List roles

Lists roles (jobs) your key can see, in the stable v1 shape. Scope: roles:read. Visibility: admins all; employer-write members see their org’s roles (confidential roles only if they’re the HR rep or hiring manager); hiring managers see assigned roles.

Query parameters

Parameter	Type	Required	Description
page	integer	No	0-indexed page. Default 0.
pageSize	integer	No	Rows per page (max 100). Default 20.
organizationId	string	No	Filter to a single organization.
status	string	No	Filter by role status.

Example request

curl "https://app.talent-ray.com/api/v1/roles?status=open" \
  -H "Authorization: Bearer tr_YOUR_KEY"

Response

200 OK

{
  "data": [
    {
      "id": "role_eng_be",
      "name": "Senior Backend Engineer",
      "organizationId": "org_acme",
      "status": "open",
      "priority": "high",
      "isPublic": true,
      "department": "Engineering",
      "location": "Remote",
      "workType": "remote",
      "salaryMin": 90000,
      "salaryMax": 120000,
      "salaryCurrency": "EUR",
      "salaryPeriod": "year",
      "targetHireCount": 2,
      "roleLevel": "senior",
      "createdAt": "2026-05-01T09:00:00Z",
      "updatedAt": "2026-06-01T09:00:00Z"
    }
  ],
  "pagination": { "page": 0, "pageSize": 20, "totalCount": 12, "totalPages": 1 }
}

Status codes

Status	Meaning
200	Success.
401	No valid API key.
403	insufficient_scope — the key lacks roles:read.
429	Rate limit exceeded.