> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interviewflowai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Create Interviewers, invite Candidates and read their results from your own system.

The InterviewFlowAI API connects your ATS or internal tools to InterviewFlowAI. Call it from your server with an [API key](https://docs.interviewflowai.com/platform/api-keys.md).

> [card] [Interviewers](https://docs.interviewflowai.com/api-reference/interviewers/create.md)
>
> Create an Interviewer when a role opens, and update its settings later.

> [card] [Candidates](https://docs.interviewflowai.com/api-reference/candidates/invite.md)
>
> Invite Candidates, fetch their results, and sync stages, notes and custom fields.

To get notified when something happens, such as a completed interview, see [Webhooks](https://docs.interviewflowai.com/platform/webhooks.md).

## Base URL

```text theme={null}
https://api.interviewflowai.com
```

## Authentication

Send your API key in the `X-API-KEY` header:

```bash theme={null}
curl -X POST https://api.interviewflowai.com/api/external/fetch/candidates \
  -H "X-API-KEY: $INTERVIEWFLOWAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobId": "JOB_ID", "page": 1, "limit": 20}'
```

A key works on its own Company only. Only **Owners** can create keys. See [API keys](https://docs.interviewflowai.com/platform/api-keys.md).

Your plan must include API access. Without it, every request returns `403`.

## Rate limits

Limits are per API key.

| Endpoints | Limit |
| - | - |
| [Create an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/create.md), [Update an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/update.md) | 5 requests a minute, shared |
| [List Candidates](https://docs.interviewflowai.com/api-reference/candidates/list.md), [Update a Candidate](https://docs.interviewflowai.com/api-reference/candidates/update.md), [Update custom fields](https://docs.interviewflowai.com/api-reference/candidates/update-custom-fields.md) | 60 requests a minute |
| [Invite a Candidate](https://docs.interviewflowai.com/api-reference/candidates/invite.md), [Invite Candidates in bulk](https://docs.interviewflowai.com/api-reference/candidates/invite-bulk.md) | 100 requests a minute |

Over the limit, requests get `429`. Wait, then retry.

## Requests and responses

Send JSON bodies with `Content-Type: application/json`. Successful responses wrap the result in `data`:

```json theme={null}
{
  "data": { "id": "…" },
  "code": 201,
  "message": "Job created successfully"
}
```

Errors return the HTTP status in `code`, and a readable `message`:

```json theme={null}
{ "code": 401, "message": "Invalid API key" }
```

## Status codes

| Status | Meaning |
| - | - |
| `200`, `201` | Success |
| `400` | The request is invalid. `message` says why. |
| `401` | The `X-API-KEY` header is missing, or the key is invalid |
| `403` | Your plan doesn't include API access |
| `404` | It doesn't exist, or belongs to another Company |
| `429` | Too many requests. Wait, then retry. |
| `5xx` | Something went wrong on our side. Retry with backoff. |

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/external/ingest/job` | [Create an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/create.md) |
| `PUT` | `/api/external/ingest/job/{jobId}` | [Update an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/update.md) |
| `POST` | `/api/external/ingest/candidate` | [Invite a Candidate](https://docs.interviewflowai.com/api-reference/candidates/invite.md) |
| `POST` | `/api/external/ingest/interview` | [Invite Candidates in bulk](https://docs.interviewflowai.com/api-reference/candidates/invite-bulk.md) |
| `POST` | `/api/external/fetch/candidates` | [List Candidates](https://docs.interviewflowai.com/api-reference/candidates/list.md) |
| `PUT` | `/api/external/interview` | [Update a Candidate](https://docs.interviewflowai.com/api-reference/candidates/update.md) |
| `PATCH` | `/api/external/custom-fields` | [Update custom fields](https://docs.interviewflowai.com/api-reference/candidates/update-custom-fields.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.