> For the complete documentation index, see [llms.txt](https://docs.reach-book.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reach-book.com/developers/get-started/making-requests.md).

# Call the API

Send the token in the `Authorization` header. Lists return `data`, `links` and `meta` for paging.

## List prospects

```bash
curl "https://reach-book.com/api/v1/prospects?search=dental" \
  -H "Authorization: Bearer rbk_YOUR_TOKEN" \
  -H "Accept: application/json"
```

Prospects are listed newest first. Filter with `search`, and page through with `page` and `per_page` (up to 100).

## Create a prospect

```bash
curl -X POST https://reach-book.com/api/v1/prospects \
  -H "Authorization: Bearer rbk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"company":"Acme Dental","domain":"acmedental.example","contact_name":"Dana Reyes","contact_email":"dana@acmedental.example"}'
```

Only `company` is required. Domain, website, location, contact, notes, `tags` and `owner_id` are optional.

## Update a prospect

```bash
curl -X PATCH https://reach-book.com/api/v1/prospects/PROSPECT_ID \
  -H "Authorization: Bearer rbk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"tags":["dental","priority"]}'
```

Only the fields you send change. `tags` replaces the prospect's tags.

## Errors

| Status | Meaning                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `401`  | The token is missing, invalid, expired or revoked, or its workspace is suspended.                     |
| `403`  | The token doesn't include the ability this endpoint needs.                                            |
| `404`  | Nothing with that id in this workspace (or, for campaigns, not one of the token creator's campaigns). |
| `422`  | Validation failed. `errors` lists the problem for each field.                                         |
| `429`  | More than 60 requests in a minute. Wait for the seconds in the `Retry-After` header.                  |

Every field, response and error for each endpoint is in the API reference, starting with [Prospects](/developers/api-reference/prospects.md).