Obtain an OAuth 2.0 access token via POST to https://api.talkdeskapp.com/oauth/token using client credentials scoped to contacts and flows
POST to /contacts with fields (name, phone_numbers, email, external_id) to create or upsert a contact record; use the external_id field to link to your CRM system
GET /contacts?phone_number={E164_number} to look up a contact by phone number before initiating a callback to avoid creating duplicates
POST to /calls/outbound with the contact phone number, agent or queue target, and an optional flow_id to route the call through a specific Studio flow
To trigger a self-service IVR specifically, POST to the Flows API callback endpoint with the customer phone number and the Studio flow ID to initiate an outbound automated call without an agent
GET /calls/{callId} after the call ends to retrieve disposition, duration, and the flow path taken for analytics ingestion
Known gotchas
The Switch Contact component (rolled out May 2026) resolves contact identities during live calls — if your contact records have mismatched external_id values between Talkdesk and your CRM, the switch will fail to resolve the identity and fall back to the original contact
Talkdesk routes accounts to regional API endpoints; verify whether your account uses the US, EU, or other regional host — using the wrong region returns 401 or 404 errors that look like credential failures
Outbound IVR flows initiated via API do not consume agent capacity but do consume outbound telephony credits; ensure the account has sufficient credits before large batch outbound campaigns
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp