> ## Documentation Index > Fetch the complete documentation index at: https://docs.voice.wixzel.com/llms.txt > Use this file to discover all available pages before exploring further. # Buy a number > Buys the number on the customer's own carrier account, points it at the trunk, and registers it, with `inbound_agent_id` answering it. **The carrier charges that account** at its own price; Wixzel Voice sells no numbers and adds nothing. Confirm the number and the price with the person before calling this. Where the number needs regulatory approval, an approved bundle, compliance application or requirement group already on the carrier account is attached automatically. Without one the carrier refuses, and the error says where to get it. Requires `phone_numbers:purchase`, which AI clients do not get unless the person ticks it, and an `Idempotency-Key` header: retrying with the same key returns the first result instead of buying twice. A number that was bought but could not be pointed at us answers `502 bought_not_connected`; it stays on the carrier account and can be registered again. ## OpenAPI ````yaml /openapi.json post /v1/phone-numbers/purchase openapi: 3.1.0 info: title: Wixzel Voice API version: '2026-09-01' description: >- APIs for agentic telephony. One API key, one balance, every voice engine. ## Authentication Send your key as `Authorization: Bearer wv_live_...`. Keys are scoped: grant only what an integration needs. There is no admin scope. ## Versioning The `/v1` prefix covers additive changes. Behavioural changes ship behind a dated `Wixzel-Version` header, and existing keys keep the behaviour they were created with. ## Money Amounts are integer **micro-USD** (1,000,000 = $1.00). Voice usage is billed per second, per token and per character, so a float dollar figure cannot represent it without disagreeing with the ledger. ## Errors Every error carries a stable `code` and a `request_id`. Match on `code`; the `message` is for humans and may change. contact: name: Wixzel Voice url: https://voice.wixzel.com servers: - url: https://api.voice.wixzel.com description: Production security: [] tags: - name: Calls description: Place calls and read what happened on them. - name: Realtime description: Talk to an agent from a browser or app, with no phone line. - name: Agents description: The prompt, voice and behaviour of a caller. - name: Leads description: People to call, and data to merge into prompts. - name: Campaigns description: Call a list of leads with one agent. - name: Knowledge bases description: Facts an agent can draw on mid-call. - name: Phone numbers description: Numbers on your SIP trunks. - name: SIP trunks description: Your carrier connections. - name: Appointments description: Bookings, including ones agents make on calls. - name: Usage description: Itemised billing lines. - name: Billing description: Balance, ledger and top-ups. - name: API keys description: Create, scope and rotate keys. - name: Engines description: What the platform can serve, and what it costs. - name: Voices description: Cloned voices, made from your own recordings, for your agents to speak in. - name: Webhooks description: Where events are sent, and what happened when they got there. - name: MCP servers description: Other apps’ tools, for agents to use while they are on a call. paths: /v1/phone-numbers/purchase: post: tags: - Phone numbers summary: Buy a number description: >- Buys the number on the customer's own carrier account, points it at the trunk, and registers it, with `inbound_agent_id` answering it. **The carrier charges that account** at its own price; Wixzel Voice sells no numbers and adds nothing. Confirm the number and the price with the person before calling this. Where the number needs regulatory approval, an approved bundle, compliance application or requirement group already on the carrier account is attached automatically. Without one the carrier refuses, and the error says where to get it. Requires `phone_numbers:purchase`, which AI clients do not get unless the person ticks it, and an `Idempotency-Key` header: retrying with the same key returns the first result instead of buying twice. A number that was bought but could not be pointed at us answers `502 bought_not_connected`; it stays on the carrier account and can be registered again. parameters: - schema: type: string minLength: 1 maxLength: 255 description: A unique value per purchase attempt, e.g. a UUID. required: true name: Idempotency-Key in: header requestBody: content: application/json: schema: $ref: '#/components/schemas/PurchasePhoneNumber' responses: '201': description: The number, bought and registered content: application/json: schema: $ref: '#/components/schemas/PurchasedPhoneNumber' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Key lacks the required scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such record content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Another purchase is running on this carrier account, the trunk was added by hand, or the account limit is reached content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Idempotency-Key reused with a different body content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Retry after the interval in `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- The carrier failed, or the number was bought and could not be connected content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: PurchasePhoneNumber: type: object properties: sip_trunk_id: type: string pattern: ^[0-9a-f]{24}$ description: >- A trunk made by connecting a carrier account. The number is bought on that account. example: 6a96a3ead6e886d42462dd3e phone_number: type: string pattern: ^\+[1-9]\d{6,14}$ example: '+14155550100' country: type: string pattern: ^[A-Z]{2}$ description: The country you searched in. example: IN type: allOf: - $ref: '#/components/schemas/NumberType' - description: >- The type you searched for. Used to find the approved regulatory documents it needs. name: type: string maxLength: 200 inbound_agent_id: type: string pattern: ^[0-9a-f]{24}$ description: >- Answers inbound calls to the number. It also becomes the agent’s caller id if the agent has none. example: 6a96a3ead6e886d42462dd3e required: - sip_trunk_id - phone_number - country - type PurchasedPhoneNumber: allOf: - $ref: '#/components/schemas/PhoneNumber' - type: object properties: purchase_status: type: string enum: - complete - pending description: >- `pending` when the carrier took the order and is still processing it, which can take a few minutes for numbers that need regulatory review. The number is registered either way. required: - purchase_status Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - insufficient_credits - not_found_error - conflict_error - api_error code: type: string description: Stable machine-readable code. example: agent_not_found message: type: string description: >- Human-readable explanation. Do not match on this — match on code. param: type: string description: Which field caused the failure, when applicable. doc_url: type: string request_id: type: string description: Quote this when asking for help. example: req_01HXYZ... required: - type - code - message - request_id required: - error NumberType: type: string enum: - local - mobile - toll_free PhoneNumber: type: object properties: id: type: string pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e object: type: string enum: - phone_number phone_number: type: string name: type: - string - 'null' sip_trunk_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e inbound_agent_id: type: - string - 'null' pattern: ^[0-9a-f]{24}$ example: 6a96a3ead6e886d42462dd3e status: type: string created_at: type: string format: date-time description: ISO 8601, always UTC. example: '2026-09-01T12:00:00.000Z' required: - id - object - phone_number - name - sip_trunk_id - inbound_agent_id - status - created_at securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Wixzel Voice API key: `Authorization: Bearer wv_live_...`. Keys are scoped; grant only what the integration needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.