Leads API
Read leads and update their status from your own systems with a scoped API key.
The Leads API lets your CRM, data warehouse or automation read your leads and update their status.
Create keys in Studio under Integrations → Leads API → New key. Each key has:
- a name;
- grants:
leads:read(Read leads) and, optionally,leads:write-status(Change lead status); - an expiry of 30, 90, 180 days or 1 year.
Keys look like atl_lead_ followed by 43 characters. They are shown once, stored only as a fingerprint, checked on every request and can be revoked at any time (Revoke key). A site environment can have up to 20 active keys. Creating a key can require a second confirmation on your phone.
Base URL and authentication
Section titled “Base URL and authentication”https://<delivery host>/v1/leads-api/environments/{environmentId}Authorization: Bearer atl_lead_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXResponses are Cache-Control: private, no-store. Errors use the RFC 9457 application/problem+json format.
List leads
Section titled “List leads”GET /leads?since=2026-10-01T00:00:00Z&limit=50&cursor=…
| Parameter | Notes |
|---|---|
since |
Only leads updated at or after this time. ISO 8601 with a time zone |
limit |
1 to 200, default 50 |
cursor |
The nextCursor from the previous response |
Leads come oldest change first. The response is { "leads": [ … ], "nextCursor": "…" | null }. Keep paging until nextCursor is null, and store the last updatedAt to fetch only changes next time.
The list includes merged, anonymised and test leads. Check mergedInto, anonymisedAt and isTest.
Get one lead
Section titled “Get one lead”GET /leads/{leadId}
| Field | Notes |
|---|---|
id, source |
Source is the form or chatbot the lead came from |
form |
{ key, name }, or null for chatbot leads |
name, email, phone, company, message |
Empty after retention removed personal data |
details |
Any other answers |
status |
new, contacted, qualified, won, lost or spam |
isTest |
Studio test submissions |
version |
Send it back when you change the status |
mergedInto, anonymisedAt |
Set when the lead was merged or anonymised |
createdAt, updatedAt |
ISO 8601 timestamps |
Change a lead’s status
Section titled “Change a lead’s status”PATCH /leads/{leadId}/status with { "status": "qualified", "expectedVersion": 4 }. Needs the Change lead status grant. The change appears in the lead’s history as made by the key.
Errors and limits
Section titled “Errors and limits”| Status | Code | Meaning |
|---|---|---|
| 401 | CP_UNAUTHENTICATED |
Missing, wrong, expired or revoked key |
| 403 | CP_FORBIDDEN |
The key lacks the grant for this request |
| 404 | CP_NOT_FOUND |
No such lead in this environment |
| 409 | CP_VERSION_CONFLICT |
The lead changed since you read it. Read it again |
| 422 | REQUEST_SCHEMA_INVALID |
The request body or a parameter is not valid |
| 422 | CURSOR_INVALID |
The cursor could not be read |
| 429 | RATE_LIMITED |
More than 300 requests a minute. Wait and retry |
The rate limit is applied per Atlas API server, so treat 300 requests a minute as a ceiling, not a guarantee.