Public API

Available onEnterprise

Who can do thisWorkspace owners and admins

The public API lets your own systems work with Infyva: list jobs and candidates, add a candidate to a job, schedule an interview, check its status and read the report summary. Enterprise workspaces can also pull the audit log.

Every endpoint is listed in the API reference.

Base URL

All endpoints are under:

https://api.infyva.ai/api/v1/public

The same value is shown in Infyva: open Settings > API keys and webhooks, then on the Developer platform page look at Base URL under API reference. If the two ever differ, use the one in Infyva.

The examples on this page use $INFYVA_API_BASE for that value and $INFYVA_API_KEY for your key:

export INFYVA_API_BASE="https://api.infyva.ai/api/v1/public"
export INFYVA_API_KEY="infy_live_..."

Create an API key

1. Open Settings > API keys and webhooks.
2. In API keys, enter a key name, for example Northwind HR sync. Names can be up to 80 characters.
3. Tick the scopes the key needs. read:interviews and read:reports are ticked for you. Pick at least one.
4. Click Create key.
5. Copy the key from Copy your new key now. You won't see it again. and store it in your secrets manager. Click Done.

Keys look like infy_live_ followed by 43 characters. Infyva stores only a hash of the key, so nobody at Infyva can show it to you again. The key table shows each key's Name, the start of the Key, its Scopes, when it was Created and when it was Last used (Never until its first call).

Keys act for your whole company, not for one person. They do not expire.

Scopes

Scope	What it allows
read:interviews	List jobs, list a job's candidates, read interview status.
write:candidates	Add candidates to a job and schedule interviews.
read:reports	Read report summaries.
read:audit_log	Pull the audit log, for your SIEM. Also needs the audit log on your plan.

You can't change a key's scopes. To change them, create a new key and revoke the old one.

Revoke a key

1. Open Settings > API keys and webhooks.
2. In the key table, click Revoke next to the key.
3. Confirm Revoke API key? Anything using the key stops working immediately.

Revoked keys stay in the table, marked Revoked.

The key owner rule

A key belongs to your company, but its calls run as the owner or admin who created it. Interviews it schedules use credits the same way as if that person sent them, and audit entries show that person.

If that person leaves the company or is no longer an owner or admin, the key stops working with 401 The admin who created this key is no longer an owner or admin. Create a new key. Before you change someone's role, create replacement keys from another admin's account.

Authenticate

Send the key in one of two headers:

curl "$INFYVA_API_BASE/jobs" \
  -H "Authorization: Bearer $INFYVA_API_KEY"

curl "$INFYVA_API_BASE/jobs" \
  -H "X-API-Key: $INFYVA_API_KEY"

Every request checks the key, the rate limit, your plan and the key owner, in that order.

Limits

Limit	Value
Requests	120 per minute per key. Over the limit you get 429 with a Retry-After header in seconds.
Active keys	25 per workspace. Revoke one to create another: A company can have at most 25 active keys. Revoke one first.
Page size	limit from 1 to 200, default 50. The audit log allows up to 5,000, default 1,000.

Pagination

List endpoints take limit and skip and return:

{
  "data": [ ... ],
  "total": 42,
  "limit": 50,
  "skip": 0
}

total is the number of items across all pages. To get the next page, add limit to skip. Lists are sorted newest first.

The audit log is different: it returns newline-delimited JSON, oldest first. Send the X-Next-Cursor header from one response as after on the next. See the API reference.

Examples

List active jobs:

curl "$INFYVA_API_BASE/jobs?status=active&limit=20" \
  -H "Authorization: Bearer $INFYVA_API_KEY"

Add a candidate to a job:

curl -X POST "$INFYVA_API_BASE/jobs/JOB_ID/candidates" \
  -H "Authorization: Bearer $INFYVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maya Chen", "email": "maya.chen@example.com", "resume_url": "https://files.example.com/maya-chen.pdf"}'

The response's id is the job-candidate record. Use it as CANDIDATE_ID to schedule an interview. Infyva stores resume_url as a link and does not download it.

Schedule an interview and email the candidate their link now:

curl -X POST "$INFYVA_API_BASE/jobs/JOB_ID/candidates/CANDIDATE_ID/interviews" \
  -H "Authorization: Bearer $INFYVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link_expiration_hours": 72}'

The job's default interview type is used unless you send interview_type (recruiter for an AI interview or elite_live for Live AI). Scheduling an AI interview holds 1 credit. A Live AI interview uses credits at 0.5 credit per minute of conversation. Your workspace's compliance policies apply to API invites too.

Check the interview, then read the report:

curl "$INFYVA_API_BASE/interviews/INTERVIEW_ID" \
  -H "Authorization: Bearer $INFYVA_API_KEY"

curl "$INFYVA_API_BASE/interviews/INTERVIEW_ID/report" \
  -H "Authorization: Bearer $INFYVA_API_KEY"

The report endpoint returns 404 Report is not ready yet until the report exists. Instead of polling, you can listen for the report.ready webhook.

Errors

Errors return JSON with a detail field, usually a message string.

Status	When	Message
401	No key sent.	Missing API key. Send Authorization: Bearer <key>.
401	The key is wrong or revoked.	Invalid or revoked API key
401	The person who created the key is no longer an owner or admin.	The admin who created this key is no longer an owner or admin. Create a new key.
403	Your plan does not include the API.	API access is not included in your company's current plan
403	The key lacks the scope.	This API key is missing the '<scope>' scope
404	The job, candidate, interview or report is not in your company, or does not exist yet.	For example: Job not found
409	A conflict, such as the candidate already being on the job.	See the API reference
422	A field failed validation.	Details of the field
429	Over 120 requests a minute.	Wait for Retry-After seconds.

What the API can't do

• Update or delete candidates, move stages or cancel interviews.
• Create or edit jobs.
• List reports in bulk or download report PDFs.
• Manage webhooks or API keys. Do that in Settings > API keys and webhooks.
• Per-user tokens or OAuth apps. Keys belong to the company.
• Test or sandbox keys, key expiry or per-key IP limits.

Next steps

• API reference
• Webhooks
• Zapier and Make