Getting started
API documentation
Connect your ATS or your own software to NuViOLive: create jobs and candidates, schedule AI interviews, and collect recordings and evaluations as soon as an interview finishes.
Base URL
Every endpoint below is relative to this address. Requests and responses are JSON over HTTPS.
https://interview-platform-566637628639.asia-south1.run.app/api/v2
What you can do
- Jobs and candidates: create and update job descriptions and candidate profiles. A candidate can carry a link to its resume, which is stored for you (not fetched); resume text goes in
summary(up to 16,000 characters). - Interviews: schedule interviews for up to 100 candidates in one request, each with its own join link and passcode, and cancel them. We email the link and passcode to each candidate only when you ask us to (
send_invite). - Results: fetch the recording and the evaluation of a completed interview, or receive them by webhook the moment the analysis finishes.
- Credits: read what you can book with, what booked interviews hold and what expires soon, and the current rates, before you book (Credits).
Getting started
Quickstart
From a new API key to a scheduled interview in four steps.
-
Create an API key
On API Access, choose Create key. The full key is shown once: store it in your secret manager, and keep it on your server. Never put it in a browser or a mobile app.
Terminalexport NUVIO_API_KEY="nuv_xxxxxxxx.yyyyyyyyyyyyyyyy" -
Check the key
GET /medescribes the key in use. A200means you are ready.curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/me" \ -H "X-API-Key: $NUVIO_API_KEY"import os import requests response = requests.get( "https://interview-platform-566637628639.asia-south1.run.app/api/v2/me", headers={"X-API-Key": os.environ["NUVIO_API_KEY"]}, timeout=30, ) response.raise_for_status() print(response.json()["data"])const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/me", { method: "GET", headers: { "X-API-Key": process.env.NUVIO_API_KEY, }, }); const { data } = await response.json(); -
Create a job and a candidate
Create the job with
POST /jobs, then add the candidate to it withPOST /candidates. Each response returns the new record's id. -
Schedule the interview
POST /schedulesbooks the interview and returns the candidate's join link and passcode. Send them to the candidate yourself, or add"send_invite": trueand we email them. When it is over, the webhook delivers the evaluation.
Getting started
Authentication
Every request carries your API key in a header.
X-API-Key: nuv_<prefix>.<secret>
A key belongs to your organization, not to a person: it can read and change every job, candidate and schedule in the organization. Only the organization account can create or revoke keys, on API Access. A revoked or expired key stops working at once.
Keep keys server-side. Anyone with the key can act as your organization through the API.
Scopes
A key carries one or both scopes; each endpoint names the one it needs.
| Scope | Grants |
|---|---|
interviews:read | Reading jobs, candidates, schedules, prompt sets, join links, recordings and credits. |
interviews:write | Creating and updating jobs, candidates and schedules; cancelling schedules; requesting a report. |
Rate limits
Each key has its own per-minute limit, set when the key is created and shown by GET /me as rate_limit_per_minute. Going over it returns 429 with a Retry-After header: wait that many seconds, then retry.
When a key is refused
| Status | Code | Why |
|---|---|---|
401 | unauthorized | The header is missing, the key is malformed, unknown, revoked or expired. |
403 | forbidden | API access is switched off for the organization, the organization is inactive, or the key lacks the endpoint's scope. |
403 | plan_excludes_api | The organization's plan does not include API access. |
Getting started
Requests and responses
Every response has the same envelope, so one client handles them all.
Response envelope
A success wraps the result in data; an error puts a machine-readable code and a readable message in error. Every response carries a request_id: quote it when you contact support.
{
"data": { "...": "..." },
"meta": { "request_id": "req_8f3c..." }
}
{
"error": {
"code": "not_found",
"message": "Interview not found.",
"details": {}
},
"meta": { "request_id": "req_8f3c..." }
}
A record that belongs to another organization answers 404, never 403: even whether it exists is not shared.
Pagination
The list endpoints (/jobs, /candidates, /schedules, /credits/lots, /credits/holds) take limit (1–200, default 50) and offset (default 0), and describe the page in meta. Keep requesting with offset + returned while has_more is true.
"meta": {
"request_id": "req_8f3c...",
"total": 412,
"limit": 50,
"offset": 0,
"returned": 50,
"has_more": true
}
Validation
Write requests are checked strictly, so a mistake fails loudly instead of saving the wrong thing. A rejected request answers 422 validation_error naming the field.
- Unknown fields are rejected.
requiredSkillsinstead ofrequired_skillsis an error, not a job with no skills. - Lists take at most 100 entries of at most 200 characters (
question_setentries up to 1,000). - Email must be a usable address; it is stored in lower case. When you schedule with
send_invite, this is where the invitation goes. - URLs (
url,linkedin_url,portfolio_url) must behttporhttps. - Experience is 0–60 years, and a maximum below the minimum is rejected. Graduation year is 1900–2100.
API reference
Identity
Which key is making the request.
Get the current key
/meAny key
Describes the key in use: its organization, name, scopes, prefix and rate limit. Works with any valid key.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/me" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/me",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/me", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"company_id": "5d0c...",
"name": "ATS production",
"scopes": ["interviews:read", "interviews:write"],
"key_prefix": "nuv_3f9a1c2b",
"rate_limit_per_minute": 120
},
"meta": { "request_id": "req_8f3c..." }
}
API reference
Jobs
Job descriptions: what the interview is about and what the analysis checks.
List jobs
/jobsinterviews:read
Returns the organization's jobs, newest first.
Query parameters
job_status
string
Optional
Only jobs in this status.
limit
integer
Optional
1–200, default 50.
offset
integer
Optional
Default 0.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs?limit=50&offset=0" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs?limit=50&offset=0",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs?limit=50&offset=0", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Get a job
/jobs/{job_description_id}interviews:read
Returns one job by its id. Every job response has exactly these fields:
{
"data": {
"job_description_id": "JOB_ID",
"company_id": "COMPANY_ID",
"job_title": "Senior Software Engineer",
"company_name": "Acme Corp",
"location": "Remote",
"job_type": "Full-Time",
"min_experience_years": 5.0,
"max_experience_years": 8.0,
"salary_range": null,
"required_education": null,
"required_skills": ["Python", "PostgreSQL"],
"preferred_skills": ["Docker", "AWS"],
"certifications": [],
"responsibilities": [],
"benefits": [],
"detailed_summary": null,
"manual_summary": null,
"question_set": ["Explain dependency injection."],
"status": "open",
"application_close_date": null,
"is_public": false,
"public_slug": "senior-software-engineer-1a2b3c4d",
"public_published_at": null,
"candidate_count": 0,
"created_at": "2026-10-03T05:20:00Z",
"updated_at": "2026-10-03T05:20:00Z"
},
"meta": { "request_id": "req_8f3c..." }
}
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Create a job
/jobsinterviews:write
Creates a job description and answers 201 with the new job, including its job_description_id.
Body
job_title
string
Required
2–200 characters.
company_name, location, job_type, salary_range, required_education
string
Optional
min_experience_years, max_experience_years
number
Optional
0–60; the maximum may not be below the minimum.
required_skills, preferred_skills, certifications, responsibilities, benefits
string[]
Optional
Up to 100 entries of up to 200 characters. Required and preferred skills decide how the analysis files each skill.
detailed_summary
string
Optional
Free-text description of the role.
question_set
string[]
Optional
Questions the interviewer should cover; entries up to 1,000 characters.
curl -X POST "https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_title": "Senior Software Engineer",
"company_name": "Acme Corp",
"location": "Remote",
"job_type": "Full-Time",
"min_experience_years": 5,
"max_experience_years": 8,
"required_skills": ["Python", "PostgreSQL"],
"preferred_skills": ["Docker", "AWS"],
"question_set": ["Explain dependency injection."]
}'
import os
import requests
response = requests.post(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"job_title": "Senior Software Engineer",
"company_name": "Acme Corp",
"location": "Remote",
"job_type": "Full-Time",
"min_experience_years": 5,
"max_experience_years": 8,
"required_skills": ["Python", "PostgreSQL"],
"preferred_skills": ["Docker", "AWS"],
"question_set": ["Explain dependency injection."]
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs", {
method: "POST",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"job_title": "Senior Software Engineer",
"company_name": "Acme Corp",
"location": "Remote",
"job_type": "Full-Time",
"min_experience_years": 5,
"max_experience_years": 8,
"required_skills": ["Python", "PostgreSQL"],
"preferred_skills": ["Docker", "AWS"],
"question_set": ["Explain dependency injection."]
}),
});
const { data } = await response.json();
Update a job
/jobs/{job_description_id}interviews:write
This replaces the whole job with the body you send; it is not a partial update. Send the complete object, with the same fields as Create a job.
curl -X PATCH "https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_title": "Senior Software Engineer (Platform)",
"required_skills": ["Python", "PostgreSQL", "Kubernetes"]
}'
import os
import requests
response = requests.patch(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"job_title": "Senior Software Engineer (Platform)",
"required_skills": ["Python", "PostgreSQL", "Kubernetes"]
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/jobs/JOB_ID", {
method: "PATCH",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"job_title": "Senior Software Engineer (Platform)",
"required_skills": ["Python", "PostgreSQL", "Kubernetes"]
}),
});
const { data } = await response.json();
API reference
Candidates
The people you interview, each attached to one job.
List candidates
/candidatesinterviews:read
Query parameters
job_description_id
string
Optional
Only candidates of this job.
limit
integer
Optional
1–200, default 50.
offset
integer
Optional
Default 0.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates?job_description_id=JOB_ID" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates?job_description_id=JOB_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates?job_description_id=JOB_ID", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Get a candidate
/candidates/{candidate_profile_id}interviews:read
Every candidate response has exactly these fields:
{
"data": {
"candidate_profile_id": "CANDIDATE_ID",
"company_id": "COMPANY_ID",
"job_description_id": "JOB_ID",
"full_name": "Jane Doe",
"email": "jane@example.com",
"phone": "+919876543210",
"location": null,
"current_company": null,
"current_designation": null,
"experience_years": 4.5,
"degree": null,
"university": null,
"graduation_year": null,
"gpa": "3.8",
"skills": ["Python", "React"],
"certifications": [],
"languages": [],
"linkedin_url": null,
"portfolio_url": null,
"summary": null,
"resume_url": "https://example.com/jane-resume.pdf",
"intake_source": "recruiter_upload",
"applied_at": null,
"review_status": "approved",
"reviewed_at": null,
"jd_match_score": null,
"jd_match_details": {},
"created_at": "2026-10-03T05:21:00Z",
"updated_at": "2026-10-03T05:21:00Z"
},
"meta": { "request_id": "req_8f3c..." }
}
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Create a candidate
/candidatesinterviews:write
Creates a candidate profile for one job and answers 201 with the candidate (the fields of Get a candidate). job_description_id is required; every other field is optional, but a candidate without an email cannot be sent an invitation by us (send_invite skips them).
409 conflict: a candidate with the same email or phone is already on this job (the message names them), or the job is on hold or closed.404 not_found: the job does not exist in your organization.
Body
job_description_id
string (UUID)
Required
The job the candidate applies for. It must be open for new candidates.
full_name, email, phone, location
string
Optional
The email is where the invitation goes when you schedule with send_invite.
current_company, current_designation, degree, university
string
Optional
experience_years
number
Optional
0–60.
graduation_year
integer
Optional
1950 to six years from now.
gpa
number or string
Optional
Stored as text: 3.8 is returned as "3.8".
skills, certifications, languages
string[]
Optional
linkedin_url, portfolio_url
string
Optional
http or https.
url
string
Optional
A link to the resume, http or https. It is stored and returned as resume_url; it is not fetched or read. Send resume text in summary.
summary
string
Optional
Resume text you already hold, up to 16,000 characters. This is what the interview draws on.
curl -X POST "https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_description_id": "JOB_ID",
"full_name": "Jane Doe",
"email": "jane@example.com",
"phone": "+919876543210",
"experience_years": 4.5,
"skills": ["Python", "React"],
"url": "https://example.com/jane-resume.pdf"
}'
import os
import requests
response = requests.post(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"job_description_id": "JOB_ID",
"full_name": "Jane Doe",
"email": "jane@example.com",
"phone": "+919876543210",
"experience_years": 4.5,
"skills": ["Python", "React"],
"url": "https://example.com/jane-resume.pdf"
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates", {
method: "POST",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"job_description_id": "JOB_ID",
"full_name": "Jane Doe",
"email": "jane@example.com",
"phone": "+919876543210",
"experience_years": 4.5,
"skills": ["Python", "React"],
"url": "https://example.com/jane-resume.pdf"
}),
});
const { data } = await response.json();
Update a candidate
/candidates/{candidate_profile_id}interviews:write
Like jobs, this replaces the whole profile with the body you send. A candidate stays with the job it was created for, and url is recorded only when the candidate is created.
curl -X PATCH "https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"full_name": "Jane Doe",
"email": "jane.doe@example.com"
}'
import os
import requests
response = requests.patch(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"full_name": "Jane Doe",
"email": "jane.doe@example.com"
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/candidates/CANDIDATE_ID", {
method: "PATCH",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"full_name": "Jane Doe",
"email": "jane.doe@example.com"
}),
});
const { data } = await response.json();
API reference
Schedules
Book interviews. Each candidate gets a join link and a passcode, which we email only when you set send_invite.
Schedule interviews
/schedulesinterviews:write
Books an interview for each candidate in candidate_profile_ids, all or none, and answers 201. Credits for every interview are reserved when you book. See Credits and interview types.
Body
job_description_id
string (UUID)
Required
candidate_profile_ids
string[] (UUIDs)
Required
1–100 candidates of that job.
agent
string
Required
futuremug or cloud_interview.
expected_duration_minutes
integer
Required
10–60. An interview lasts at least 10 and at most 60 minutes on either interviewer; anything else is a 422.
schedule_mode
string
Optional
fixed_datetime (default), available_24h or windowed_range; see the table below.
scheduled_for
datetime
Optional
ISO 8601, e.g. 2026-10-01T14:00:00Z.
available_until
datetime
Optional
End of the window, for windowed_range.
interview_type
string
Optional
recording, proctoring, recording_proctoring (default) or interview_only.
voice
string
Optional
The AI interviewer: western or indian (default). Each has its own credit rate, pinned at booking: Western 11.44 / 11.78 / 14.11 / 9.50 and Indian 8.33 / 8.67 / 11.00 / 6.40 credits per minute for recording / proctoring / recording + proctoring / interview only. Every interview is conducted in English: Indian English (en-IN) or US English (en-US).
question_proficiency_level
string
Optional
low, medium (default) or high.
prompt_set_id
string (UUID)
Optional
A prompt set from GET /prompt-sets. Omit it for the default prompt set; an id that names no prompt set is refused with 422.
send_invite
boolean
Optional
false (default): nothing is emailed; deliver each join_url and join_passcode yourself. true: we email each candidate their join link and passcode.
Invite emails
By default no email is sent: the response carries every candidate's join_url and join_passcode for you to deliver, through your ATS for example. With "send_invite": true we email each candidate their join link, passcode and interview window, with your organisation's name and logo in the message (your custom branding, when you have set one). Every schedule in the response has an invite_email.status that says what happened:
| invite_email.status | Meaning |
|---|---|
not_requested | send_invite was false. Nothing was sent. |
queued | Handed to our email queue. It is sent within moments and retried if the mail server refuses it. |
sent | Sent while your request was being handled. |
skipped | The candidate has no email address. Nothing was sent; deliver the link yourself. |
failed | The send was attempted and refused; detail says why. The interview is still booked, so deliver the link yourself. |
If invite emails are unavailable on the platform, a request with "send_invite": true answers 503 and books nothing: no interview is created and no credits are reserved. Retry without send_invite to book and deliver the links yourself.
Schedule modes
Each mode takes only the times that apply to it, so a time you send is never silently ignored. Interviews can be booked up to 6 days from today, in every mode: a window may not start in the past and must end within 7 days from now (the sixth day plus the interview).
| schedule_mode | scheduled_for | available_until | Window |
|---|---|---|---|
fixed_datetime | Required | Omit | From scheduled_for for the interview's duration. |
available_24h | Omit | Omit | 24 hours from the moment you book. |
windowed_range | Required | Required | At least the interview's duration, ending within the 6-day booking horizon. |
curl -X POST "https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"job_description_id": "JOB_ID",
"candidate_profile_ids": ["CANDIDATE_ID"],
"agent": "cloud_interview",
"schedule_mode": "windowed_range",
"scheduled_for": "2026-10-01T09:00:00Z",
"available_until": "2026-10-03T18:00:00Z",
"expected_duration_minutes": 30,
"interview_type": "recording_proctoring",
"send_invite": true
}'
import os
import requests
response = requests.post(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"job_description_id": "JOB_ID",
"candidate_profile_ids": ["CANDIDATE_ID"],
"agent": "cloud_interview",
"schedule_mode": "windowed_range",
"scheduled_for": "2026-10-01T09:00:00Z",
"available_until": "2026-10-03T18:00:00Z",
"expected_duration_minutes": 30,
"interview_type": "recording_proctoring",
"send_invite": True
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules", {
method: "POST",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"job_description_id": "JOB_ID",
"candidate_profile_ids": ["CANDIDATE_ID"],
"agent": "cloud_interview",
"schedule_mode": "windowed_range",
"scheduled_for": "2026-10-01T09:00:00Z",
"available_until": "2026-10-03T18:00:00Z",
"expected_duration_minutes": 30,
"interview_type": "recording_proctoring",
"send_invite": true
}),
});
const { data } = await response.json();
{
"data": {
"created": true,
"schedules": [
{
"schedule_id": "8a41...",
"session_id": "c2f0...",
"interview_id": "c2f0...",
"candidate_profile_id": "CANDIDATE_ID",
"candidate_name": "Jane Doe",
"status": "scheduled",
"join_url": "https://.../join/9Xk2...",
"join_token": "9Xk2...",
"join_passcode": "482913",
"starts_at": "2026-10-01T09:00:00+00:00",
"ends_at": "2026-10-03T18:00:00+00:00",
"expected_duration_minutes": 30,
"interview_type": "recording_proctoring",
"credits_per_minute": "11.00",
"invite_email": { "status": "queued" }
}
]
},
"meta": { "request_id": "req_8f3c..." }
}
The join_url, join_token and join_passcode are returned only here. Listing, fetching or cancelling a schedule and resolving a join link return all three as null, so a read-only key cannot collect working interview links. Deliver or store them when you book.
When the prompt set relies on the job's interview questions and the job has none, the booking answers 422 if the questions are the prompt set's only material, or books with a warnings list saying the question list is skipped. A prompt set that asks only the job's questions is also booked with a warning when the list is short for the booked time (fewer than one question per two minutes): such an interview ends once its list is asked. warnings is present only when there is something to say.
List schedules
/schedulesinterviews:read
Query parameters
limit
integer
Optional
1–200, default 50.
offset
integer
Optional
Default 0.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules?limit=50" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules?limit=50",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules?limit=50", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Get a schedule
/schedules/{schedule_id}interviews:read
Every schedule response (list, get, cancel, and the schedule of a join link) has exactly these fields:
{
"data": {
"schedule_id": "8a41...",
"session_id": "c2f0...",
"interview_id": "c2f0...",
"job_description_id": "JOB_ID",
"candidate_profile_id": "CANDIDATE_ID",
"company_id": "COMPANY_ID",
"company_name": "Acme Corp",
"job_title": "Senior Software Engineer",
"candidate_name": "Jane Doe",
"candidate_email": "jane@example.com",
"schedule_mode": "windowed_range",
"status": "scheduled",
"starts_at": "2026-10-01T09:00:00Z",
"ends_at": "2026-10-03T18:00:00Z",
"expected_duration_minutes": 30,
"language_code": "en-US",
"language_name": "English (United States)",
"agent_variant": "western",
"interviewer": "western",
"prompt_set_id": "PROMPT_SET_ID",
"prompt_set_name": "Questions first, JD skills next, last resume details",
"interview_type": "recording_proctoring",
"credits_per_minute": "11.0000",
"recording_refund_per_minute": "2.3300",
"latest_email_delivery_status": "sent",
"latest_email_delivery_at": "2026-10-01T08:00:05Z",
"session_started_at": null,
"session_completed_at": null,
"join_url": null,
"join_token": null,
"join_passcode": null,
"created_at": "2026-10-01T08:00:00Z",
"updated_at": "2026-10-01T08:00:00Z"
},
"meta": { "request_id": "req_8f3c..." }
}
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Cancel a schedule
/schedules/{schedule_id}/cancelinterviews:write
Cancels an interview that has not started. Its join link stops working and the reserved credits are released.
curl -X POST "https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID/cancel" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.post(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID/cancel",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/schedules/SCHEDULE_ID/cancel", {
method: "POST",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
API reference
Results
The recording and the evaluation of a finished interview.
Get the recording
/interviews/{session_id}/recordinginterviews:read
Returns where the interview video is. The url is short-lived; call this again for a fresh one after expires_at.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/recording" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/recording",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/recording", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"session_id": "c2f0...",
"status": "available",
"available": true,
"url": "https://...",
"expires_at": "2026-10-01T10:15:00+00:00",
"mime_type": "video/webm",
"size_bytes": 104857600,
"complete": true,
"missing_segments": 0,
"reason": null
},
"meta": { "request_id": "req_8f3c..." }
}
| status | Meaning |
|---|---|
| available | The file exists; url is a short-lived link. |
| preparing | The interview is over and the recording is being assembled. Retry shortly. |
| failed | The recording cannot be produced; reason says why. |
| unavailable | No recording was captured, for example a proctoring-only interview. |
complete is false when parts were lost in transit (missing_segments counts them); the file still plays, with gaps.
Get the evaluation
/interviews/{session_id}/reportinterviews:write
Returns the evaluation of a completed interview and, when a webhook is set for it, sends the webhook payload to it again: the webhook of the API key that booked the interview, or else your organization's default webhook (see Which webhook receives an interview). analysis is the same object as the webhook's analysis.
409 conflict: the interview has not completed yet.200with"status": "queued"(or"running") and"analysis": null: the analysis is still running. Try again shortly, or wait for the webhook.200with"status": "failed"and"analysis": null: the analysis could not be produced; nothing is sent to the webhook.
curl -X POST "https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/report" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.post(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/report",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/interviews/SESSION_ID/report", {
method: "POST",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"session_id": "c2f0...",
"status": "completed",
"analysis": {
"score_scale_version": 2,
"interview_verdict": "Good",
"assessment_status": "complete",
"overall_score": 7.5,
"overall_basis": "total_of_six_dimensions",
"overall_total": 45.0,
"overall_total_max": 60.0,
"dimension_scores": {
"technical_competency": 8.0,
"problem_solving": 7.0,
"communication": 8.0,
"role_fit": 7.5,
"practical_experience": 7.0,
"jd_match": 7.5
},
"overall_summary": "...",
"required_skill_set_breakdown": [{ "skill": "Python", "score": 8.0, "comment": "..." }],
"optional_skill_set_breakdown": [],
"other_skill_set_breakdown": [],
"behaviour_skill_set_breakdown": [],
"question_answers": [{ "question": "...", "candidate_answer": "..." }],
"interview_quality": { "state": "ok", "reasons": [], "...": "..." },
"...": "..."
},
"webhook": { "status": "skipped" }
},
"meta": { "request_id": "req_8f3c..." }
}
API reference
Resources
Lookups used by the other endpoints.
List prompt sets
/prompt-setsinterviews:read
Custom prompt sets you can attach to a schedule with prompt_set_id.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/prompt-sets" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/prompt-sets",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/prompt-sets", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Resolve a join link
/join-links/{join_token}interviews:read
Finds the schedule a join token belongs to, and whether the link can be used now: allowed, reason (not_started, expired, completed or cancelled when it cannot) and the schedule, whose link, token and passcode are null.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/join-links/JOIN_TOKEN" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/join-links/JOIN_TOKEN",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/join-links/JOIN_TOKEN", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
API reference
Credits
Your organization's credits: what you can book with now, what booked interviews hold, what expires soon, and the current rates. Read-only, and always your own organization's.
Check these before you book: a booking reserves its credits for every candidate, or books none (402 insufficient_credits). Credit amounts are strings with two decimals, rates keep the rate card's four; times are in UTC. The balance and the holds are never cached.
Get the credit balance
/creditsinterviews:read
available_creditsis what a booking can use right now: exactly what the402check counts. Credits past their expiry date are no longer usable; for up to five minutes, until they are removed, they still count intotal_credits, soavailable_creditscan be lower thantotal_credits − held_credits.held_creditsis reserved by booked interviews (and by AI actions in the dashboard) until each one runs or is cancelled.expiringis what you can still use that expires in the next 30 days, and the next expiry date with its credits (nullwhen nothing expires).low_credit_alert_thresholdis the credit alert set on Plan & Usage (yours, or the platform default);"0.00"means alerts are off.billing_enforced: whenfalse, bookings are never refused for credits and nothing is held.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"available_credits": "7616.87",
"held_credits": "220.00",
"total_credits": "7836.87",
"expiring": {
"within_days": 30,
"credits": "1500.00",
"next_expiry_at": "2026-11-12T04:30:00+00:00",
"next_expiry_credits": "1500.00"
},
"low_credit_alert_threshold": "500.00",
"billing_enforced": true,
"as_of": "2026-10-29T09:00:00+00:00"
},
"meta": { "request_id": "req_8f3c..." }
}
List credit lots
/credits/lotsinterviews:read
Each lot of credits that still holds any, in the order they are spent: the soonest expiry first, never-expiring last. Paged with limit and offset (Pagination). source is plan_cycle, topup, bonus, manual_grant or refund; expires_at is null for credits that never expire. A lot past its expiry shows "expired": true and "available_credits": "0.00" until it is removed.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/lots?limit=50&offset=0" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/lots?limit=50&offset=0",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/lots?limit=50&offset=0", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": [
{
"source": "plan_cycle",
"granted_credits": "6000.00",
"remaining_credits": "1500.00",
"held_credits": "220.00",
"available_credits": "1280.00",
"granted_at": "2026-10-01T04:30:00+00:00",
"expires_at": "2026-11-12T04:30:00+00:00",
"expired": false,
"expiring_soon": true
}
],
"meta": {
"request_id": "req_8f3c...",
"total": 3, "limit": 50, "offset": 0,
"returned": 3, "has_more": false
}
}
List credit holds
/credits/holdsinterviews:read
What holds credits right now, newest first, paged. purpose is interview (a booking: its schedule_id, its interview_id, the booked reserved_minutes and the credits_per_minute fixed at booking) or ai_action (a dashboard AI action such as resume_parsing). held_credits is what is still held. The holds of all your bookings are listed, whichever key or dashboard user booked them.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/holds" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/holds",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/holds", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": [
{
"purpose": "interview",
"schedule_id": "9b1d...",
"session_id": "c2f0...",
"interview_id": "c2f0...",
"ai_action": null,
"held_credits": "220.00",
"reserved_minutes": 20,
"credits_per_minute": "11.0000",
"held_since": "2026-10-29T08:10:00+00:00"
}
],
"meta": {
"request_id": "req_8f3c...",
"total": 1, "limit": 50, "offset": 0,
"returned": 1, "has_more": false
}
}
Get the current rates
/credits/ratesinterviews:read
The credits per minute a booking would fix today, for each interview_type and each interviewer (voice, as in POST /schedules) available to you. A schedule without voice books the Indian interviewer at its rates. A booking holds, per candidate, minutes × credits_per_minute rounded up to the next 0.01 credit. booking_available is false when no rate is offered.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/rates" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/rates",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/credits/rates", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"items": [
{
"voice": "indian",
"interview_type": "recording_proctoring",
"display_name": "Interview with Recording + Proctoring",
"credits_per_minute": "11.0000",
"recording_refund_per_minute": "2.3300",
"features": { "recording": true, "proctoring": true }
}
],
"defaults": { "voice": "indian", "interview_type": "recording_proctoring" },
"booking": {
"min_minutes": 10,
"max_minutes": 60,
"hold_per_candidate": "minutes x credits_per_minute, rounded up to the next 0.01 credit"
},
"booking_available": true
},
"meta": { "request_id": "req_8f3c..." }
}
Webhooks
Completion webhook
Get each result pushed to your server the moment its analysis finishes.
Set your endpoint and signing secret on API Access. When an interview's analysis finishes, we POST the result to it. The analysis runs only once the interview is completed, so interview.status is always completed.
Which webhook receives an interview
Each API key can have its own webhook, so several systems connected with one key each receive only their own interviews.
- An interview booked with an API key that has its own webhook is posted to that webhook, signed with that webhook's own secret.
- Every other interview goes to your organization's default webhook: interviews booked in the dashboard, and those of keys without a webhook of their own, with their webhook switched off, or revoked. Revoking a key switches its webhook off.
- No webhook applies: nothing is sent; use Get the evaluation.
Set the default webhook and each key's webhook on API Access, or let a key manage its own with the endpoints below.
Get this key's webhook
/webhookinterviews:write
The calling key's own webhook. "configured": false means the key has none and its interviews go to the default webhook. The secret is never returned here.
curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.get(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook", {
method: "GET",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
{
"data": {
"configured": true,
"uses_default_webhook": false,
"url": "https://ats.example.com/webhooks/nuviolive",
"is_active": true,
"has_secret": true,
"created_at": "2026-10-09T10:00:00+00:00",
"updated_at": "2026-10-09T10:00:00+00:00"
},
"meta": { "request_id": "req_8f3c..." }
}
Set this key's webhook
/webhookinterviews:write
Creates or replaces the calling key's own webhook. A key manages only its own webhook, never the default or another key's.
Body
url
string
Required
Public HTTPS URL, 10 to 1,000 characters. Private, loopback and link-local addresses are refused.
secret
string
Optional
Signing secret, 16 to 256 characters. Omit it to keep the current secret, or, for a new webhook, to have one generated.
is_active
boolean
Optional
Default true. false pauses it: this key's interviews then go to the default webhook.
The response carries secret only when you just sent one or one was generated. Store it: it is not shown again.
curl -X PUT "https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook" \
-H "X-API-Key: $NUVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://ats.example.com/webhooks/nuviolive",
"is_active": true
}'
import os
import requests
response = requests.put(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
json={
"url": "https://ats.example.com/webhooks/nuviolive",
"is_active": True
},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook", {
method: "PUT",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"url": "https://ats.example.com/webhooks/nuviolive",
"is_active": true
}),
});
const { data } = await response.json();
Remove this key's webhook
/webhookinterviews:write
Removes the calling key's own webhook; its interviews go to the default webhook from then on. Returns {"deleted": true}, or false when the key had none.
curl -X DELETE "https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook" \
-H "X-API-Key: $NUVIO_API_KEY"
import os
import requests
response = requests.delete(
"https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook",
headers={"X-API-Key": os.environ["NUVIO_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json()["data"])
const response = await fetch("https://interview-platform-566637628639.asia-south1.run.app/api/v2/webhook", {
method: "DELETE",
headers: {
"X-API-Key": process.env.NUVIO_API_KEY,
},
});
const { data } = await response.json();
Payload
{
"event": "interview.completed",
"delivered_at": "2026-10-01T10:02:00+00:00",
"interview": {
"session_id": "c2f0...",
"interview_id": "c2f0...",
"schedule_id": "8a41...",
"job_id": "JOB_ID",
"job_title": "Senior Software Engineer",
"candidate_id": "CANDIDATE_ID",
"candidate_name": "Jane Doe",
"status": "completed",
"completion_reason": "...",
"started_at": "2026-10-01T09:30:00+00:00",
"completed_at": "2026-10-01T09:55:00+00:00",
"duration_minutes": 25.0,
"duration_basis": "measured",
"interview_type": "recording_proctoring",
"recording_included": true,
"proctoring_included": true
},
"analysis": { "...": "..." },
"cheating_events": [],
"recording": { "status": "available", "api_url": "...", "...": "..." },
"transcript": []
}
duration_basis:measured(the interview's own start and end),scheduled_window, orunknown(thenduration_minutesisnull). It is never estimated.interview_type,recording_included,proctoring_included: what the booked interview type included.interview_typeisnullfor an interview booked before interview types existed.recording: the same object as Get the recording, plusapi_urlto fetch a fresh link once the one in the payload expires.cheating_events: integrity detections actually recorded (tab switches, fullscreen exits and similar), each withtype,source,detected_atanddetails. Empty means none were detected only whenproctoring_includedistrue; when proctoring was not part of the interview, nothing was monitored.analysis.interview_verdict: the report's verdict, taken fromoverall_score(0–10 at one decimal, rounded half up):Excellent9.0–10.0,Good7.0–8.9,Average5.5–6.9,Below Average4.5–5.4,Poorbelow 4.5. An interview with too little coverage (too short, or too few answers), or one whose candidate speech came through garbled (assessment_coverage.transcript_garbled), isInconclusivewhatever its score: re-interview rather than decide.analysis.overall_basis:total_of_six_dimensionsfor current reports (overall_totalis the total of the sixdimension_scores, 0–60, andoverall_scoreis that total / 6);average_of_assessed_dimensionswhen the interview never came to some dimensions (they arenullindimension_scoresand left out:overall_totalis the total of the others, out ofoverall_total_max= 10 × their number, andoverall_scoreis their average); oraverage_of_five_competenciesfor earlier ones (overall_totalandoverall_total_maxarenull).dimension_scoreshastechnical_competency,problem_solving,communication,role_fit,practical_experienceandjd_match, each 0–10 as the report shows it, ornullwhen an earlier report never measured it or the interview did not assess it. For earlier reports,technical_score,communication_score,problem_solving_scoreandrole_readiness_scoreare the 0–10 competency, andjd_to_resume_match_scoreis the 0–100 resume match divided by 10.analysis: scores on a 0–10 scale.assessment_statussays how far the verdict can be trusted, as the report does:complete,provisional(limited evidence) orinconclusive(too little of the interview took place to judge, or the candidate's speech came through garbled; re-interview), with the figures inassessment_coverage; it isnullfor interviews analysed before 2026-10-05, when no coverage was stored. From 2026-10-06assessment_coveragealso carriestranscript_garbled(boolean: the candidate's speech came through as misheard or broken words in at least 35% of what they said, over at least 4 answers or fragments; the verdict is thenInconclusive, the first reason reads "Candidate voice/transcript is garbled" and advises listening to the recording and re-interviewing, andrecommendationis only that note),garbled_turns(integer: garbled answers plus split word fragments) andgarbled_word_share(0–1, ornull), andinterview_qualitycarriestranscript_garbledtoo (falsefor older reports). These fields are additive; older reports are not re-scored. A weak but understandable answer is scored normally. Skills are filed against the job's required and preferred skills as they were when the interview was analysed, matched by normalised name;other_skill_set_breakdownis empty for interviews analysed from 2026-10-06.interview_quality.stateisok,degradedorunknown; read a degraded interview's score with care. A required or preferred skill the interview did not cover scores0.0, "Not demonstrated". From 2026-10-15 a behaviour skill the interview gave no evidence of scores0.0with the comment "Not assessed in this interview: ..." and is left out ofbehaviour_skill_set_score, which is0.0when no behaviour skill was assessed; older reports keep their score. An interview whose prompt set asks only the job's question list carriesassessment_coverage.questions_listed,listed_answeredand, from 2026-10-15,listed_asked; when every listed question was asked the report says "Completed: all N questions asked". From 2026-10-24assessment_coveragealso carriesended_by_platform_fault(boolean: a technical problem on the platform ended the interview, not the candidate; its unanswered last question is not counted against them, the report says "Ended early by a technical problem", and the interview is not charged) andend_reason(provider_failure,interviewer_unresponsive,agent_left,agent_terminatedornull);last_question_unansweredthen passes over the invitation to ask the interviewer questions. A required or preferred skill the candidate only named because the question asked only for names scores0.0with the comment "Not assessed: ..." and is left out oftechnical_skill_set_score.evidence_strength_scoreweighs only what the interview assessed (dimensions it never came to and skills never asked about, or only asked to be named, are left out), so it reads higher than before for the same interview; older reports keep their value.nullmeans not measured:confidence_score,learning_agility_scoreandstakeholder_communication_scoreare alwaysnullfor current interviews, andanswer_consistency_score/evidence_strength_scorearenullwhen there was nothing to measure.
Verify the signature
Each delivery is signed with HMAC-SHA256 of the raw request body, keyed with your signing secret. Compute it over the bytes you received, before parsing the JSON, and compare in constant time.
X-NuViO-Signature: sha256=<hex digest>
import hashlib
import hmac
def is_valid(raw_body: bytes, header_value: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header_value or "")
import crypto from "node:crypto";
export function isValid(rawBody, headerValue, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(headerValue || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Retries
Answer with any 2xx to acknowledge. A failed delivery is retried with growing waits (10 s, 60 s, 5 min, 30 min), and retries survive our deployments. Make your endpoint idempotent: treat a repeated session_id as the same interview.
Reference
Errors
Branch on the status and the error code; show the message to people.
| Status | Code | Meaning |
|---|---|---|
400 | bad_request | The request cannot be processed as sent. |
401 | unauthorized | Missing, malformed, unknown, revoked or expired API key. |
402 | insufficient_credits | Not enough credits to book these interviews; details gives what is needed and what is available. |
403 | forbidden / plan_excludes_api | Access is switched off, the organization is inactive, the key lacks the scope, or the plan excludes the API. |
404 | not_found | No such record in your organization. |
409 | conflict | The record is not in a state that allows this, e.g. a report for an unfinished interview. |
422 | validation_error | A field is missing, unknown or out of range; the message names it. |
429 | rate_limited | Over the key's per-minute limit; wait for Retry-After. |
5xx | internal_error, service_unavailable | A problem on our side. Retry with backoff, and quote the request_id if it persists. |
Reference
Credits and interview types
Interviews are paid for in prepaid credits, by the type of interview booked.
| interview_type | What it includes |
|---|---|
recording | Screen, camera and audio recording; no proctoring. |
proctoring | Face checks and integrity detections; never recorded. |
recording_proctoring | Both. Used when a schedule sends no interview_type. |
interview_only | Neither: the AI interview, its transcript and its report only. |
- Booking reserves credits for every candidate, or books none (
402when short). The rate is fixed when you book and returned ascredits_per_minute. - Only the exact time the interview ran is charged, capped at the booked duration; the rest of the reservation is released. Cancelling releases it all.
- Your balance, rates and usage are on Plan & Usage, and in the API under Credits.