> ## Documentation Index > Fetch the complete documentation index at: https://docs.fish.audio/llms.txt > Use this file to discover all available pages before exploring further. # Create Phone Call > Place an outbound call from one of your phone numbers; the agent speaks when the callee answers. ## OpenAPI ````yaml post /v1/agent/phone-calls openapi: 3.1.0 info: title: FishAudio OpenAPI version: '1' servers: - description: Fish Audio API url: https://api.fish.audio security: [] tags: [] paths: /v1/agent/phone-calls: post: tags: - Phone Calls summary: Create Phone Call description: >- Place an outbound call from one of your Twilio phone numbers to a US, Canada or Japan destination. A domestic trunk 0 after +81 (e.g. +81080...) is accepted and normalized to E.164 (+8180...). 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. Ringing is never billed — metering starts when the callee answers. Errors carry a machine-readable `reason` (e.g. `destination_not_allowed`, `insufficient_credit`, `daily_limit_exceeded`, `concurrency_limit_exceeded`). parameters: - in: header name: idempotency-key description: >- Retry-safe replay key: the same key with the same body returns the call already placed instead of dialing again (24h window). required: false schema: anyOf: - type: string - type: 'null' default: null title: Idempotency-Key deprecated: false requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PhoneCallCreatePayload' responses: '201': description: Document created, URL follows headers: {} content: application/json: schema: properties: session_id: title: Session Id type: string status: const: queued default: queued title: Status type: string required: - session_id type: object '401': description: No permission -- see authorization schemes headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '402': description: No payment -- see charging schemes headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '403': description: Request forbidden -- authorization will not help headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '404': description: Nothing matches the given URI headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '409': description: Request conflict headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '422': description: '' headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '429': description: >- The user has sent too many requests in a given amount of time ("rate limiting") headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '502': description: Invalid responses from another server/proxy headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object '503': description: The server cannot process the request due to a high load headers: {} content: application/json: schema: properties: status: title: Status type: integer message: title: Message type: string reason: anyOf: - type: string - type: 'null' default: null title: Reason required: - status - message type: object security: - BearerAuth: [] x-codeSamples: - lang: bash label: Create Phone Call source: |- curl --request POST \ --url https://api.fish.audio/v1/agent/phone-calls \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: ' \ --data '{ "agent_id": "", "phone_number_id": "", "to_number": "+14155550123" }' components: schemas: PhoneCallCreatePayload: additionalProperties: false description: |- POST phone-calls body, shared by the public and console routes. to_number is deliberately not format-validated here: the contract orders the E.164 check after the agent/published checks, so it runs in the service with a machine-readable reason. properties: agent_id: title: Agent Id type: string phone_number_id: description: The team-owned number to dial from (twilio provider only). title: Phone Number Id type: string to_number: description: Destination in E.164, e.g. +14155550123. title: To Number type: string dynamic_variables: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean maxProperties: 50 type: object - type: 'null' default: null title: Dynamic Variables overrides: anyOf: - $ref: '#/components/schemas/AgentSessionOverridesPayload' - type: 'null' default: null metadata: anyOf: - additionalProperties: $ref: '#/components/schemas/JsonValue' type: object - type: 'null' default: null title: Metadata required: - agent_id - phone_number_id - to_number title: PhoneCallCreatePayload type: object AgentSessionOverridesPayload: additionalProperties: false description: >- Wire twin of @fishaudio/agent-protocol `SessionOverrides` (session.ts). Every field must be allow-listed in Agent.overrides_allowed; unauthorized fields fail session creation loudly rather than being silently dropped. properties: first_message: anyOf: - maxLength: 10000 type: string - type: 'null' default: null title: First Message first_message_prompt: anyOf: - maxLength: 10000 type: string - type: 'null' default: null title: First Message Prompt system_prompt: anyOf: - maxLength: 100000 type: string - type: 'null' default: null description: >- Limited to 4000 tokens (o200k_base), same budget as the configured prompt it replaces. title: System Prompt voice_id: anyOf: - maxLength: 256 type: string - type: 'null' default: null title: Voice Id language: anyOf: - enum: - en - ja - zh - ko - es - fr - de type: string - type: 'null' default: null title: Language title: AgentSessionOverridesPayload type: object JsonValue: {} securitySchemes: BearerAuth: type: http scheme: bearer ````