Create or attach lead - TopCalls Voice API

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>", "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" ] }

Authorizations

Authorization

string

header

required

Use Authorization: Bearer tc_live_xxxxx

Body

application/json

name

string

required

Minimum string length: 1

phone_number

string

required

Phone number in E.164 format (also validated as dialable by libphonenumber-js — country codes that don't exist are rejected)

Pattern: ^\+[1-9]\d{8,14}$

list_id

string<uuid>

required

string<email>

status

enum<string>

default:New

Available options:

New,

Contacted,

Converted,

Unsubscribed

notes

string

notes_append

string

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.

string<uuid>

required

account_id

string<uuid>

required

name

string

required

phone_number

string

required

Pattern: ^\+[1-9]\d{8,14}$

status

enum<string>

required

Available options:

New,

Contacted,

Converted,

Unsubscribed