Initiate a call | Talkif Docs

POST /api/v1/calls

SECURITY: Verifies account access, phone ownership, provider ownership, flow ownership

Returns:

201 Created: Call initiated immediately (capacity available)
202 Accepted: Call queued for later processing (at capacity/rate limited)

POST /api/v1/calls SECURITY: Verifies account access, phone ownership, provider ownership, flow ownership Returns: - 201 Created: Call initiated immediately (capacity available) - 202 Accepted: Call queued for later processing (at capacity/rate limited)

Authentication

AuthorizationBearer

Pass a JWT access token or an API key (prefixed with tif_live_) as a Bearer token.

Request

This endpoint expects an object.

flowIdstringRequiredformat: "uuid"

Flow ID to use for the AI conversation

fromNumberstringRequired

Caller phone number in E.164 format, must be owned by the account

providerIdstringRequiredformat: "uuid"

Provider ID to route the call through

toNumberstringRequired

Destination phone number in E.164 format (emergency numbers blocked)

campaignContactIdstring or nullOptionalformat: "uuid"

Campaign contact ID for per-contact status tracking

campaignIdstring or nullOptionalformat: "uuid"

Campaign ID if this call is part of a bulk campaign

contactIdstring or nullOptionalformat: "uuid"

Contact ID to associate with this call

flowVersionstring or nullOptional

Flow version to use, defaults to current published version

metadataobject or nullOptional

Additional metadata to attach to the call

sourceenum or nullOptional

Call source - where the call originated from

Response

Call initiated or queued

object

Call initiated immediately (201 Created)

object

Call queued for later processing (202 Accepted)

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error