Invite and follow an interview

Use this workflow after a report has a usable completed analysis. Your backend needs interviews:write for invitation actions and interviews:read to track state and retrieve results.

Quote and inviteCopy Anchor Link

With interviews:write, POST this body to /api/v1/interview-quotes:

{ "reportId": "REPORT_ID", "candidateEmail": "candidate@example.test", "sendEmail": true }

POST the same fields plus quoteFingerprint from the quote to /api/v1/interviews, with a stable Idempotency-Key. A 202 returns interviewId, statusUrl, and delivery status. With sendEmail: true, invitationToken is null. Set sendEmail: false only when your own system will deliver the candidate link /interview/{invitationToken}; the response then includes the private invitation credential. Replay only recovers a credential for an eligible current invitation; old links cannot enter a replacement attempt.

Poll /api/v1/interviews/{id}/status using interviews:read, or subscribe to the interview events. Interpret the four axes independently:

completed means candidate completion; evaluation: ready means the report can be read at /api/v1/interviews/{id}/result?schemaVersion=1. This response includes strengths, concerns, evidence, requirement confidence/coverage where supported, integrity indicators, and review limitations. Skill scores use 0–10 and readiness uses 0–100; missing measurements are null. It excludes raw transcripts and audio.

POST /api/v1/interviews/{id}/resend with a new idempotency key to queue another email for an eligible pending attempt. Resend preserves the current credential and does not charge for a new interview. Provider acknowledgements can be lost, so email may be duplicated. sent means provider acceptance, not inbox delivery.

For another interview, obtain a fresh quote and POST the invitation body to /api/v1/interviews/{id}/reinterview with a new key. This creates a new logical attempt and preserves the old public result. An in-progress interview cannot be replaced. Versions are captured at admission; a platform reassignment does not rewrite an existing attempt.

Complete request sequenceCopy Anchor Link

Supply PROBB_URL, PROBB_API_KEY, and REPORT_ID from your environment and prior analysis. Use a new INVITE_KEY for this intentional invitation; retain it for retries.

jq -n --arg report "$REPORT_ID" \
  '{reportId:$report,candidateEmail:"candidate@example.test",sendEmail:true}' > interview-quote-input.json
curl --fail-with-body "$PROBB_URL/api/v1/interview-quotes" \
  -H "Authorization: Bearer $PROBB_API_KEY" -H 'Content-Type: application/json' \
  --data-binary @interview-quote-input.json > interview-quote.json
jq --arg fp "$(jq -r '.data.fingerprint' interview-quote.json)" \
  '. + {quoteFingerprint:$fp}' interview-quote-input.json > interview-input.json
curl --fail-with-body "$PROBB_URL/api/v1/interviews" \
  -H "Authorization: Bearer $PROBB_API_KEY" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $INVITE_KEY" --data-binary @interview-input.json > invitation.json
INTERVIEW_ID=$(jq -r '.data.interviewId' invitation.json)
curl --fail-with-body "$PROBB_URL/api/v1/interviews/$INTERVIEW_ID/status" \
  -H "Authorization: Bearer $PROBB_API_KEY"

Do not send example invitations to real recipients while testing; use the isolated sandbox. For self-delivery, change sendEmail before quoting, securely construct the candidate link on the application origin, and deliver it only to the intended candidate.

Choose the right follow-upCopy Anchor Link

Interview events can replace routine polling. The candidate guide explains microphone, consent, and recovery instructions for recipients.