FIfish
Phone Calls

Create Phone Call

Changed on

Place an outbound call from one of your phone numbers. Platform numbers dial US, Canada or Japan destinations, and a domestic trunk 0 after +81 (e.g. +81080...) is accepted and normalized to E.164 (+8180...). Imported SIP numbers dial through their own termination and may attach custom INVITE headers with sip_headers. Returns immediately with the session queued for dialing. Subscribe to the phone_call.dial_finished webhook or poll GET /v1/agent/sessions/{session_id} for the dial outcome and the leg's sip_call_id. Ringing is never billed: metering starts when the callee answers.

Errors carry a machine-readable reason (e.g. destination_not_allowed, insufficient_credit, concurrency_limit_exceeded).

post/v1/agent/phone-calls

Request

  • Base URL
    https://api.fish.audio
  • URL
    https://api.fish.audio/v1/agent/phone-calls
  • Auth
    HTTP bearer

Headers

idempotency-keystring nullable

Retry-safe replay key: the same key with the same body returns the call already placed instead of dialing again (24h window).

Request body

agent_idstring required
phone_number_idstring required

The team-owned number to dial from (twilio provider only).

to_numberstring required

Destination in E.164, e.g. +14155550123.

dynamic_variablesobject nullable
metadataobject nullable
llm_extra_bodyobject nullable
sip_headersobject nullable

Custom SIP headers for this call's INVITE, imported SIP numbers only. Same rules as the number's termination_headers, and merged over them.

Response

Document created, URL follows

session_idstring required
status'queued'

Changes