API overview

The Talvin API lets you read your interviews and candidate responses, and subscribe to webhooks for real-time events. Use it to connect Talvin to your ATS, internal dashboards or any custom tool.

Base URL: https://app.talvin.ai/api/v1

Prefer no code?

The Zapier integration uses this same API and connects Talvin to thousands of apps without writing any code.

Getting your credentials

You need two values, both in the Talvin dashboard under Settings → Integrations:

Credential	Where to find it	Example
Organization ID	The Organization ID card at the top of the Integrations page	org_2abc…
API key	API Keys tab → Create API Key → choose Custom API (or a platform)	talvin_a1b2c3…

Caution

Your API key is shown only once, when you create it. Store it in a secrets manager or environment variable. If you lose it, revoke the key and create a new one.

The key gives read access to your organization’s interview and candidate data. Never commit it to source control or ship it in client-side code.

See Managing API keys for creating and revoking keys.

Authentication

Pass both credentials as headers on every request:

X-TALVIN-API-KEY: talvin_your_api_key
X-TALVIN-ORGANIZATION-ID: org_your_organization_id

Quick test to check your credentials:

curl https://app.talvin.ai/api/v1/whoami \
  -H "X-TALVIN-API-KEY: talvin_your_api_key" \
  -H "X-TALVIN-ORGANIZATION-ID: org_your_organization_id"

{ "success": true, "data": { "id": "0f4c1…", "name": "My Integration" } }

A 401 means the key or organization ID is missing or invalid.

Rate limits

Requests are limited to 100 requests per 5 seconds per organization. Every response includes:

Header	Meaning
X-RateLimit-Limit	Requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window

When you go over the limit, the API returns 429 with { "error": "Rate limit exceeded" }. Wait briefly and retry.

Errors

Errors return a JSON body { "error": "message" } with standard status codes:

Status	Meaning
400	Malformed request (for example, missing hookUrl)
401	Missing or invalid API key or organization ID
404	Resource not found, or it belongs to another organization
429	Rate limit exceeded. Retry after a short delay
500	Something went wrong on our side. Safe to retry; contact support if it keeps happening

Questions

Need higher rate limits, or an endpoint that doesn’t exist yet? Email hello@talvin.ai. API feedback directly shapes our roadmap.