Authentication & First Request

Use this guide to make your first successful call to the NTRVSTA External Integrations API.

Authentication

Authenticate each request with your organization-scoped API key, issued as ntrvsta_live_<publicId>.<secret>, using either:

• X-Ntrvsta-Api-Key: <your-key>
• Authorization: Bearer <your-key>

Scopes and rate limits

Each API key must select at least one scope:

• templates:read — list and get templates
• templates:write — create and update templates
• invitations:write — create interview invitations
• results:read — poll interview results

A request without the scope its endpoint requires fails with HTTP 403:

{ "error": "API key scope templates:write is required" }

Credentials created before scopes were introduced keep all four scopes until they are revoked and replaced.

Each credential can send up to 120 authenticated requests per fixed 60-second window. Excess requests return HTTP 429 with { "error": "API key rate limit exceeded" }. Retry after the current window resets.

Authentication errors

• 401 — missing key (API key is required) or unknown or revoked key (Invalid API key)
• 403 — the owning organization is inactive (Organization is inactive) or the key is missing a required scope
• 429 — rate limit exceeded

First Flow

The most common sequence is:

1. Create a reusable template
2. Create an interview invitation for a candidate
3. Poll for interview results

First Request Example

curl --request POST \
  --url https://partners.ntrvsta.com/v1/templates \
  --header 'Content-Type: application/json' \
  --header 'X-Ntrvsta-Api-Key: <your-api-key>' \
  --data '{
    "title": "Senior Backend Engineer",
    "description": "Backend engineering interview for distributed systems candidates"
  }'

externalPostingId is optional. Include it when you want idempotent create-or-reuse behavior for the same external posting.

Next Step

Once you have your API key and first template payload ready, continue in the live API Reference for schema details and request testing.