NuViOLive
API Documentation

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.

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.

  1. 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.

    Terminal
    export NUVIO_API_KEY="nuv_xxxxxxxx.yyyyyyyyyyyyyyyy"
  2. Check the key

    GET /me describes the key in use. A 200 means you are ready.

    curl -X GET "https://interview-platform-566637628639.asia-south1.run.app/api/v2/me" \
      -H "X-API-Key: $NUVIO_API_KEY"
  3. Create a job and a candidate

    Create the job with POST /jobs, then add the candidate to it with POST /candidates. Each response returns the new record's id.

  4. Schedule the interview

    POST /schedules books the interview and returns the candidate's join link and passcode. Send them to the candidate yourself, or add "send_invite": true and we email them. When it is over, the webhook delivers the evaluation.

Getting started

Authentication

Every request carries your API key in a header.

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.

ScopeGrants
interviews:readReading jobs, candidates, schedules, prompt sets, join links, recordings and credits.
interviews:writeCreating 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

StatusCodeWhy
401unauthorizedThe header is missing, the key is malformed, unknown, revoked or expired.
403forbiddenAPI access is switched off for the organization, the organization is inactive, or the key lacks the endpoint's scope.
403plan_excludes_apiThe 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.

Success
{
  "data": { "...": "..." },
  "meta": { "request_id": "req_8f3c..." }
}
Error
{
  "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
"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. requiredSkills instead of required_skills is an error, not a job with no skills.
  • Lists take at most 100 entries of at most 200 characters (question_set entries 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 be http or https.
  • 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

GET/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"
Response · 200 OK
{
  "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

GET/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"

Get a job

GET/jobs/{job_description_id}interviews:read

Returns one job by its id. Every job response has exactly these fields:

Response · 200 OK
{
  "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"

Create a job

POST/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."]
  }'

Update a job

PATCH/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"]
  }'

API reference

Candidates

The people you interview, each attached to one job.

List candidates

GET/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"

Get a candidate

GET/candidates/{candidate_profile_id}interviews:read

Every candidate response has exactly these fields:

Response · 200 OK
{
  "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"

Create a candidate

POST/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"
  }'

Update a candidate

PATCH/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"
  }'

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

POST/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.statusMeaning
not_requestedsend_invite was false. Nothing was sent.
queuedHanded to our email queue. It is sent within moments and retried if the mail server refuses it.
sentSent while your request was being handled.
skippedThe candidate has no email address. Nothing was sent; deliver the link yourself.
failedThe 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_modescheduled_foravailable_untilWindow
fixed_datetimeRequiredOmitFrom scheduled_for for the interview's duration.
available_24hOmitOmit24 hours from the moment you book.
windowed_rangeRequiredRequiredAt 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
  }'
Response · 201 Created
{
  "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

GET/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"

Get a schedule

GET/schedules/{schedule_id}interviews:read

Every schedule response (list, get, cancel, and the schedule of a join link) has exactly these fields:

Response · 200 OK
{
  "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"

Cancel a schedule

POST/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"

API reference

Results

The recording and the evaluation of a finished interview.

Get the recording

GET/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"
Response · 200 OK
{
  "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..." }
}
statusMeaning
availableThe file exists; url is a short-lived link.
preparingThe interview is over and the recording is being assembled. Retry shortly.
failedThe recording cannot be produced; reason says why.
unavailableNo 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

POST/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.
  • 200 with "status": "queued" (or "running") and "analysis": null: the analysis is still running. Try again shortly, or wait for the webhook.
  • 200 with "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"
Response · 200 OK
{
  "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

GET/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"
GET/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"

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

GET/creditsinterviews:read
  • available_credits is what a booking can use right now: exactly what the 402 check counts. Credits past their expiry date are no longer usable; for up to five minutes, until they are removed, they still count in total_credits, so available_credits can be lower than total_credits − held_credits.
  • held_credits is reserved by booked interviews (and by AI actions in the dashboard) until each one runs or is cancelled.
  • expiring is what you can still use that expires in the next 30 days, and the next expiry date with its credits (null when nothing expires).
  • low_credit_alert_threshold is the credit alert set on Plan & Usage (yours, or the platform default); "0.00" means alerts are off.
  • billing_enforced: when false, 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"
Response · 200 OK
{
  "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

GET/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"
Response · 200 OK
{
  "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

GET/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"
Response · 200 OK
{
  "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

GET/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"
Response · 200 OK
{
  "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

GET/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"
Response · 200 OK
{
  "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

PUT/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
  }'

Remove this key's webhook

DELETE/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"

Payload

interview.completed
{
  "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, or unknown (then duration_minutes is null). It is never estimated.
  • interview_type, recording_included, proctoring_included: what the booked interview type included. interview_type is null for an interview booked before interview types existed.
  • recording: the same object as Get the recording, plus api_url to fetch a fresh link once the one in the payload expires.
  • cheating_events: integrity detections actually recorded (tab switches, fullscreen exits and similar), each with type, source, detected_at and details. Empty means none were detected only when proctoring_included is true; when proctoring was not part of the interview, nothing was monitored.
  • analysis.interview_verdict: the report's verdict, taken from overall_score (0–10 at one decimal, rounded half up): Excellent 9.0–10.0, Good 7.0–8.9, Average 5.5–6.9, Below Average 4.5–5.4, Poor below 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), is Inconclusive whatever its score: re-interview rather than decide.
  • analysis.overall_basis: total_of_six_dimensions for current reports (overall_total is the total of the six dimension_scores, 0–60, and overall_score is that total / 6); average_of_assessed_dimensions when the interview never came to some dimensions (they are null in dimension_scores and left out: overall_total is the total of the others, out of overall_total_max = 10 × their number, and overall_score is their average); or average_of_five_competencies for earlier ones (overall_total and overall_total_max are null). dimension_scores has technical_competency, problem_solving, communication, role_fit, practical_experience and jd_match, each 0–10 as the report shows it, or null when an earlier report never measured it or the interview did not assess it. For earlier reports, technical_score, communication_score, problem_solving_score and role_readiness_score are the 0–10 competency, and jd_to_resume_match_score is the 0–100 resume match divided by 10.
  • analysis: scores on a 0–10 scale. assessment_status says how far the verdict can be trusted, as the report does: complete, provisional (limited evidence) or inconclusive (too little of the interview took place to judge, or the candidate's speech came through garbled; re-interview), with the figures in assessment_coverage; it is null for interviews analysed before 2026-10-05, when no coverage was stored. From 2026-10-06 assessment_coverage also carries transcript_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 then Inconclusive, the first reason reads "Candidate voice/transcript is garbled" and advises listening to the recording and re-interviewing, and recommendation is only that note), garbled_turns (integer: garbled answers plus split word fragments) and garbled_word_share (0–1, or null), and interview_quality carries transcript_garbled too (false for 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_breakdown is empty for interviews analysed from 2026-10-06. interview_quality.state is ok, degraded or unknown; read a degraded interview's score with care. A required or preferred skill the interview did not cover scores 0.0, "Not demonstrated". From 2026-10-15 a behaviour skill the interview gave no evidence of scores 0.0 with the comment "Not assessed in this interview: ..." and is left out of behaviour_skill_set_score, which is 0.0 when no behaviour skill was assessed; older reports keep their score. An interview whose prompt set asks only the job's question list carries assessment_coverage.questions_listed, listed_answered and, from 2026-10-15, listed_asked; when every listed question was asked the report says "Completed: all N questions asked". From 2026-10-24 assessment_coverage also carries ended_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) and end_reason (provider_failure, interviewer_unresponsive, agent_left, agent_terminated or null); last_question_unanswered then 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 scores 0.0 with the comment "Not assessed: ..." and is left out of technical_skill_set_score. evidence_strength_score weighs 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. null means not measured: confidence_score, learning_agility_score and stakeholder_communication_score are always null for current interviews, and answer_consistency_score / evidence_strength_score are null when 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.

Header
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 "")

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.

StatusCodeMeaning
400bad_requestThe request cannot be processed as sent.
401unauthorizedMissing, malformed, unknown, revoked or expired API key.
402insufficient_creditsNot enough credits to book these interviews; details gives what is needed and what is available.
403forbidden / plan_excludes_apiAccess is switched off, the organization is inactive, the key lacks the scope, or the plan excludes the API.
404not_foundNo such record in your organization.
409conflictThe record is not in a state that allows this, e.g. a report for an unfinished interview.
422validation_errorA field is missing, unknown or out of range; the message names it.
429rate_limitedOver the key's per-minute limit; wait for Retry-After.
5xxinternal_error, service_unavailableA 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_typeWhat it includes
recordingScreen, camera and audio recording; no proctoring.
proctoringFace checks and integrity detections; never recorded.
recording_proctoringBoth. Used when a schedule sends no interview_type.
interview_onlyNeither: the AI interview, its transcript and its report only.
  • Booking reserves credits for every candidate, or books none (402 when short). The rate is fixed when you book and returned as credits_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.