> ## 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. # Purchase Phone Number > Buy a number from the inventory. ## OpenAPI ````yaml post /v1/agent/phone-numbers 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-numbers: post: tags: - Phone Numbers summary: Purchase or Import Phone Number description: >- `provider` discriminates two variants. `twilio` buys a number from the managed inventory: it lands in your default workspace, any `agent_id` you bind must live there too, and billing is the monthly price charged in daily slices; the first day is charged before anything is bought (402 costs you nothing) and the daily run advances it from there. `sip` imports a number you already own at your carrier: point your trunk's origination at our SIP host, provide inbound authentication (digest and/or source CIDRs) and optionally a termination host so the number can place calls; nothing is rented and there is no monthly fee. Either way, 409 means the number is already on the platform; 502 means the provider or trunk provisioning refused, and the number stays visible with status `error` and is safe to release. requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/PublicPhoneNumberPurchasePayload' - $ref: '#/components/schemas/PublicSipNumberImportPayload' responses: '201': description: Document created, URL follows headers: {} content: application/json: schema: properties: phone_number_id: title: Phone Number Id type: string workspace_id: title: Workspace Id type: string phone_number: description: E.164, e.g. +14155550123. title: Phone Number type: string provider: enum: - livekit - twilio - sip title: Provider type: string label: default: '' title: Label type: string agent_id: anyOf: - type: string - type: 'null' description: >- Inbound calls route to this agent; unbound numbers ring busy. title: Agent Id status: enum: - provisioning - active - error - released title: Status type: string status_detail: default: '' description: What failed when status is `error`; empty otherwise. title: Status Detail type: string supports_outbound: default: false description: >- Whether the number can place calls (outbound and warm-transfer consult legs): managed `twilio` always, imported `sip` only when a termination was configured. title: Supports Outbound type: boolean termination_uri: anyOf: - type: string - type: 'null' default: null description: >- Imported `sip` numbers: the customer trunk's termination host. title: Termination Uri inbound_auth_username: anyOf: - type: string - type: 'null' default: null description: >- Imported `sip` numbers: the inbound digest username. Passwords are never echoed. title: Inbound Auth Username inbound_allowed_addresses: description: 'Imported `sip` numbers: allowed source IPs/CIDRs.' items: type: string title: Inbound Allowed Addresses type: array termination_transport: anyOf: - type: string - type: 'null' default: null description: 'Imported `sip` numbers: termination transport.' title: Termination Transport termination_auth_username: anyOf: - type: string - type: 'null' default: null description: >- Imported `sip` numbers: the termination digest username. Passwords are never echoed. title: Termination Auth Username created_at: format: date-time title: Created At type: string updated_at: format: date-time title: Updated At type: string required: - phone_number_id - workspace_id - phone_number - provider - agent_id - status - created_at - updated_at 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 '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: [] components: schemas: PublicPhoneNumberPurchasePayload: additionalProperties: false properties: provider: const: twilio description: >- `twilio` buys from the managed inventory (supports call transfer); `sip` imports a number you already own at your carrier; see the `sip` request variant. title: Provider type: string phone_number: description: >- E.164 number from `GET /v1/agent/available-phone-numbers`, e.g. +14155550123. title: Phone Number type: string label: default: '' maxLength: 120 title: Label type: string agent_id: anyOf: - type: string - type: 'null' default: null description: Bind an agent to answer inbound calls right away. title: Agent Id required: - provider - phone_number title: PublicPhoneNumberPurchasePayload type: object PublicSipNumberImportPayload: additionalProperties: false description: >- The `sip` variant of POST /v1/agent/phone-numbers: import a number that stays at your carrier. Point your trunk's origination at our SIP host, give inbound at least one authentication factor (digest and/or source CIDRs), and optionally a termination host + credentials so the number can place calls. Nothing is rented: carrier charges stay on your account, and imported numbers carry no telephony charges at all: no monthly fee, no phone surcharge, no transfer fees; you pay agent minutes only. properties: inbound_auth_username: default: '' maxLength: 128 title: Inbound Auth Username type: string inbound_auth_password: default: '' maxLength: 128 title: Inbound Auth Password type: string inbound_allowed_addresses: items: type: string maxItems: 32 title: Inbound Allowed Addresses type: array termination_uri: default: '' title: Termination Uri type: string termination_transport: default: auto enum: - auto - udp - tcp - tls title: Termination Transport type: string termination_auth_username: default: '' maxLength: 128 title: Termination Auth Username type: string termination_auth_password: default: '' maxLength: 128 title: Termination Auth Password type: string phone_number: title: Phone Number type: string label: default: '' maxLength: 120 title: Label type: string agent_id: anyOf: - type: string - type: 'null' default: null title: Agent Id provider: const: sip title: Provider type: string required: - phone_number - provider title: PublicSipNumberImportPayload type: object securitySchemes: BearerAuth: type: http scheme: bearer ````