Taalk Help Center

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 phone and firstName as required. Taalk drops a contact only when it has neither phone nor email; send firstName anyway so the agent can greet the person.
  • Attempt counts, answered status and dnc in 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" becomes 2134. 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. Use POST.
  • 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.