API and Developer Access
The Taalk REST API lets your own systems place calls, run campaigns, push contacts, check Do-Not-Call status and pull results. This page is the starting point: where keys live, how to authenticate, limits, errors and a map of every public endpoint.
Before you start
- You need a paid plan. Free workspaces can read the API docs but can't create keys.
- Create a key in Developer › Integrations › Taalk API Token (free add-on). See API Keys.
- Browse and try every endpoint in Developer › API docs.
Base URL and authentication
| Base URL | https://api.taalk.ai/api |
| Auth header | Authorization: Bearer <TAALK_API_KEY> |
| Body format | JSON, up to 5 MB per request |
curl https://api.taalk.ai/api/campaign2s \
-H "Authorization: Bearer $TAALK_API_KEY"
More than one workspace
If you belong to several workspaces, add db=<workspace ID> to the query string. Without it, the request goes to your default workspace. The workspace ID is the db= value in your console address bar after you switch workspace.
curl "https://api.taalk.ai/api/campaign2s?db=<WORKSPACE_ID>" \
-H "Authorization: Bearer $TAALK_API_KEY"
Try requests in API docs
Go to Developer › API docs.
- Pick an endpoint from the list.
- Click Test request. The docs sign you in with a short-lived token for your current workspace, so you don't paste a key.
- Fill the parameters and send.
| Good to know | |
|---|---|
| Real actions | The Live server places real calls and texts. Taalk asks you to confirm before a DELETE and before any request that calls or texts someone. |
| Docs limits | About 120 requests and 20 writes per 10 minutes per user. |
force |
Not allowed from the docs (403). |
Limits
| Limit | Value |
|---|---|
| Keys per user | 15 |
| Rate limit | Set per key with Rate limit when you create it (Unlimited by default). Over the limit returns 429. |
| Page size | pageSize defaults to 10. Contact lists allow up to 200 per page. |
| DNC bulk check | 100 numbers per request |
| Long reports | /report and /campaign2s/{id}/contacts/report return 413 with Retry-After: 60 if they take too long. Retry after a minute. |
Errors
Errors come back as a plain-text message with the HTTP status.
| Status | Meaning | What to do |
|---|---|---|
| 400 | Bad request. Missing field, invalid date range, missing agent or caller ID, missing complianceAttested |
Read the message and fix the request |
| 401 | Invalid, expired or revoked key, a scoped key used outside its scope, no access to that workspace, or your role can't change this item | Check the key, its scopes, db and your role |
| 402 | Feature not on your plan, or add-on locked | Upgrade or unlock the add-on |
| 403 | Your plan doesn't allow API calls or DNC checks, or an action reserved for Taalk | Upgrade, or contact support |
| 404 | Not found, or the campaign isn't running (pause, resume, cancel) | Check the ID |
| 406 | Restore not possible (the campaign has a current run, or its last run wasn't canceled) | Check campaign state |
| 409 | Campaign already running, or caller ID used by another campaign | Pause the other campaign or pick another caller ID |
| 413 | Report still computing | Retry after Retry-After seconds |
| 424 | Caller ID group has no numbers | Add numbers to the group |
| 428 | Auto-recharge is off | Turn on auto-recharge before launching |
| 429 | Rate limit, or too many campaigns running at once | Slow down, or pause another campaign |
Endpoint map
All updates use POST (not PATCH). The only PATCH endpoint is the DNC list change.
Calls
| Method | Endpoint | What it does |
|---|---|---|
| POST | /call |
Call one contact now. Body: name, phone (E.164), optional from, agent, campaign, retryMethod, params, timeout. 200 queued, 202 campaign is after hours, 406 blocked by calling-hour rules |
| GET | /call/{localId} |
Call status and summary for third-party tools |
| GET | /calls |
List calls. Filters: range, tz, agent, campaign, phone, direction, answered, amd, transfer |
| GET | /calls/count |
Count calls matching the same filters |
| GET | /calls/status |
Live counts: payload.realtime (waiting, pending, in-progress) and payload.messaging (open threads, texts, emails). Optional campaign |
| GET | /calls/export/csv |
Download calls as CSV |
| GET | /calls/{id} |
One call: status, summary, details |
| GET | /calls/{id}/transcript |
Full transcript |
| GET | /calls/{id}/recording |
Recording (425 while it's still processing) |
| GET | /calls/{id}/recording/all |
All recording URLs for a call |
| DELETE | /calls/{id}/recording |
Delete a recording. Can't be undone |
| GET | /calls/{id}/explain |
AI explanation of the call |
| POST | /calls/{id}/report |
Report a problem with a call |
| POST | /calls/{id}/action/sms |
Text the contact on this call |
| POST | /calls/{id}/action/hangup |
Hang up a live call |
Campaigns and contacts
See API Guide: Campaigns and API Guide: Contacts.
| Method | Endpoint | What it does |
|---|---|---|
| GET, POST | /campaign2s |
List or create campaigns |
| GET, POST, DELETE | /campaign2s/{id} |
Read, update or delete a campaign |
| POST | /campaign2s/{id}/{action} |
start, pause, resume, cancel, restore |
| POST | /campaign2s/segments |
Count campaigns per filter |
| GET | /campaign2s/{id}/activities |
Recent changes to the campaign |
| GET, POST | /campaign2s/{id}/contacts |
List, or add / update / remove contacts |
| GET, POST | /campaign2s/{id}/contacts/{cid} |
Read or update one contact |
| GET | /campaign2s/{id}/contacts/{cid}/sessions |
Calls and messages for one contact |
| GET | /campaign2s/{id}/contacts/report |
Contact analytics (needs tz) |
| GET | /campaign2s/{id}/contacts/fields |
Custom Taalk_ fields in use |
| GET | /campaign2s/{id}/contacts/export/csv and /jsonl |
Export a campaign's contacts |
| GET | /contacts |
Search contacts across campaigns |
| GET | /contacts/export/csv and /jsonl |
Export contacts across campaigns |
| POST | /contact_form/{campaignId} |
Send a lead from a web form into a campaign |
Agents, knowledge and plugins
| Method | Endpoint | What it does |
|---|---|---|
| GET, POST | /agents |
List or create agents |
| GET, POST, DELETE | /agents/{id} |
Read, update or delete an agent |
| POST | /agents/{id}/lock |
Lock or unlock (readonly) |
| POST | /agents/{id}/test |
Place a test call |
| POST | /agents/wizard |
Draft an agent with AI |
| GET, POST | /knowledges |
List or create knowledge |
| GET, POST, DELETE | /knowledges/{id} |
Read, update or delete knowledge |
| GET, POST | /plugins |
List or create plugins |
| GET, POST, DELETE | /plugins/{id} |
Read, update or delete a plugin |
| GET | /plugins/{id}/agents |
Agents that use a plugin |
Compliance
See API Guide: DNC and Calling-Hour Checks.
| Method | Endpoint | What it does |
|---|---|---|
| GET | /dnc/{phone}, /dnc/{type}/{phone} |
Check one number |
| POST | /dnc |
Check up to 100 numbers |
| PATCH | /dnc/{type} |
Add or remove numbers on your list |
| POST | /check_ftc_rule |
Calling hours and holiday for a state or area code |
Reports and other
| Method | Endpoint | What it does |
|---|---|---|
| GET | /report |
Dashboard analytics. range, tz, granularity, agent, campaign, timeline, postcall |
| POST | /monitor/engagement |
Engagement report by hour, day or week (endsAt, granularity, campaign, tz, comparison) |
| GET | /monitor/engagement/{companyId} |
Saved engagement reports |
| GET | /count/{type} |
Count agents, knowledges, plugins and more |
| GET | /chatbot_entry |
Key and URL to embed the chatbot |
The API docs list the engagement report as
/api/monitor/engagement. The correct path is/monitor/engagement(full URLhttps://api.taalk.ai/api/monitor/engagement).
Prefer webhooks to polling
To get results as they happen, send them to your system instead of polling:
- Post-call results from an agent: Event Webhooks.
- Campaign alerts such as new contacts and fuse trips: Notification Webhooks.
Costs
Calls, texts and emails you start through the API cost the same as in the console. See How Billing Works.