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

# API overview

> Base URL, authentication, formats and conventions for the Intent Leads REST API.

```text Base URL theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://intentleads.si/api/v1
```

The API can do everything the dashboard can: lanes, keywords, checks, exports, leads, usage, and with an admin key billing, team and API keys.

## Authentication

Send an [API key](/authentication) as a bearer token on every request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://intentleads.si/api/v1/me \
  -H "Authorization: Bearer $INTENT_LEADS_KEY"
```

Endpoints marked **admin** need an admin key; the others work with any key.

## What's free

Only one call uses contacts from your plan: confirming an export (`POST /exports` with `"dry_run": false`). Everything else, including quotes, checks, samples and every download, is free.

## Requests and responses

* Request bodies are JSON (`Content-Type: application/json`), except `PUT /company-list`, which also takes CSV or plain text.
* Responses are JSON. Leads and exports can also be CSV with `format=csv`.
* Dates are `YYYY-MM-DD`; timestamps are ISO 8601 in UTC.
* Lanes are addressed by their code, like `L1`.
* Empty values are `null`.

## Idempotency

Confirming an export needs an `idempotency_key`. Retrying with the same key returns the original export (`"reused": true`) and never buys again. See [Exports](/guides/exports#idempotency-and-retries).

## Paging

`GET /leads` returns up to `limit` leads (1 to 5,000, default 1,000).

* With `since=last`, call again until `has_more` is `false`: each call moves your cursor.
* With `since=YYYY-MM-DD`, pass `next_page` (or the `X-Next-Page` header for CSV) back as `page`.

## Long-running work

Exports and checks run in the background. Start them, then poll:

| Start | Poll | Typical time |
| - | - | - |
| `POST /exports` | `GET /exports/{id}` | A few minutes |
| `POST /lanes/{code}/checks` | `GET /lanes/{code}/checks` | A few minutes |

Poll every 10 to 30 seconds.

## Errors

Errors return a status code and a JSON body with a stable `error` code and a readable `message`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "allowance_exhausted",
  "message": "You've used this period's contacts. Upgrade on the Usage page, or wait for the next period."
}
```

Branch on `error`, not on `message`. See [Errors](/errors) for every code.


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