Leads. The contacts your agent captured.
Read the names, emails, phone numbers and companies visitors gave in conversations, update them and remove them. Use the lead.captured webhook to hear about new ones straight away.
On this page
List leads
/chatbots/{chatbotId}/leadsThe chatbot's leads, newest first.
Permission: leads:read
Path parameters
chatbotIdThe chatbot. Listed by GET /chatbots.
Query parameters
limitItems per page, 1 to 100. Default 20.
cursormeta.pagination.nextCursor from the previous page.
contacttrue: only leads with an email address or phone number.
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/leads?contact=true \
-H "Authorization: Bearer $SIMPLYBOOST_TOKEN"Response 200 OK
{
"ok": true,
"data": {
"leads": [
{
"id": "7b1d2e9c-41f0-4c6a-8f0e-2a9d5c3b1e77",
"chatbotId": "f45268b2-1980-470d-865d-5048a89aedce",
"threadId": "3f0c9a52-6d1e-4b0a-9c51-0f3e2c7d8a14",
"name": "Sanne de Vries",
"email": "sanne@studiolicht.nl",
"phone": null,
"company": "Studio Licht",
"channel": "web",
"converted": false,
"capturedAt": "2026-10-07T09:31:12+00:00"
}
]
},
"meta": { "requestId": "req_…", "pagination": { "limit": 20, "hasMore": false, "nextCursor": null } }
}Response fields
data.leads[].idThe lead's ID.
data.leads[].chatbotIdThe chatbot that captured it.
data.leads[].threadIdThe conversation it came from, when known.
data.leads[].nameName the visitor gave.
data.leads[].emailEmail address.
data.leads[].phonePhone number.
data.leads[].companyCompany.
data.leads[].channelChannel it was captured on: web, api, whatsapp, instagram or facebook.
data.leads[].convertedWhether you marked it as converted.
data.leads[].capturedAtWhen it was captured.
meta.paginationlimit, hasMore (true when there is another page) and nextCursor (null on the last page).
Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No such chatbot, or this token may not see it. |
| 400 | validation_error | limit or cursor is not valid. |
Get a lead
/chatbots/{chatbotId}/leads/{leadId}One lead.
Permission: leads:read
Path parameters
chatbotIdThe chatbot. Listed by GET /chatbots.
leadIdThe lead, from lead.id.
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/leads/LEAD_ID \
-H "Authorization: Bearer $SIMPLYBOOST_TOKEN"Response 200 OK
{
"ok": true,
"data": {
"lead": {
"id": "7b1d2e9c-41f0-4c6a-8f0e-2a9d5c3b1e77",
"chatbotId": "f45268b2-1980-470d-865d-5048a89aedce",
"threadId": "3f0c9a52-6d1e-4b0a-9c51-0f3e2c7d8a14",
"name": "Sanne de Vries",
"email": "sanne@studiolicht.nl",
"phone": null,
"company": "Studio Licht",
"channel": "web",
"converted": false,
"capturedAt": "2026-10-07T09:31:12+00:00"
}
},
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}Response fields
data.lead.idThe lead's ID.
data.lead.chatbotIdThe chatbot that captured it.
data.lead.threadIdThe conversation it came from, when known.
data.lead.nameName the visitor gave.
data.lead.emailEmail address.
data.lead.phonePhone number.
data.lead.companyCompany.
data.lead.channelChannel it was captured on: web, api, whatsapp, instagram or facebook.
data.lead.convertedWhether you marked it as converted.
data.lead.capturedAtWhen it was captured.
Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No such chatbot or lead, or this token may not see it. |
Update a lead
/chatbots/{chatbotId}/leads/{leadId}Change only the fields you send. Send null to clear a contact field.
Permission: leads:write
Path parameters
chatbotIdThe chatbot. Listed by GET /chatbots.
leadIdThe lead, from lead.id.
Body (JSON)
nameUp to 255 characters.
emailA valid email address, up to 254 characters.
phoneUp to 50 characters.
companyUp to 255 characters.
convertedMark the lead as converted, or not.
curl -X PATCH https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/leads/LEAD_ID \
-H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
-H "Content-Type: application/json" \
-d '{"converted": true, "company": "Studio Licht B.V."}'Response 200 OK
{
"ok": true,
"data": { "lead": { "id": "7b1d…", "company": "Studio Licht B.V.", "converted": true, … } },
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}Response fields
data.lead.idThe lead's ID.
data.lead.chatbotIdThe chatbot that captured it.
data.lead.threadIdThe conversation it came from, when known.
data.lead.nameName the visitor gave.
data.lead.emailEmail address.
data.lead.phonePhone number.
data.lead.companyCompany.
data.lead.channelChannel it was captured on: web, api, whatsapp, instagram or facebook.
data.lead.convertedWhether you marked it as converted.
data.lead.capturedAtWhen it was captured.
Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A field is not one of the five above, has the wrong type or is too long, or email is not valid. |
| 404 | not_found | No such chatbot or lead, or this token may not see it. |
Delete a lead
/chatbots/{chatbotId}/leads/{leadId}Removes the lead from the leads list and the API. The conversation it came from is kept.
Permission: leads:delete
Path parameters
chatbotIdThe chatbot. Listed by GET /chatbots.
leadIdThe lead, from lead.id.
curl -X DELETE https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/leads/LEAD_ID \
-H "Authorization: Bearer $SIMPLYBOOST_TOKEN"Response 200 OK
{
"ok": true,
"data": { "id": "7b1d2e9c-41f0-4c6a-8f0e-2a9d5c3b1e77", "deleted": true },
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}Response fields
data.idThe deleted lead's ID.
data.deletedAlways true.
Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No such chatbot or lead, or this token may not see it. |