Invites

Invite candidates

POST /api/v1/roles/{roleId}/invites (scope write:invites) takes candidates — each with full_name, email, and optionally phone, source, external_ref and country — at most 100 per request. A row that fails is reported in the answer (invalid, with the field), never as a 422 for the whole request. The role must be active (guide approved), and the workspace needs credits: one credit is used per billable completed interview.

Send delivery to choose who delivers the link:

• recruit100x — we email the invite and a reminder before it expires ("reminders": false turns the reminder off);
• return_link — you deliver it: each invited row returns screen_url once (a replay of the same Idempotency-Key answers screen_url_redacted: true; the link is never stored by us in a readable form);
• workspace_default — whichever of the two your workspace chose.

Sending delivery also adds invite_id, expires_at and external_ref to each row, and the statuses duplicate (the candidate already has a live invite for this role) and held. Without delivery the answer keeps its original shape.

"hold_until_ready": true (with recruit100x delivery) holds candidates while the guide is not approved yet and invites them the moment it is.

Invite statuses

An invite is created, sent, opened, consented, in_progress, completed, expired, expired_incomplete, cancelled, alternative_requested or declined.

One invite

• GET /api/v1/invites/{inviteId} (scope read:roles) — status, expiry, delivery, the door it came through, your external_ref.
• POST /api/v1/invites/{inviteId}/link (scope write:invites) — a new screen_url for a live return_link invite, for when you lost the first one. The original link keeps working.
• POST /api/v1/invites/{inviteId}/cancel (scope write:invites) — stops reminders and cancels an unstarted invite; every link to it stops working. Cancelling again answers the same.

These three routes need an Idempotency-Key header.