Outbound Calls

Originate a call

Places an outbound call. Returns 202 once CallNode accepts the originate command. The call lifecycle is then visible via GET on the same callId, or via the optional status webhook.

The destination takes one of three mutually exclusive forms:

  1. PSTN — to is E.164; the call is completed over the phone network.
  2. Direct SIP URI — to is sip:user@host[:port][;transport=udp|tcp]; the call is delivered straight to your SIP endpoint.
  3. Saved trunk (BYOC) — sipTrunkId selects a trunk created in the dashboard, and to is an E.164 number (terminated by your carrier) or an extension your host understands.

In every form from must be a CallNode number you own — it becomes the caller ID presented to the called party or your SIP endpoint. SIP destinations bill at your plan's SIP egress rate and must accept traffic from 198.27.122.194 or 192.95.44.47 (audio G.711 PCMU/PCMA at 8 kHz, DTMF RFC 2833).

post/api/v1/outbound/calls

Request

  • Base URL: https://api.callnode.io
  • URL: https://api.callnode.io/api/v1/outbound/calls
  • Auth: API key in header X-Api-Key and API key in header X-Timestamp and API key in header X-Signature

Headers

X-Idempotency-Keystring uuid

A UUID. Replaying the same key returns the original result rather than acting twice.

Request body

sipTrunkIdstring

ID of a saved SIP trunk (Dashboard → SIP Trunks). Routes the call to the trunk's configured host (BYOC / PBX). Mutually exclusive with a sip: to.

fromstring required

Plus sign followed by 7–15 digits.

webhookUrlstring uri

Where your AI agent runs. Overrides the webhook stored on the from number. Invoked once when the call connects (call_started), then once per turn — for every caller utterance (user_speech) and every completed keypad entry (user_dtmf, with the digit string in a dtmf field) — see the Conversational Webhook guide.

metadataobject

Opaque JSON, echoed back on status webhooks. Max 4 KB.

statusWebhookUrlstring uri

URL we POST call lifecycle events to (answered, completed, failed). For SIP destinations, call.failed events carry the mapped failureCode and may also include sipCause — the raw hangup cause string (diagnostic passthrough; not enumerated).

maxDurationSecsinteger

Hard cap on call duration.

tcpaOverrideboolean

Bypass the 8am–9pm called-party-local-time check. Audited.

Example request

{
  "to": "+16135551234",
  "from": "+16135551234"
}

Response

Originate command accepted.

callIdstring
status'originating' | 'ringing' | 'answered' | 'completed' | 'failed' | 'canceled'
createdAtstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.