Leads and exports
The leads an agent collected on any channel, with every field the visitor gave, and CSV exports of leads or conversations. New leads also arrive as the lead.created webhook.
- GET
/v1/agents/{agent_id}/leadsList leads - GET
/v1/agents/{agent_id}/leads/{lead_id}Get a lead - PATCH
/v1/agents/{agent_id}/leads/{lead_id}Mark a lead as read or unread - DELETE
/v1/agents/{agent_id}/leads/{lead_id}Delete a lead - POST
/v1/agents/{agent_id}/exportsExport conversations or leads as CSV
List leads
GET/v1/agents/{agent_id}/leads
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 20 characters. |
start_date | stringquery | First day, as YYYY-MM-DD (UTC). |
end_date | stringquery | Last day, inclusive, as YYYY-MM-DD (UTC). |
read | booleanquery | true returns only read leads, false only unread ones. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].date | string or null | When it came in, in UTC. |
data[].id | integer | Lead id. |
data[].read | boolean | true once it was opened in the portal or marked as read. |
data[].session_id | string or null | Internal session id of the conversation (api-conv_... for API conversations). |
data[].type | string or null | Kind of lead form, e.g. contact. |
data[].version | integer | Version of the lead. Send it as expected_version with a change or deletion. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"data": [
{
"date": "2026-11-10T17:00:37.539882",
"id": 46,
"read": false,
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"type": "contact",
"version": 2
}
],
"next_cursor": null,
"object": "list"
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Get a lead
GET/v1/agents/{agent_id}/leads/{lead_id}
The lead with all its fields and version.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
lead_idrequired | integerpath | Lead id. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
data | object | The lead. |
data.date | string or null | When it came in, in UTC. |
data.id | integer | Lead id. |
data.params | object | The fields the visitor gave (name, email, ...). |
data.read | boolean | true once it was opened in the portal or marked as read. |
data.session_id | string or null | Internal session id of the conversation (api-conv_... for API conversations). |
data.type | string or null | Kind of lead form, e.g. contact. |
resource_id | string | The lead id as a string. |
version | integer | Version of the lead. Send it as expected_version with a change or deletion. |
Example request
curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"data": {
"date": "2026-11-10T17:00:37.539882",
"id": 46,
"params": {
"email": "anna@example.com",
"name": "Anna Example"
},
"read": false,
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"type": "contact"
},
"resource_id": "46",
"version": 2
}Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.
Mark a lead as read or unread
PATCH/v1/agents/{agent_id}/leads/{lead_id}
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
lead_idrequired | integerpath | Lead id. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Request body
| Field | Type | Description |
|---|---|---|
readrequired | boolean | true marks the lead as read, false as unread. |
expected_version | integer or null | The version from your last read. If the resource changed since, the call answers 409 version_conflict. Leave it out to change the current version. At least 1. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
replayed | boolean | true: this Idempotency-Key was used before, and the stored result is returned. |
resource | object | The lead after the change. |
resource.agent_id | string | The agent's id. |
resource.data | object | The lead. |
resource.data.date | string or null | When it came in, in UTC. |
resource.data.id | integer | Lead id. |
resource.data.params | object | The fields the visitor gave (name, email, ...). |
resource.data.read | boolean | true once it was opened in the portal or marked as read. |
resource.data.session_id | string or null | Internal session id of the conversation (api-conv_... for API conversations). |
resource.data.type | string or null | Kind of lead form, e.g. contact. |
resource.resource_id | string | The lead id as a string. |
resource.version | integer | Version of the lead. Send it as expected_version with a change or deletion. |
Example request
curl -X PATCH "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"expected_version": 2,
"read": true
}'import os, uuid, requests
r = requests.patch(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"expected_version": 2,
"read": True,
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json"
},
body: JSON.stringify({
"expected_version": 2,
"read": true
})
});
console.log(res.status, await res.json());Response 200 OK
{
"replayed": false,
"resource": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"data": {
"date": "2026-11-10T17:00:37.539882",
"id": 46,
"params": {
"email": "anna@example.com",
"name": "Anna Example"
},
"read": true,
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"type": "contact"
},
"resource_id": "46",
"version": 3
}
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Delete a lead
DELETE/v1/agents/{agent_id}/leads/{lead_id}
Deletes the lead and its lead.created webhook event. Without expected_version the current version is used.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
lead_idrequired | integerpath | Lead id. |
expected_version | integerquery | The lead's version from your last read. A changed lead answers 409 version_conflict. At least 1. |
Idempotency-Key | stringheader | Any unique string up to 255 characters. The same key with the same body returns the stored result for 24 hours instead of running again. See Retries. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
agent_id | string | The agent's id. |
deleted | boolean | true: it is deleted. |
id | integer | Id of the deleted lead. |
Example request
curl -X DELETE "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"import os, uuid, requests
r = requests.delete(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46",
headers={
"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads/46", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Idempotency-Key": crypto.randomUUID()
}
});
console.log(res.status, await res.json());Response 200 OK
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"deleted": true,
"id": 46
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.
Export conversations or leads as CSV
POST/v1/agents/{agent_id}/exports
A CSV page (csv, row_count, next_cursor); call again with after for the next page.
Parameters
| Parameter | Type | Description |
|---|---|---|
agent_idrequired | stringpath | The agent's id, from GET /v1/agents. |
Request body
| Field | Type | Description |
|---|---|---|
kindrequired | string | What to export. One of conversations, leads. |
after | string or null | The next_cursor of the previous page. Up to 20 characters. |
end_date | string or null | Last day, inclusive, as YYYY-MM-DD (UTC). |
limit | integer | Rows per page. Default 100. 1 to 100. |
start_date | string or null | First day, as YYYY-MM-DD (UTC). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
csv | string | The CSV text of this page, header row first. |
filename | string | A file name for it. |
mime_type | string | The CSV media type. |
next_cursor | string or null | Pass it as after for the next page. null when everything is exported. |
row_count | integer | Rows on this page. |
formula_safe | boolean | true: cells that start with =, +, - or @ carry a leading quote, so spreadsheets do not run them. |
header_included | boolean | true: the first line is the header row. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/exports" \
-H "Authorization: Bearer $ULTIMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"end_date": "2026-11-10",
"kind": "leads",
"limit": 100,
"start_date": "2026-11-01"
}'import os, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/exports",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
json={
"end_date": "2026-11-10",
"kind": "leads",
"limit": 100,
"start_date": "2026-11-01",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/exports", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"end_date": "2026-11-10",
"kind": "leads",
"limit": 100,
"start_date": "2026-11-01"
})
});
console.log(res.status, await res.json());Response 200 OK
{
"csv": "id,date,session_id,params,read,type\r\n46,2026-11-10 17:00:37.539882,api-conv_8TFivGiB5wHJqdt7FfRZkFYH,\"{\"\"name\"\": \"\"Anna Example\"\", \"\"email\"\": \"\"anna@example.com\"\"}\",False,contact\r\n",
"filename": "leads.csv",
"formula_safe": true,
"header_included": true,
"mime_type": "text/csv; charset=utf-8",
"next_cursor": null,
"row_count": 1
}Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.