# Roles > Create a role from a job description (text or a link), follow its interview guide to approval, and set its open screening link. ## Create a role `POST /api/v1/roles` (scope `write:roles`, `Idempotency-Key` required) takes the job description as `{"mode": "paste", "text": …}` or `{"mode": "url", "url": …}`; the title is read from it when you don't send one. Optional: `client_label` (shown to candidates; omit to keep the client confidential), `location.country`, a compensation range, must-haves, knock-out rules, `jurisdiction_preset`, `invite_expiry_days`, `open_link`, `external_ref` (your id for the role) and `auto_approve`. A role in the EU/EEA or outside the countries Recruit100x screens for is refused with `422 ROLE_COUNTRY_NOT_SUPPORTED`. A link we can't read is `422 JD_FETCH_FAILED` — send the text instead. ## The interview guide A new role is a `draft` whose guide is being drafted. `guide_status` moves through: - `drafting` — the guide is being written from the job description; - `pending_approval` — ready for a person on your team to approve (in the dashboard or from the approval email); - `approved` — the role is `active` and candidates can be invited; `role.ready` is sent; - `failed` — the guide could not be written (`role.guide_failed`); - `not_requested` — no guide was requested. `auto_approve: true` approves a guide that passes every check, for trusted workspaces with auto-approval turned on. ## Change or close a role `PATCH /api/v1/roles/{roleId}` changes the job description, title or client label while the guide is not approved (afterwards `409 ROLE_GUIDE_APPROVED`), closes or reopens the role (`status`), and changes the open link. Closing cancels unstarted invites unless you send `"open_invites": "keep"`. ## Open screening link settings `open_link` sets the role's public link: `policy` (`open`, `applicants_only`, `invite_only`, `off`), `cap` (interviews the link may start; default 200), `expires_at`, and on PATCH `regenerate: true` (the old link stops at once). Omitted on create, the role gets your workspace's default policy, which is open unless you changed it. See [Open screening link](/developers/open-link). ## Read roles `GET /api/v1/roles` lists your roles with counts (filter `?status=draft|active|closed`); `GET /api/v1/roles/{roleId}` reads one, including `guide_status`, `open_link`, `external_ref` and `dashboard_url`.