Invite a candidate to an interview
Invites the candidate of a completed report to an AI interview and answers 202 with the interview in invited; the interview is prepared in the background. Follow it with GET /v1/interviews/{id} or the interview.* webhooks. Credits or monthly quota are reserved now, with the same price and limits as in the app. With sendEmail: false the response carries invitationUrl, the candidate's personal link, and only this response does; send an Idempotency-Key so a retry returns it again.
Required scope: interviews:write.
Errors
- 400:
invalid_content_type,invalid_idempotency_key,invalid_json,request_body_too_large,unknown_field - 401:
authentication_required,invalid_api_key - 402:
insufficient_credits,price_exceeds_max,quota_exceeded - 403:
api_access_disabled,insufficient_scope - 404:
report_not_found - 409:
idempotency_key_reused,idempotency_request_in_progress,interview_exists,interview_in_progress,job_closed,report_not_completed - 422:
candidate_email_missing,invalid_parameter - 429:
rate_limit_exceeded - 500:
api_error - 503:
maintenance_mode,service_unavailable
ApiKeyAuthorizationBearer <probb_live_<id>_<secret>>Idempotency-Key?stringMakes retries safe. Repeating a request with the same key and body within 24 hours returns the original response with Idempotent-Replayed: true. The same key with a different body, or from a different API key, returns idempotency_key_reused.
1 <= length <= 255application/json- body
reportId*stringThe completed report to interview the candidate for. A report that is still running or needs review is report_not_completed.
1 <= length <= 200email?stringWhere to send the invitation. Defaults to the candidate's email; if there is none, the request fails with candidate_email_missing.
emaillength <= 254sendEmail?booleanWhether Probb emails the invitation. Send false to receive the candidate's link in invitationUrl and deliver it yourself.
truereplaceExisting?booleanReplace the report's current interview with this one. The old interview becomes cancelled. Without it, a report that already has an interview in play or finished is interview_exists. An interview the candidate has started cannot be replaced.
falsemaxCredits?numberThe most credits you allow this to cost. If the current price is higher the request fails with price_exceeds_max and nothing is charged. Read the price from GET /v1/organization.
0 < value <= 1000000Success.
application/json- response
object*stringid*stringThe interview's ID. It stays the same when the invitation is re-sent.
reportId*stringThe report the interview was created for.
candidate*|The candidate interviewed. Null if the candidate was deleted.
job*|The job interviewed for. Null if the job was deleted.
status*stringinvited from the invitation until the candidate starts (the interview is prepared in the background), in_progress, evaluating once the candidate has finished and scoring runs, completed when the evaluation is ready, expired if the invitation lapsed unused, cancelled if it was cancelled or replaced, and failed with a failureCode.
"invited""in_progress""evaluating""completed""expired""cancelled""failed"failureCode*|Why the interview failed, when status is failed. invitation_failed means the email could not be delivered; the interview is otherwise intact and can be re-sent.
invitation*How the candidate was invited.
reminders*The reminder emails for an invitation the candidate has not started. At most two go out. Change the schedule with PATCH /v1/organization/interview-reminders; to nudge a candidate now, resend the interview.
interviewVersion*stringThe interview version the candidate takes. It never changes.
createdAt*stringWhen the interview was created.
date-timeupdatedAt*stringWhen the interview last changed.
date-timeexpiresAt*stringWhen the invitation stops working if unused.
date-timestartedAt*|When the candidate started.
completedAt*|When the candidate finished.
invitationUrl*|The candidate's personal link, only when you sent sendEmail: false, and only in this response (an idempotent replay returns it again). Anyone with the link can take the interview, so treat it as a secret. Null when Probb emailed the invitation.
# Set PROBB_URL and PROBB_API_KEY. Replace any *_VALUE placeholder and any example ID (such as job_example) with a real one.# Idempotency-Key is optional. Reuse the same key and body when retrying one logical write.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": "rep_example", "sendEmail": true, "maxCredits": 10}'{ "object": "interview", "id": "string", "reportId": "string", "candidate": { "id": "string", "name": "string" }, "job": { "id": "string", "title": "string" }, "status": "invited", "failureCode": "preparation_failed", "invitation": { "email": "string", "emailStatus": "queued", "sentAt": "2019-08-24T14:15:22Z" }, "reminders": { "optedOut": true, "nudgeSentAt": "2019-08-24T14:15:22Z", "lastCallSentAt": "2019-08-24T14:15:22Z", "nextReminderAt": "2019-08-24T14:15:22Z", "nextReminderKind": "nudge", "inactiveReason": "org_disabled" }, "interviewVersion": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "expiresAt": "2019-08-24T14:15:22Z", "startedAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z", "invitationUrl": "string"}