Invite a candidate
Create an interview attempt and prepare its questions. ProBB AI can send the invitation email, or your own system can deliver the candidate link.
Before you call
Obtain a current interview quote and send the same details plus quoteFingerprint with a stable Idempotency-Key. The workspace must have interview allowance.
Required scope: interviews:write.
What happens next
A 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.
Recovery
Repeat the same body/key after a timeout. A returned token is a bearer credential; never log it. Replays only recover an eligible current pending invitation. Use resend for another email and reinterview for a new attempt.
Follow the complete workflow · Errors and retries
ApiKeyAuthorizationBearer <token>Idempotency-Key*stringStable key for one logical write. Retry the identical body with the same key after a timeout; a changed body conflicts. 1–128 letters, digits, dots, underscores, colons, or hyphens.
^[A-Za-z0-9._:-]+$1 <= length <= 128application/json- body
reportId*stringReport ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
1 <= length <= 100candidateEmail*stringEmail address of the intended candidate. The quote and invitation must use the same address.
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$emailsendEmail?booleanTrue (default) asks ProBB AI to email the invitation. False returns a private link credential for your system to deliver. Invitation batches require true.
truequoteFingerprint*stringFingerprint copied unchanged from the corresponding current quote. Changing quote inputs requires a new quote.
^[a-f0-9]{64}$A 202 returns interviewId and statusUrl. With sendEmail=true, invitationToken is null. With false, securely deliver /interview/{invitationToken} on the application origin yourself. Preparation and email delivery proceed independently.
application/json- response
data*# Set PROBB_URL and PROBB_API_KEY. Replace RESOURCE_ID if present.# Set REQUEST_KEY once for this logical write; reuse it with the same body on retries.curl --fail-with-body -X POST "$PROBB_URL/api/v1/interviews" \ -H "Authorization: Bearer $PROBB_API_KEY" \ -H "Idempotency-Key: $REQUEST_KEY" \ -H 'Content-Type: application/json' \ --data-binary '{ "reportId": "report_example", "candidateEmail": "candidate@example.test", "sendEmail": true, "quoteFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'{ "data": { "interviewId": "interview_example", "reportId": "report_example", "invitationToken": null, "statusUrl": "/api/v1/interviews/interview_example/status", "emailDelivery": "queued" }}