Reference

Authentication, enums, error handling, and the pre-launch checklist. Keep this page open while you build.

---

Authentication

Every endpoint on both the Interview API and the Webhook management API is authenticated by the same header:

x-application-secret-key: <secret-key>

Keys are issued by the Allps team and look like sk_int_<32-character-urlsafe-token>. The same header carries:

• User API keys — bound to an AppUser, scoped to that user's interviews.
• Static service secrets — for platform integrations (talent, allps, video_analyzer, media_service).

Rate limiting

Each key has a per-minute limit (default 25 req/min). Exceeding it returns 429 Too Many Requests. The window resets every 60 seconds.

Revocation

If a key is compromised, contact the Allps team to deactivate it. All subsequent requests return 401. Key management shall be available in over the API soon.

---

Enums

AgentLanguages

The language Allps speaks and evaluates in. Pass as language_code (or interview_lang_code on screening endpoints).

Value	Language
1	English
2	German
3	Hindi
4	Swiss German
5	French
6	Spanish
7	Danish
8	Swedish
9	Arabic

InterviewTypes

Controls which pipeline processes the interview and which evaluation shape you get back.

Value	Name	Description
0	JOB_INTERVIEW	Standard job interview. Per-question ratings plus an LLM overall summary.
1	SCREENING_INTERVIEW	You provide qualifying / information questions. Boolean outcomes plus a communication analysis.
2	VIDEO_INTRODUCTION_INTERVIEW	Short video-intro flow. No evaluation — media hand-off only.

InterviewState

Visible as state in GET /interview/details/{id}.

Value	Name	Meaning
0	NOT_STARTED	Created but not yet opened by the candidate.
1	ONGOING	Currently in progress.
2	ENDED	Terminal success state. Stop polling.
3	ERROR	Unrecoverable error.
4	AWAITING_INTRODUCTION	Waiting for the candidate's self-introduction.
5	READY_FOR_NEXT_QUESTION	AI is deciding the next question.
6	AWAITING_ANSWER	AI has asked a question, waiting for the candidate.
7	ALL_QUESTIONS_ASKED	All questions complete; winding down.
8	READY_FOR_FEEDBACK	Preparing closing feedback.
9	AWAITING_CANDIDATE_QUESTIONS	Waiting for the candidate to ask their own questions.
10	NEEDS_FOLLOW_UP	AI is generating a follow-up.
11	REPEAT_CURRENT_QUESTION	Repeating the current question.

Integration shortcut

States 4–11 are transient and only meaningful while the interview is effectively in progress. For your integration, treat anything in {0, 1, 4–11} as "not done yet" and only 2 as done.

EndingReason

Visible as ending_reason in GET /interview/details/{id}.

Value	Name	Meaning
0	NOT_ENDED_BECAUSE_NOT_STARTED	Interview never began.
1	INTERVIEW_COMPLETED	Success case — all questions asked and answered.
2	USER_ENDED	Candidate ended the session deliberately.
3	ENDED_DUE_TO_USER_INACTIVITY	No speech for an extended period.
4	ENDED_DUE_TO_USER_UNCOOPERRATIVE	Repeated uncooperative behaviour.
5	ENDED_DUE_TO_ERRROR	Backend error.
6	ENDED_DUE_TO_FRONTEND_ERRROR	Frontend-side failure.
7	ENDED_DUE_TO_EXCEEDED_RESUME_COUNT	Session resumed too many times.
8	USER_ENDED_DUE_TO_ERROR	Candidate chose to quit after an error.

Route non-clean endings to a review queue

For a hiring decision, treat ending_reason == 1 as the only clean interview. Everything else should be reviewed manually or rescheduled.

ArchivalStatus

Indicates whether recordings have been processed and uploaded.

Value	Name	Meaning
0	NOT_STARTED	Nothing archived yet.
1	ARCHIVED	All artefacts uploaded to cloud storage.
2	ONGOING	Recording is being created.
3	ERROR	Archival failed.
4	RECORDING_CREATED	Local recording exists but not yet uploaded.

Poll until archival_status == 1 before requesting recordings (if you aren't relying on webhooks).

Suitability

The verdict in overall_assessment.suitability. Always returned in English, regardless of interview language, so you can safely switch on it.

Value	Suggested action
"Exceeds expectations"	Fast-track to next round.
"Meets expectations"	Standard progression.
"Below expectations"	Reject or consider for a different role.
"Needs further assessment"	Insufficient signal — schedule a follow-up.

Per-question rating (job interviews only)

Value	Meaning
SUBOPTIMAL	Missed the core of the question.
OKAY	Partial answer.
GOOD	Solid, on-topic answer.
EXCELLENT	Comprehensive, insightful answer.

Question types

Used in questions[].type on create-from-questions and in the evaluation report's q_type.

Value	Description
"technical"	Tests hard skills and domain knowledge.
"behavioral"	Past-tense "tell me about a time" questions.
"situational"	Hypothetical "what would you do if" questions.
"qualifying"	Yes/no screening questions. Screening interviews only.
"information"	Fact-gathering questions. Screening interviews only.

experience_level / difficulty_level

experience_level	Meaning		difficulty_level	Meaning
"junior"	0–2 years.		"easy"	Entry-level.
"senior"	3–7 years.		"medium"	Standard mid-level.
"assistant"	Support role.		"hard"	Advanced, with follow-ups.
"intern"	Internship.

Webhook events and kinds

Events:

Value	Meaning
interview.media_processed	Emitted after media processing completes. Carries transcript, evaluation, recording URLs.
webhook.test	Synthetic event for receiver validation.

Interview kinds (value of interview.kind in a webhook payload):

Value	Numeric interview_type
job_interview	0
screening_interview	1
video_introduction	2

Webhook delivery status codes (visible in GET /webhooks/deliveries):

Value	Name
0	PENDING
1	DELIVERING
2	SUCCESS
3	FAILED

---

Error handling

HTTP status codes

Status	Meaning	Typical cause
200	Success	—
201	Created	Webhook endpoint registered.
204	No content	Webhook endpoint deleted.
401	Unauthorized	Missing / invalid x-application-secret-key; expired JWT.
403	Forbidden	Key valid but lacks permission for this route.
404	Not found	Invalid interview_id / endpoint_id, or resource not yet generated.
409	Conflict	Duplicate interview, candidate already verified, etc.
422	Validation error	Request body failed Pydantic validation. Response includes per-field detail.
429	Too many requests	Rate limit exceeded. Retry after 60 s.
500	Server error	Allps-side failure. Retry with backoff; escalate if persistent.

Error identifiers

Errors are returned as { "detail": "<human-readable-message>" }. A few you will actually see:

Message	Meaning	Recommended action
InterviewNotExist	Bad interview id.	Verify the id.
InterviewNotEndException	Interview hasn't finished; no report yet.	Keep polling.
EvalReportGenerationException	Not all questions were answered.	Check ending_reason; schedule a retake.
RecordingCreationException	Recording still being processed.	Retry with exponential backoff.
RateLimitReachedException	Over your per-minute quota.	Sleep 60 s.
TokenExpiredException	JWT / API key expired.	Refresh and retry.
InsecureWebhookURLNotAllowed	http:// rejected because WEBHOOK_ALLOW_INSECURE_HTTP=false.	Use https://.

---

Idempotency

Create endpoints are not idempotent

Retrying POST /interview/create-from-questions after a network timeout can create a duplicate interview.

To avoid duplicates:

• Use short timeouts (5–10 s) so you know quickly whether a request landed.
• Only retry on 5xx. Never retry a timeout where you're unsure whether the request completed — the correct move is to reconcile, not to retry.
• Include a unique correlation id in your own system alongside the returned interview_id so you can detect duplicates during reconciliation.

Webhook deliveries are idempotent by default. Re-dispatching an event whose delivery already succeeded is a no-op; the payload's event_id is a deterministic key you can use to de-duplicate on your side.

---

Integration checklist

Before you go live.

Credentials and environment

• [ ] Received an API key from the Allps team; stored it in your secret manager.
• [ ] Confirmed the key's rate limit matches your expected traffic.
• [ ] Confirmed the correct base URL for staging vs. production.

Core integration

• [ ] Successfully created a test interview end-to-end.
• [ ] Shared the interview_link with a real candidate and seen the interview complete.
• [ ] Implemented a poll loop that stops on state == 2, or registered a webhook and skip polling.
• [ ] Fetched and parsed a real transcript.
• [ ] Fetched and parsed a real evaluation report; your code handles both the job-interview short form and the screening/video long form.
• [ ] Fetched a recording URL and confirmed your storage strategy does not persist the URL itself.
• [ ] Verified the interview is conducted and evaluated in the language you expect (language_code).

Error handling

• [ ] Retry logic handles 429, 500 RecordingCreationException, and 404 InterviewNotEndException.
• [ ] ending_reason == 1 is the only "clean" interview in your hiring workflow; everything else routes through a review queue.

Webhooks (if used)

• [ ] Registered an endpoint and stored the one-time secret.
• [ ] Receiver verifies X-Webhook-Signature with HMAC-SHA256 over "{timestamp}.{body}".
• [ ] Enforced a timestamp replay window (typically 5 minutes).
• [ ] Using event_id as an idempotency key.
• [ ] Tested with POST /webhooks/endpoints/{id}/test; the webhook.test delivery succeeded.
• [ ] Read the catalogue (GET /webhooks/catalog) and confirmed your receiver handles every interview.kind you registered for.
• [ ] Receiver returns 2xx quickly — heavy processing is deferred.
• [ ] Bookmarked GET /webhooks/deliveries and POST /webhooks/deliveries/{id}/redeliver for operations.