> ## 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. # Register Phone Number ## OpenAPI ````yaml /openapi/openapi.yaml post /v1/phone-numbers 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: post: tags: - phone-numbers summary: Register Phone Number operationId: register_phone_number_v1_phone_numbers_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PhoneNumberCreate' 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: PhoneNumberCreate: properties: phone_number: type: string pattern: ^\+[1-9]\d{1,14}$ title: Phone Number friendly_name: anyOf: - type: string - type: 'null' title: Friendly Name provider: type: string enum: - twilio - telnyx title: Provider agent_id: type: string format: uuid title: Agent Id provider_config: $ref: '#/components/schemas/SipProviderConfig' inbound_routing: anyOf: - $ref: '#/components/schemas/InboundRouting-Input' - type: 'null' credential_id: anyOf: - type: string format: uuid - type: 'null' title: Credential Id type: object required: - phone_number - provider - agent_id title: PhoneNumberCreate 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 SipProviderConfig: properties: trunk_address: anyOf: - type: string maxLength: 255 - type: 'null' title: Trunk Address description: SIP server FQDN, e.g. 'sip.telnyx.com'. auth_username: anyOf: - type: string maxLength: 255 - type: 'null' title: Auth Username auth_password: anyOf: - type: string maxLength: 255 - type: 'null' title: Auth Password additionalProperties: true type: object title: SipProviderConfig description: |- SIP digest credentials for outbound trunk auth. Same three fields for Twilio and Telnyx — they both speak SIP and need a username/password pair plus the trunk address. The values differ per provider: twilio: trunk_address: '.pstn.twilio.com' auth_username: Twilio Elastic SIP Trunk credential username auth_password: matching password (never logged, stripped from DB) telnyx: trunk_address: 'sip.telnyx.com' (or your region-specific edge) auth_username: Telnyx SIP connection auth username auth_password: matching password All fields are OPTIONAL at the schema layer because the service falls back to env vars (`{PROVIDER}_TRUNK_ADDRESS`, `{PROVIDER}_SIP_USERNAME`, `{PROVIDER}_SIP_PASSWORD`) when omitted. The service raises 400 SIP_TRUNK_PROVISION_FAILED if neither path provides all three. `extra="allow"` preserves forward-compat — future provider-specific knobs (e.g. Twilio's `messaging_service_sid`) can be added by callers without us bumping the API. 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 ````