> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.confirm.global/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.confirm.global/_mcp/server.

# API Reference

The CONFIRM API lets you read and manage your organization's candidates, jobs, applications, and background checks from your own systems.

> **Note**
>
> The API is in **Early Access**. Talk to your CONFIRM account team before you build an integration, so we can help you set it up and let you know about changes ahead of time.

## Base URL

```
https://api.confirm.global
```

All endpoints documented here are under the `/api/v1/` prefix.

## Authentication

Every request must include a bearer token:

```
Authorization: Bearer <token>
```

Tokens are issued per user session today (the same JWT your CONFIRM login uses). Dedicated API keys are planned for a future release; until then, contact CONFIRM for help obtaining a token for integration use.

## Organization scoping

Requests operate within your organization. Your token determines which organization you act as, and you can only read or modify candidates, jobs, applications, and background checks that belong to it. Your user's role also determines which actions are allowed — for example, write endpoints require write permission on the relevant resource.

## Resources

| Resource              | Description                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Candidates**        | People who applied to your jobs: list and search, update contact details, view activity timelines, advance to interview scheduling, send evaluations, and manage the blocklist. |
| **Jobs**              | Role definitions: create, update, copy, and close jobs, list a job's applications, and manage per-job knowledge base documents.                                                 |
| **Applications**      | A candidate's application to a specific job: read full detail, move through pipeline stages, schedule and reschedule interviews, reject, hire, or withdraw.                     |
| **Background Checks** | Initiate background checks for an application, track their status, and list available check services and pipelines.                                                             |

## Example: list candidates

```bash
curl "https://api.confirm.global/api/v1/candidates?limit=10&page=1" \
  -H "Authorization: Bearer $CONFIRM_TOKEN"
```

A successful response returns a paginated list:

```json
{
  "data": [
    {
      "candidate_id": "6f4a1c2e-...",
      "first_name": "Jordan",
      "last_name": "Lee",
      "email": "jordan@example.com",
      "phone": "+15555550123",
      "source": "indeed"
    }
  ],
  "pagination": { "total": 128, "page": 1, "limit": 10, "total_pages": 13 }
}
```

## Errors

Errors return a consistent envelope with a machine-readable code and a request ID you can share with support:

```json
{
  "error": {
    "code": "CANDIDATE_NOT_FOUND",
    "message": "Candidate not found",
    "request_id": "3f2b8c1e-9d4a-4b6f-8e2a-1c5d7f9a0b3e"
  }
}
```

Every response also carries the request ID in an `X-Request-ID` header. To trace a request through your own logs, send your own `X-Request-ID` header and CONFIRM will use that value instead of generating one.