Overview
Calls
Phone Numbers
Lead lists
Leads
Webhooks
Account
curl --request POST \
--url https://api.topcalls.ai/v1/leads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"phone_number": "<string>",
"list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com",
"status": "New",
"notes": "<string>",
"notes_append": "<string>",
"tags": [],
"metadata": {}
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"phone_number": "<string>",
"status": "New",
"tags": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"existed": true,
"email": "jsmith@example.com",
"notes": "<string>",
"metadata": {},
"converted_at": "2023-11-07T05:31:56Z",
"list_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}Create or attach lead
Creates a single lead and assigns it to the given list. Idempotent on
(account_id, phone_number): if a lead with this phone number already
exists in the account, the existing lead is attached to the requested
list (no error) and the response carries existed: true with HTTP 200.
A genuinely new lead returns HTTP 201 with existed: false.
Requires scope: leads:write.
curl --request POST \
--url https://api.topcalls.ai/v1/leads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"phone_number": "<string>",
"list_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"email": "jsmith@example.com",
"status": "New",
"notes": "<string>",
"notes_append": "<string>",
"tags": [],
"metadata": {}
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"phone_number": "<string>",
"status": "New",
"tags": [
"<string>"
],
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"existed": true,
"email": "jsmith@example.com",
"notes": "<string>",
"metadata": {},
"converted_at": "2023-11-07T05:31:56Z",
"list_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}Documentation Index
Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Use Authorization: Bearer tc_live_xxxxx
Body
1Phone number in E.164 format (also validated as dialable by libphonenumber-js — country codes that don't exist are rejected)
^\+[1-9]\d{8,14}$New, Contacted, Converted, Unsubscribed Response
Existing lead attached to the requested list (idempotent)
Result of POST /v1/leads. existed=false (returned with HTTP 201) means
the phone number was new and a fresh lead row was created. existed=true
(returned with HTTP 200) means a lead with this phone number already
existed in the account; it has been (idempotently) attached to the
requested list, and list_ids reflects every list the lead is currently
in. The lead's other fields (name, email, notes, tags, metadata) are NOT
overwritten on the attach path - use PATCH /v1/leads/{id} for that.
^\+[1-9]\d{8,14}$New, Contacted, Converted, Unsubscribed false if a new lead was created; true if an existing lead was attached.