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.

4 min read Updated

List leads

GET/v1/agents/{agent_id}/leads

Permission leads:read

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 20 characters.
start_datestringqueryFirst day, as YYYY-MM-DD (UTC).
end_datestringqueryLast day, inclusive, as YYYY-MM-DD (UTC).
readbooleanquerytrue returns only read leads, false only unread ones.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].datestring or nullWhen it came in, in UTC.
data[].idintegerLead id.
data[].readbooleantrue once it was opened in the portal or marked as read.
data[].session_idstring or nullInternal session id of the conversation (api-conv_... for API conversations).
data[].typestring or nullKind of lead form, e.g. contact.
data[].versionintegerVersion of the lead. Send it as expected_version with a change or deletion.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/agents/c3e02486-f107-40c4-ac4d-e6155111bc8e/leads" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

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}

Permission leads:read

The lead with all its fields and version.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
lead_idrequiredintegerpathLead id.

Response 200 OK

FieldTypeDescription
agent_idstringThe agent's id.
dataobjectThe lead.
data.datestring or nullWhen it came in, in UTC.
data.idintegerLead id.
data.paramsobjectThe fields the visitor gave (name, email, ...).
data.readbooleantrue once it was opened in the portal or marked as read.
data.session_idstring or nullInternal session id of the conversation (api-conv_... for API conversations).
data.typestring or nullKind of lead form, e.g. contact.
resource_idstringThe lead id as a string.
versionintegerVersion 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"

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}

Permission leads:writeNeeds an integration with read and change access

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
lead_idrequiredintegerpathLead id.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
readrequiredbooleantrue marks the lead as read, false as unread.
expected_versioninteger or nullThe 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

FieldTypeDescription
replayedbooleantrue: this Idempotency-Key was used before, and the stored result is returned.
resourceobjectThe lead after the change.
resource.agent_idstringThe agent's id.
resource.dataobjectThe lead.
resource.data.datestring or nullWhen it came in, in UTC.
resource.data.idintegerLead id.
resource.data.paramsobjectThe fields the visitor gave (name, email, ...).
resource.data.readbooleantrue once it was opened in the portal or marked as read.
resource.data.session_idstring or nullInternal session id of the conversation (api-conv_... for API conversations).
resource.data.typestring or nullKind of lead form, e.g. contact.
resource.resource_idstringThe lead id as a string.
resource.versionintegerVersion 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
}'

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}

Permission leads:writeNeeds an integration with read and change access

Deletes the lead and its lead.created webhook event. Without expected_version the current version is used.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.
lead_idrequiredintegerpathLead id.
expected_versionintegerqueryThe lead's version from your last read. A changed lead answers 409 version_conflict. At least 1.
Idempotency-KeystringheaderAny 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

FieldTypeDescription
agent_idstringThe agent's id.
deletedbooleantrue: it is deleted.
idintegerId 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)"

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

Permission exports:read

A CSV page (csv, row_count, next_cursor); call again with after for the next page.

Parameters

ParameterTypeDescription
agent_idrequiredstringpathThe agent's id, from GET /v1/agents.

Request body

FieldTypeDescription
kindrequiredstringWhat to export. One of conversations, leads.
afterstring or nullThe next_cursor of the previous page. Up to 20 characters.
end_datestring or nullLast day, inclusive, as YYYY-MM-DD (UTC).
limitintegerRows per page. Default 100. 1 to 100.
start_datestring or nullFirst day, as YYYY-MM-DD (UTC).

Response 200 OK

FieldTypeDescription
csvstringThe CSV text of this page, header row first.
filenamestringA file name for it.
mime_typestringThe CSV media type.
next_cursorstring or nullPass it as after for the next page. null when everything is exported.
row_countintegerRows on this page.
formula_safebooleantrue: cells that start with =, +, - or @ carry a leading quote, so spreadsheets do not run them.
header_includedbooleantrue: 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"
}'

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.

Next steps