> ## Documentation Index > Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt > Use this file to discover all available pages before exploring further. # Purchase Phone Number > Buy a phone number through OneInbox and wire it to an agent in one step. OneInbox provisions the number on its own carrier account — the caller brings no external provider account or credentials. Pass a specific `phone_number` from GET /phone-numbers/search, or just filters to auto-pick one. ## OpenAPI ````yaml /openapi/openapi.yaml post /v1/phone-numbers/purchase openapi: 3.1.0 info: title: OneInbox API version: 1.0.0 servers: - url: https://api.oneinbox.ai description: Production server security: [] tags: - name: health - name: integrations - name: llm-models - name: tools - name: knowledge-bases - name: voices - name: webhooks - name: agents - name: phone-numbers - name: calls - name: workspace - name: usage - name: audit-events paths: /v1/phone-numbers/purchase: post: tags: - phone-numbers summary: Purchase Phone Number description: >- Buy a phone number through OneInbox and wire it to an agent in one step. OneInbox provisions the number on its own carrier account — the caller brings no external provider account or credentials. Pass a specific `phone_number` from GET /phone-numbers/search, or just filters to auto-pick one. operationId: purchase_phone_number_v1_phone_numbers_purchase_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PhoneNumberPurchase' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - API Key: [] components: schemas: PhoneNumberPurchase: properties: phone_number: anyOf: - type: string pattern: ^\+[1-9]\d{1,14}$ - type: 'null' title: Phone Number description: A specific number from /phone-numbers/search. Omit to auto-pick. country: type: string maxLength: 2 minLength: 2 title: Country default: US area_code: anyOf: - type: string - type: 'null' title: Area Code description: Area code (US/CA only) contains: anyOf: - type: string - type: 'null' title: Contains description: Digits/letters to match friendly_name: anyOf: - type: string - type: 'null' title: Friendly Name agent_id: type: string format: uuid title: Agent Id inbound_routing: anyOf: - $ref: '#/components/schemas/InboundRouting-Input' - type: 'null' type: object required: - agent_id title: PhoneNumberPurchase description: >- Buy a number through OneInbox. The carrier (Twilio today) is an internal implementation detail — the caller never supplies provider creds or trunk config; the number is bought on OneInbox's own account and wired automatically. Either pass a specific `phone_number` from GET /phone-numbers/search, or leave it out and give search filters (country / area_code / contains) to auto-pick the first available match. PhoneNumberResponse: properties: id: type: string title: Id phone_number: type: string title: Phone Number friendly_name: anyOf: - type: string - type: 'null' title: Friendly Name provider: type: string title: Provider agent_id: type: string title: Agent Id status: type: string title: Status inbound_trunk_id: anyOf: - type: string - type: 'null' title: Inbound Trunk Id outbound_trunk_id: anyOf: - type: string - type: 'null' title: Outbound Trunk Id dispatch_rule_id: anyOf: - type: string - type: 'null' title: Dispatch Rule Id inbound_routing: anyOf: - $ref: '#/components/schemas/InboundRouting-Output' - type: 'null' sms_capable: anyOf: - type: boolean - type: 'null' title: Sms Capable created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - phone_number - friendly_name - provider - agent_id - status - inbound_trunk_id - outbound_trunk_id - dispatch_rule_id - created_at - updated_at title: PhoneNumberResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError InboundRouting-Input: properties: agent_id: type: string format: uuid title: Agent Id fallback: anyOf: - $ref: '#/components/schemas/InboundRoutingFallback-Input' - type: 'null' voicemail_message: anyOf: - type: string - type: 'null' title: Voicemail Message type: object required: - agent_id title: InboundRouting description: |- Per-number routing override. Stored as JSONB so we can extend with business-hours and caller-id rules later without a schema change. InboundRouting-Output: properties: agent_id: type: string title: Agent Id fallback: anyOf: - $ref: '#/components/schemas/InboundRoutingFallback-Output' - type: 'null' voicemail_message: anyOf: - type: string - type: 'null' title: Voicemail Message type: object required: - agent_id title: InboundRouting description: |- Per-number routing override. Stored as JSONB so we can extend with business-hours and caller-id rules later without a schema change. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError InboundRoutingFallback-Input: properties: agent_id: anyOf: - type: string format: uuid - type: 'null' title: Agent Id type: object title: InboundRoutingFallback description: |- Backup agent dispatched when the primary inbound_routing.agent_id is unreachable (deleted, paused, or returns a worker error). Optional — if omitted the worker just rejects the call. InboundRoutingFallback-Output: properties: agent_id: type: string title: Agent Id type: object title: InboundRoutingFallback description: |- Backup agent dispatched when the primary inbound_routing.agent_id is unreachable (deleted, paused, or returns a worker error). Optional — if omitted the worker just rejects the call. securitySchemes: API Key: type: http description: >- Your **API key** sent as a Bearer credential — `Authorization: Bearer `, where `` starts with `oi_sk_` (create one via `POST /v1/api-keys`). Although the field is labelled 'token', paste your API key here. A dashboard JWT is also accepted on this header for the same endpoints. scheme: bearer ````