Create Interview
Creates an interview for a candidate using an existing or inline candidate/agent/job, scoped to the API key’s company. Respects company billing limits and subscription plans. Set isTest=true to create a test interview that immediately completes without consuming billing minutes.
Overview
The create interview endpoint allows you to schedule AI-powered interviews with candidates. You can use existing candidate and agent IDs, or create them on-the-fly using inline definitions. Interviews can be scheduled for a future time or started immediately.Use Cases
- Scheduled Interviews: Schedule interviews for a specific date and time
- Immediate Interviews: Start interviews right away for quick screening
- Inline Resources: Create interviews without pre-creating candidates or agents
- Bulk Interview Scheduling: Automate interview scheduling for multiple candidates
Inline Candidate, Agent, and Job Support
You can create interviews with candidates, agents, and jobs that don’t exist yet by providing inline resource objects. This enables streamlined interview scheduling without pre-creating resources in your system.Inline Candidate with Job Association
Inline Candidate with Inline Job
Create both the candidate and job inline for a completely self-contained interview creation:candidate with
job: - A new Job entity is created in your company - A new
Candidate entity is created and automatically associated with the new job- The Interview is linked to both the new candidate and job - All resources become permanent entities in your system - This is the most streamlined way to schedule interviews without any pre-existing resources
Inline Candidate without Job Association
job at the DTO level to create a new job -
Reference existing: Use jobId at the DTO level to link to an existing
job - Within inline candidate: Use jobId inside candidate
for a more compact syntax when creating both candidate and job association -
No job: Omit all job fields to create a candidate in your talent pool
without job association (can be assigned later via the update candidate
endpoint) Priority: When
multiple job sources are provided, job takes precedence over
DTO-level jobId, which takes precedence over candidate.jobId.
XOR Validation: You cannot combine candidate.jobId with DTO-level
job fields (jobId or job) as this would be ambiguous. Choose one
method per request.Generic Focus and Jobless Interviews
Generic focus agents are designed for interviews where candidates don’t need to be assigned to a specific job. This is useful for:- Talent Pool Building: Interviewing candidates for future opportunities without a specific role
- General Outreach: Engaging with candidates in your database who aren’t currently assigned to jobs
- Pre-screening: Conducting initial conversations before matching candidates to specific positions
Creating a Jobless Interview with GENERIC Focus
400 Bad Request error if:- You use a GENERIC focus agent with a candidate that has job assignments
- You try to create a jobless interview (no job specified) with a non-GENERIC agent
Existing Candidate with Inline Job
You can also define the job inline usingjob when you already have a candidate but don’t want to create a separate job resource first.
job together with an
existing candidateId, the API: - Creates a full Job entity in your
company using the inline fields. - Automatically associates the candidate
with the new job if they weren’t already linked. - Links the interview to this
newly created job. - jobId and job are mutually exclusive (XOR): -
Use either jobId (existing job) or job (inline job
definition), but not both.Billing and Limits
Scheduling Options
Immediate Interview
OmitscheduleTime to start the interview immediately:
Scheduled Interview
Provide a futurescheduleTime timestamp (max 30 days in the future):
Job Selection for Existing Candidates
When using an existingcandidateId, you can optionally specify a jobId to indicate which job the interview is for. This is especially important when a candidate is associated with multiple jobs.
Candidate with Single Job
If the candidate has only one job (or no jobs), thejobId field is optional. The system will automatically use the candidate’s first job if available:
Candidate with Multiple Jobs
When a candidate is associated with multiple jobs, you must specify thejobId to indicate which job the interview is for:
jobId you provide must belong to the same company as your API key. If the candidate is not already assigned to this job, they will be automatically assigned to it when the interview is created.jobId and job are XOR (mutually exclusive): - If you
provide jobId, you must omit job. - If you provide
job, you must omit jobId. - When job is used: - A new
job is created for your company. - That job is used as the interview’s
jobId. - The candidate is associated with that job automatically before the
interview is created.Company Isolation
All resources (candidate, agent, job) must belong to the same company as your API key. The API automatically validates company ownership and returns403 Forbidden if resources belong to different companies.
Complete Workflow Examples
Scenario 1: Interview with Job Association
Scenario 2: Interview without Job Association (Talent Pool)
Scenario 3: Interview for Candidate with Multiple Jobs
Scenario 4: Existing Candidate with Inline Job
jobId returned in the interview
object.Test Mode
Test mode allows you to create test interviews that immediately complete without consuming billing minutes. This is useful for testing webhook handlers and integration flows.When to Use Test Mode
- Testing Webhook Handlers: Verify that your webhook endpoints correctly handle
interview.completedandanalysis.completedevents - Integration Testing: Test your application’s interview processing logic without waiting for real interviews
- Development: Develop and debug features that depend on completed interviews
- Demo Purposes: Create sample interviews for demonstrations
How Test Mode Works
When you setisTest: true:
- Billing Bypass: All billing checks are skipped - no minutes are consumed
- Immediate Completion: The interview is created with
COMPLETEDstatus immediately - Mock Analysis Data: Realistic screening analysis data is automatically generated and stored
- Webhook Events: Both
interview.completedandanalysis.completedwebhook events are triggered - Default Duration: Test interviews have a default duration of 5 minutes
Example: Creating a Test Interview
Test Interview Characteristics
- Status: Always
COMPLETEDimmediately - Duration: 5 minutes (300 seconds)
- Analysis: Includes mock screening analysis with:
- Conversation check results (candidateInterest: true, conversationCompleted: true)
- Candidate analysis scores and recommendations
- Mock transcript segments
- Webhooks: Triggers both
interview.completedandanalysis.completedevents - Billing: No minutes consumed, no billing checks performed
isTest: true in their metadata. They appear in interview lists and can be queried like normal interviews, but they do not affect billing or production metrics.Related Resources
Interviews Resource Guide
Agents Resource Guide
Candidates Resource Guide
Billing Guide
Webhooks Guide
Authorizations
API key for authentication using Bearer scheme
Query Parameters
Required for ATS API keys to specify which company to access. Ignored for standard company API keys.
Body
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
Existing candidate ID (XOR with candidate). Must exist and belong to the same company as the API key. Existence/company relationship is validated server-side.
"123e4567-e89b-12d3-a456-426614174000"
Job ID to associate the interview with (XOR with job). Required when candidate has multiple job assignments and no job is provided. Must belong to the API key's company. If the candidate is not already assigned to this job, they will be automatically assigned.
"123e4567-e89b-12d3-a456-426614174000"
Existing agent ID (XOR with agent). Must exist and belong to the same company as the API key. Existence/company relationship is validated server-side.
"987e6543-e21b-12d3-a456-426614174000"
Scheduled time in ISO 8601 format (max 30 days in future)
"2025-11-20T10:00:00Z"
Job for inline creation (XOR with jobId). When provided, a new job will be created and used for the interview. Cannot be combined with jobId.
Candidate for inline creation (XOR with candidateId)
Agent for inline creation (XOR with agentId)
- Option 1
- Option 2
Custom metadata for the interview (max 10KB, 5 levels deep, 50 keys)
{
"externalInterviewId": "INT-789",
"interviewerNotes": "Focus on technical skills"
}If true, creates a test interview that immediately completes without consuming billing minutes. Triggers webhook events (interview.completed, analysis.completed) for testing webhook handlers.
false
Response
OK (legacy; prefer 201)
Interview ID
"123e4567-e89b-12d3-a456-426614174000"
Candidate ID
"987e6543-e21b-12d3-a456-426614174000"
Agent ID
"456e7890-e12b-34d5-a678-901234567890"
Interview status
UNDEFINED, SCHEDULED, CANCELLED, FAILED, COMPLETED, IN_PROGRESS "SCHEDULED"
Scheduled time
"2025-11-20T10:00:00Z"
Created timestamp
"2024-11-16T10:30:00Z"
Updated timestamp
"2024-11-16T10:30:00Z"
Job ID associated with this interview, if any
"123e4567-e89b-12d3-a456-426614174000"
Interview duration in minutes
15
Finished date
"2025-11-20T10:15:00Z"
Custom metadata
{ "externalInterviewId": "INT-789" }Call attempt logs for this interview. Present for phone interviews, typically empty or undefined for online interviews.
Candidate analysis data. Present only if analysis has been generated.
Whether this is a test interview. Test interviews are created with isTest=true, immediately complete without consuming billing minutes, and are excluded from billing/usage summaries. Use test interviews for testing webhook handlers and integration flows.
false