API Guide: Contacts
Push contacts into a campaign, update them, and pull results back out. Base URL https://api.taalk.ai/api, header Authorization: Bearer <TAALK_API_KEY>. For keys and errors, see API and Developer Access.
Contacts always belong to a campaign. To upload in the console instead, see Uploading Contacts.
Add, update and remove contacts
POST /campaign2s/{id}/contacts takes one body with up to four parts. Use any of them in the same request.
| Part | Type | What it does |
|---|---|---|
append |
array of contacts | Adds contacts. A contact already in the campaign (same phone, or same email if there's no phone) is updated instead |
update |
object | Updates existing contacts. Key: contact ID, phone or email. Value: the fields to change |
remove |
array | Removes contacts by contact ID, phone or email. Can't be undone |
shuffle |
boolean | Randomizes dialing order. With append, shuffles the new batch; on its own, reshuffles contacts not yet answered and not on DNC |
curl -X POST https://api.taalk.ai/api/campaign2s/<CAMPAIGN_ID>/contacts \
-H "Authorization: Bearer $TAALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"append": [
{ "phone": "+17045550123", "firstName": "Sarah", "lastName": "Chen", "email": "[email protected]", "Taalk_policy": "PLX-9921" },
{ "phone": "+19805550188", "firstName": "Marcus" }
],
"update": { "+17045550199": { "Taalk_priority": "high" } },
"remove": ["+17045550142"]
}'
The response returns the campaign in payload and what changed:
{ "payload": { "_id": "<CAMPAIGN_ID>", "name": "June Renewals" },
"change": { "inserted": 2, "updated": 1, "removed": 1, "deduplicated": 0 } }
| Count | Meaning |
|---|---|
inserted |
New contacts added |
updated |
Contacts changed, by update or by re-uploading an existing contact |
deduplicated |
Of those, contacts that were already in the campaign and got re-uploaded |
removed |
Contacts removed |
Duplicates inside one request are dropped and not counted. Keep each request under 5 MB.
Contact fields
| Field | Notes |
|---|---|
phone |
Use E.164, for example +17045550123. US numbers are stored as 10 digits without +1 |
firstName, lastName |
The agent uses these for the contact's name |
email |
A contact with an email and no phone is allowed (email campaigns) |
Taalk_<anything> |
Your own fields, for example Taalk_policy. Use them in scripts as {Taalk_policy} and they appear in exports |
callbackAt |
A date to call back |
- The API docs list
phoneandfirstNameas required. Taalk drops a contact only when it has neitherphonenoremail; sendfirstNameanyway so the agent can greet the person. - Attempt counts, answered status and
dncin an upload are ignored. Numbers are flagged by the campaign's DNC Detection setting. See DNC Detection. - Re-uploading an existing contact keeps its history. If the campaign has Retry for Duplcated Contact Upload on, its attempts are reset so it's called again.
- New contacts trigger the campaign's New Contact notifications. See Notification Webhooks.
Update one contact
POST /campaign2s/{id}/contacts/{cid}. cid is the contact ID, phone or email. Send only the fields to change. The phone can't be changed.
curl -X POST https://api.taalk.ai/api/campaign2s/<CAMPAIGN_ID>/contacts/+17045550123 \
-H "Authorization: Bearer $TAALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "Taalk_Success": true, "Taalk_appointment": "2026-11-20" }'
Returns { "payload": { "modified": 1, "contact": { ... } } }, or 404 if the contact isn't found. Setting Taalk_Success to true also marks the contact's last call as a success.
Values that look like numbers are saved as numbers when you update a contact, so
"02134"becomes2134. Add a letter or prefix if leading zeros matter.
List and read contacts
curl "https://api.taalk.ai/api/campaign2s/<CAMPAIGN_ID>/contacts?answered=1&tz=-5&range=2026-11-01,2026-11-14&pageSize=200" \
-H "Authorization: Bearer $TAALK_API_KEY"
| Parameter | What it does |
|---|---|
page, pageSize |
Page from 0. Default 10, maximum 200 (more returns 400) |
range |
start,end dates. Filters by when the contact was added |
tz |
UTC offset in hours for range, for example -5 |
phone |
Starts with this number. Comma-separate several |
name |
First or last name contains this text |
succeed |
1: transferred, texted or opened a link |
answered |
1 answered, 0 not |
dnc |
1 on DNC, 0 not |
callback |
1: waiting for a callback |
The response is { "payload": [ ...contacts ], "total": 1482 }. Each contact has try (attempts), answered, hasRedirectCall (transferred), hasSentSMS, needCallback, dnc, session (last call ID), calledAt and Taalk_Success.
| Method | Endpoint | What it returns |
|---|---|---|
| GET | /campaign2s/{id}/contacts/{cid} |
One contact (cid = ID or phone). payload is null if not found |
| GET | /campaign2s/{id}/contacts/{cid}/sessions |
Calls and messages for one contact |
| GET | /campaign2s/{id}/contacts/fields |
Names of the Taalk_ fields in use |
| GET | /contacts |
Search across all campaigns. Filters phone, name, campaign |
Export
| Endpoint | Format |
|---|---|
GET /campaign2s/{id}/contacts/export/csv |
CSV for one campaign |
GET /campaign2s/{id}/contacts/export/jsonl |
One JSON object per line |
GET /contacts/export/csv?campaign=<ID>, /contacts/export/jsonl |
Across campaigns, or one with campaign |
CSV columns: First Name, Last Name, Created At, Updated At, Engaged At, DNC, Phone, Dial, Answered, Messaged, Clicked, Transferred, Duration, Duration After Transfer, then your Taalk_ fields. Use exports instead of paging through large lists.
Contact report
GET /campaign2s/{id}/contacts/report?tz=-5 returns timeline (contacts added per day, by result) and counts. tz is required. Add range to pick dates; without it you get the month up to the latest upload. This is the data behind the Contacts tab. See Contacts Tab Overview.
If the report takes too long you get 413 with Retry-After: 60. Retry after a minute.
Leads from a web form
POST /contact_form/{campaignId} adds one lead to a campaign. Send firstName, lastName, phone, email, and optionally callbackAt. Other fields are saved as Taalk_<field>. Use a key with the Contact Form scope, so the key can do nothing else. See API Keys. Returns 400 if there's no phone and no email.
What the Contacts API can't do (yet)
- Update with
PATCH. UsePOST. - Change a contact's phone number. Remove it and add it again.
- Manage saved contact lists (the ones behind From List in the console). They aren't part of the public API.