API Reference#

The InterviewRelay REST API gives you programmatic access to all platform features. Create campaigns, manage invites, retrieve transcripts, and automate your interview workflows.

Base URL#

All API requests are made to:

https://api.interviewrelay.com/v1

All requests must use HTTPS. HTTP requests will be redirected.

Authentication#

Authenticate using a Bearer token in the Authorization header:

curl https://api.interviewrelay.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting Your API Key#

1. Go to Settings → API Keys
2. Click Generate New Key
3. Give the key a name and select permissions
4. Copy the key — it's only shown once

Key Permissions#

| Permission | Description | |-----------|-------------| | campaigns:read | List and view campaigns | | campaigns:write | Create and update campaigns | | invites:read | List and view invites | | invites:write | Create and manage invites | | sessions:read | View sessions and transcripts | | sessions:write | Manage session lifecycle | | billing:read | View billing and usage | | billing:write | Manage subscriptions and credits | | organization:read | View organization settings | | organization:write | Manage organization settings |

Campaigns API#

Create Campaign#

Request body:

Example request:

curl -X POST https://api.interviewrelay.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Customer Feedback",
    "description": "Quarterly feedback interviews with enterprise customers",
    "scriptId": "scr_abc123",
    "projectId": "prj_xyz789",
    "settings": {
      "voice": "alloy",
      "language": "en",
      "maxDuration": 1800,
      "requireConsent": true
    },
    "inviteDefaults": {
      "expiresIn": "7d",
      "emailTemplate": "default"
    }
  }'

Example response:

{
  "id": "cam_a1b2c3d4",
  "name": "Q1 Customer Feedback",
  "description": "Quarterly feedback interviews with enterprise customers",
  "scriptId": "scr_abc123",
  "projectId": "prj_xyz789",
  "status": "active",
  "settings": {
    "voice": "alloy",
    "language": "en",
    "maxDuration": 1800,
    "requireConsent": true
  },
  "inviteDefaults": {
    "expiresIn": "7d",
    "emailTemplate": "default"
  },
  "stats": {
    "totalInvites": 0,
    "completedSessions": 0,
    "averageDuration": 0
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Campaigns#

Query parameters:

Example request:

curl https://api.interviewrelay.com/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "status=active" \
  -d "limit=10"

Get Campaign#

Example request:

curl https://api.interviewrelay.com/v1/campaigns/cam_a1b2c3d4 \
  -H "Authorization: Bearer YOUR_API_KEY"

Invites API#

Create Invite#

Request body:

Example request:

curl -X POST https://api.interviewrelay.com/v1/campaigns/cam_a1b2c3d4/invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "participant@example.com",
    "name": "Jane Doe",
    "sendEmail": true,
    "expiresIn": "7d",
    "metadata": {
      "userId": "12345",
      "segment": "enterprise"
    }
  }'

Example response:

{
  "id": "inv_x1y2z3",
  "campaignId": "cam_a1b2c3d4",
  "token": "inv_8f7d9e2c1a0b3h4k5j6m",
  "email": "participant@example.com",
  "name": "Jane Doe",
  "status": "pending",
  "inviteUrl": "https://interviewrelay.com/interview/inv_8f7d9e2c1a0b3h4k5j6m",
  "emailStatus": "sent",
  "expiresAt": "2024-01-22T10:30:00Z",
  "metadata": {
    "userId": "12345",
    "segment": "enterprise"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Bulk Create Invites#

Request body:

{
  "invites": [
    { "email": "alice@example.com", "name": "Alice", "metadata": { "segment": "trial" } },
    { "email": "bob@example.com", "name": "Bob", "metadata": { "segment": "enterprise" } }
  ],
  "sendEmail": true,
  "expiresIn": "7d"
}

Get Invite#

List Invites#

Query parameters:

Cancel Invite#

Resend Invite#

Sessions API#

List Sessions#

Query parameters:

Example request:

curl https://api.interviewrelay.com/v1/campaigns/cam_a1b2c3d4/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "status=completed" \
  -d "limit=50"

Get Session#

Example response:

{
  "id": "ses_m1n2o3p4",
  "campaignId": "cam_a1b2c3d4",
  "inviteId": "inv_x1y2z3",
  "status": "completed",
  "participant": {
    "email": "participant@example.com",
    "name": "Jane Doe"
  },
  "startedAt": "2024-01-15T14:00:00Z",
  "completedAt": "2024-01-15T14:12:30Z",
  "duration": 750,
  "questionsAnswered": 8,
  "totalQuestions": 10,
  "language": "en",
  "sentiment": {
    "overall": "positive",
    "score": 0.72
  },
  "device": {
    "browser": "Chrome 120",
    "os": "macOS 14.2",
    "type": "desktop"
  },
  "metadata": {
    "userId": "12345",
    "segment": "enterprise"
  },
  "createdAt": "2024-01-15T13:59:45Z"
}

Get Session Transcript#

Query parameters:

Export Session as PDF#

Query parameters:

Pause Session#

Request body:

{
  "reason": "Technical issue reported by participant"
}

Resume Session#

Session Heartbeat#

Record Consent#

Request body:

List Session Files#

Upload Session File#

Projects API#

List Projects#

Create Project#

Request body:

Get Project#

Update Project#

Delete Project#

Scripts API#

Create Script#

Request body:

Question object:

Example request:

curl -X POST https://api.interviewrelay.com/v1/scripts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Satisfaction Script",
    "systemPrompt": "You are a friendly interviewer conducting a customer satisfaction survey. Be conversational and follow up on interesting responses.",
    "questions": [
      {
        "id": "q1",
        "text": "Tell me about your experience using our product.",
        "type": "open",
        "followUp": {
          "enabled": true,
          "maxFollowUps": 2,
          "prompt": "Ask a follow-up that digs deeper into their specific experience"
        }
      },
      {
        "id": "q2",
        "text": "On a scale of 1-10, how likely are you to recommend us?",
        "type": "rating"
      }
    ],
    "settings": {
      "maxFollowUps": 2,
      "language": "en",
      "voice": "alloy"
    }
  }'

List Scripts#

Query parameters:

Get Script#

Update Script#

Delete Script#

Publish Script#

Create New Version#

Request body:

Export Script#

Import Script#

Upload Script Media#

Organizations API#

Get Organization#

Update Organization#

Request body:

List Members#

Invite Member#

Update Member Role#

Remove Member#

Billing API#

Get Current Plan#

Example response:

{
  "plan": "professional",
  "status": "active",
  "credits": {
    "balance": 342,
    "included": 500,
    "purchased": 100,
    "used": 258
  },
  "billingPeriod": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "nextInvoice": {
    "date": "2024-02-01T00:00:00Z",
    "amount": 19900,
    "currency": "usd"
  }
}

Get Usage#

Query parameters:

Purchase Credits#

Request body:

List Invoices#

Rate Limiting#

API requests are rate-limited per API key:

| Plan | Rate Limit | |------|-----------| | Free | 60 requests/minute | | Starter | 300 requests/minute | | Professional | 1,000 requests/minute | | Enterprise | Custom (up to 10,000 requests/minute) |

Rate Limit Headers#

Every response includes rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1705312800

Handling Rate Limits#

When rate limited, the API returns 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retryAfter": 45
  }
}

Implement exponential backoff in your client:

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Error Codes#

All error responses follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

HTTP Status Codes#

| Status | Meaning | |--------|---------| | 200 | Success | | 201 | Created | | 204 | No Content (successful deletion) | | 400 | Bad Request — invalid parameters | | 401 | Unauthorized — invalid or missing API key | | 403 | Forbidden — insufficient permissions | | 404 | Not Found — resource doesn't exist | | 409 | Conflict — resource state conflict | | 422 | Unprocessable Entity — validation error | | 429 | Too Many Requests — rate limit exceeded | | 500 | Internal Server Error | | 503 | Service Unavailable — temporary outage |

Common Error Codes#

Pagination#

List endpoints return paginated results. Use limit and offset parameters:

# First page
curl https://api.interviewrelay.com/v1/campaigns?limit=20&offset=0

# Second page
curl https://api.interviewrelay.com/v1/campaigns?limit=20&offset=20

Pagination Response#

All list endpoints include pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Best Practices#

Idempotency#

For POST requests, include an Idempotency-Key header to prevent duplicate operations:

curl -X POST https://api.interviewrelay.com/v1/campaigns/cam_abc/invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"email": "participant@example.com"}'

Idempotency keys are valid for 24 hours. Repeat requests with the same key return the original response.

Webhooks vs. Polling#

Use webhooks for real-time event notifications instead of polling the API. Webhooks are more efficient and provide instant updates for:

• Session started / completed / abandoned
• Invite delivered / bounced / opened
• Transcript ready
• Credit balance alerts

Error Handling#

1. Always check HTTP status codes
2. Parse the error response body for detailed information
3. Implement retry logic with exponential backoff for 5xx errors and 429
4. Don't retry 4xx errors (except 429) — they indicate client-side issues
5. Log error details for debugging

Caching#

• Campaign and script data changes infrequently — cache for 5-10 minutes
• Session data may change rapidly during active interviews — don't cache
• Transcripts are immutable after generation — cache indefinitely

SDKs & Libraries#

Official client libraries are available for popular languages:

JavaScript / TypeScript#

npm install @interviewrelay/api-client

import { InterviewRelayClient } from '@interviewrelay/api-client';

const client = new InterviewRelayClient({ apiKey: process.env.IR_API_KEY });

const campaign = await client.campaigns.create({
  name: 'My Campaign',
  scriptId: 'scr_abc123'
});

const invite = await client.invites.create(campaign.id, {
  email: 'participant@example.com'
});

Python#

pip install interviewrelay

from interviewrelay import Client

client = Client(api_key="YOUR_API_KEY")

campaign = client.campaigns.create(
    name="My Campaign",
    script_id="scr_abc123"
)

invite = client.invites.create(
    campaign_id=campaign.id,
    email="participant@example.com"
)

Ruby#

gem install interviewrelay

require 'interviewrelay'

client = InterviewRelay::Client.new(api_key: ENV['IR_API_KEY'])

campaign = client.campaigns.create(
  name: 'My Campaign',
  script_id: 'scr_abc123'
)

cURL#

All examples in this documentation use cURL. No additional installation needed.