# Dover API overview

> Authenticate with a Bearer API key, check the ATS Premium requirement, and find every Dover API endpoint for jobs, candidates, and custom careers pages.

The Dover API lets you add candidates to active jobs, list recent hires, or host a custom careers page (list postings, render a job page, and submit applications with a resume) from your own backend.

This page covers what every request needs. For the parameters, request bodies, and responses of each endpoint, see the [API reference](https://docs.dover.com/api/reference/). For the setup walkthrough and FAQ, see the [Dover API help article](https://docs.dover.com/api/dover-api/).

## Base URL

Every request goes to `https://app.dover.com`, and every endpoint lives under `/api/v1/external/`.

## Authentication

Authenticate each request with your API key in the `Authorization` header:

```http
Authorization: Bearer <API_KEY>
```

To create or copy a key, open [Settings → API Key](https://app.dover.com/settings/company/api-key) in the Dover app.

:::caution
Call the API from your backend only. Do not put the key in browser JavaScript or in anything else your visitors can read.
:::

## ATS Premium requirement

The API is available on the ATS Premium plan. On any other plan, every endpoint responds with `403` and `code: ats_premium_required`:

```json
{
  "code": "ats_premium_required",
  "detail": "The Dover API is available on the ATS Premium plan.",
  "upgrade_url": "https://app.dover.com/settings/company/billing?upgrade=1"
}
```

## Endpoints

| Endpoint | What it does |
| --- | --- |
| `GET /api/v1/external/jobs` | [List active public jobs](https://docs.dover.com/api/reference/operations/externalapilistjobs/) and the hiring pipeline stages you can add candidates to. |
| `POST /api/v1/external/add-candidate` | [Add one candidate](https://docs.dover.com/api/reference/operations/externalapiaddcandidate/) to a job, with an optional resume. |
| `POST /api/v1/external/bulk-add-candidates` | [Add many candidates](https://docs.dover.com/api/reference/operations/externalapibulkaddcandidates/) to jobs in one JSON request. |
| `GET /api/v1/external/candidates` | [List recently hired candidates](https://docs.dover.com/api/reference/operations/externalapilisthiredcandidates/), optionally for one job. |
| `GET /api/v1/external/job-postings` | [List the jobs](https://docs.dover.com/api/reference/operations/externalapilistjobpostings/) published to your Dover careers page. |
| `GET /api/v1/external/job-postings/{id}` | [Get a job page](https://docs.dover.com/api/reference/operations/externalapigetjobposting/): description, locations, compensation, and the application questions to render. |
| `POST /api/v1/external/job-postings/{id}/applications` | [Submit an application](https://docs.dover.com/api/reference/operations/externalapisubmitjobpostingapplication/) to a posting, with a resume and answers. |

The careers-page endpoints only return jobs published to your Dover careers page. Submitting an application creates an inbound application, which is a different pipeline from adding a candidate.

## Quick start

1. List your jobs. Each job has an `id` and a list of `hiring_pipeline_stages`, each with an `id` and a `name`.

   ```bash
   curl https://app.dover.com/api/v1/external/jobs \
     -H "Authorization: Bearer $DOVER_API_KEY"
   ```

2. Add a candidate to one of those jobs. `channel`, `job_id`, `candidate_first_name`, and `candidate_last_name` are required, and you must pass exactly one of `hiring_pipeline_stage_id` or `hiring_pipeline_stage_name`.

   ```bash
   curl -X POST https://app.dover.com/api/v1/external/add-candidate \
     -H "Authorization: Bearer $DOVER_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "channel": "SOURCED",
       "job_id": "<JOB_ID>",
       "hiring_pipeline_stage_id": "<STAGE_ID>",
       "candidate_first_name": "Ada",
       "candidate_last_name": "Lovelace",
       "candidate_email": "ada@example.com"
     }'
   ```

   `channel` is how the candidate entered your pipeline: `AGENCY`, `REFERRAL`, `SOURCED`, or `APPLIED`. It drives attribution in reporting, and some channels need extra fields; the [reference](https://docs.dover.com/api/reference/operations/externalapiaddcandidate/) lists them.

## OpenAPI specification

The full machine-readable specification is available at [app.dover.com/docs/api.json](https://app.dover.com/docs/api.json). Use it to generate a client or to give an AI coding tool the exact endpoints and fields.

## Need help?

Email [support@dover.com](mailto:support@dover.com).