# Create a role

Create a role (job) in an organization. Scope: roles:write.

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

```bash
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](/docs/api/pipeline/roles-get/)).

## 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. |