DevelopersReference
Leads
Visitors the agent qualified or captured, with the verdict and CRM link.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
List leads, newest first
GET /leads
Scope: leads:read. Operation id: listLeads.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
limit | query | integer | Page size, 1 to 200. Default 50. |
cursor | query | string | The nextCursor from the previous page. Opaque; never build one. |
visitorId | query | string (uuid) |
Example request
curl "https://api.showpilot.com/v1/leads?limit=50" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
One page of leads.
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of Lead | yes | |
nextCursor | NextCursor | yes |
Lead
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
visitorId | string or null (uuid) | yes | |
agentId | string or null (uuid) | yes | |
source | string | yes | form_capture or meeting_booked. |
email | string or null | yes | |
name | string or null | yes | |
company | string or null | yes | |
verdict | object or null | yes | The agent's qualification, when it made one. |
status | string | yes | |
ownerUserId | string or null | yes | |
crm | object or null | yes | |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
NextCursor
Pass as cursor for the next page; null on the last page.
Errors
| Status | When |
|---|---|
| 400 | A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code invalid-request. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
One lead
GET /leads/{id}
Scope: leads:read. Operation id: getLead.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string (uuid) |
Example request
curl "https://api.showpilot.com/v1/leads/d0000001-0000-4000-8000-000000000000" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The lead.
Lead
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
visitorId | string or null (uuid) | yes | |
agentId | string or null (uuid) | yes | |
source | string | yes | form_capture or meeting_booked. |
email | string or null | yes | |
name | string or null | yes | |
company | string or null | yes | |
verdict | object or null | yes | The agent's qualification, when it made one. |
status | string | yes | |
ownerUserId | string or null | yes | |
crm | object or null | yes | |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
Errors
| Status | When |
|---|---|
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |
Update a lead's owner, status or CRM link
PATCH /leads/{id}
Scope: leads:write. Operation id: updateLead.
Send only the fields to change; null clears a field. Requires Idempotency-Key.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
Idempotency-Key | header | string | Any unique string, up to 200 characters, chosen by the caller. A retry with the same key and the same request replays the stored response (with the header Idempotent-Replayed set to true); the same key with a different request is refused. Keys are remembered for 24 hours. |
id | path | string (uuid) |
Example request
curl "https://api.showpilot.com/v1/leads/d0000001-0000-4000-8000-000000000000" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
The lead after the change.
Lead
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string (uuid) | yes | |
visitorId | string or null (uuid) | yes | |
agentId | string or null (uuid) | yes | |
source | string | yes | form_capture or meeting_booked. |
email | string or null | yes | |
name | string or null | yes | |
company | string or null | yes | |
verdict | object or null | yes | The agent's qualification, when it made one. |
status | string | yes | |
ownerUserId | string or null | yes | |
crm | object or null | yes | |
createdAt | string (date-time) | yes | |
updatedAt | string (date-time) | yes |
Errors
| Status | When |
|---|---|
| 400 | A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code invalid-request. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 409 | The write cannot apply. Code conflict when the object's state refuses it (a follow-up already closed); code idempotency-mismatch when the Idempotency-Key was already used for a different request. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |