Create a role

Creates a role (job) in a target organization. Scope: roles:write. Requires employer-write authority in organizationId (admins bypass). The role is created with its default pipeline steps and, where applicable, HR-rep assignment.

Request body

Field	Type	Required	Description
name	string	Yes	Role title.
organizationId	string	Yes	Organization to create the role in.
description	string	No	Role description.
department / location / workType	string	No	remote / hybrid / onsite for workType.
priority / roleLevel / status	string	No	Metadata.
salaryMin / salaryMax / targetHireCount	integer	No	Numbers.
salaryCurrency / salaryPeriod	string	No	Salary currency / period.
isPublic	boolean	No	Whether the role is public.

Example request

curl -X POST https://app.talent-ray.com/api/v1/roles \
  -H "Authorization: Bearer tr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Senior Backend Engineer", "organizationId": "org_acme", "department": "Engineering", "workType": "remote" }'

Response

201 Created — the created role (same shape as Get a role).

Status codes

Status	Meaning
201	Created.
400	bad_request — missing/invalid fields.
401	No valid API key.
403	insufficient_scope (missing roles:write) or forbidden (no write authority in the target org).
429	Rate limit / usage limit exceeded.