Roles

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.

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.