> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a phone number

> Register a number into the workspace inventory: `managed` (platform-provisioned Vobiz DID, enters `provisioning`), `hosted` (customer-owned number hosted on the platform trunk after an LOA, enters `pending_verification`), or `byo_trunk` (number on an existing active SIP trunk, enters `active`). Requires the admin-tier `phone_numbers:write` scope (customer/platform admins, or an API key bearing the scope). Scope `phone_numbers:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /phone-numbers
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /phone-numbers:
    post:
      tags:
        - Phone Numbers
      summary: Register a phone number
      description: >-
        Register a number into the workspace inventory: `managed`
        (platform-provisioned Vobiz DID, enters `provisioning`), `hosted`
        (customer-owned number hosted on the platform trunk after an LOA, enters
        `pending_verification`), or `byo_trunk` (number on an existing active
        SIP trunk, enters `active`). Requires the admin-tier
        `phone_numbers:write` scope (customer/platform admins, or an API key
        bearing the scope). Scope `phone_numbers:write`.
      operationId: create_phone_number_ca_api_v0_phone_numbers_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - number
                - source
              properties:
                number:
                  type: string
                  description: >-
                    E.164 number (e.g. +919876543210); whitespace and separators
                    are stripped.
                source:
                  type: string
                  enum:
                    - managed
                    - byo_trunk
                    - hosted
                  description: Registration source.
                display_name:
                  type: string
                  nullable: true
                  description: Human label for the number.
                sip_trunk_id:
                  type: string
                  description: >-
                    Required when source is `byo_trunk`; must reference an
                    active SIP trunk in this workspace.
                provider:
                  type: string
                  description: >-
                    Carrier/provider label. Defaults to `vobiz` for
                    managed/hosted, or the trunk's provider for byo_trunk.
                outbound_enabled:
                  type: boolean
                  default: true
                  description: Whether the number may be used as an outbound caller ID.
                inbound_enabled:
                  type: boolean
                  default: false
                  description: Whether the number answers inbound calls.
                metadata:
                  type: object
                  description: >-
                    Free-form metadata. For `hosted`, must include
                    `loa_acknowledged: true` to authorize the platform to
                    present the number as caller ID.
              example:
                number: '+919876543210'
                source: byo_trunk
                sip_trunk_id: trunk_x1y2z3
                display_name: Sales line
                outbound_enabled: true
                inbound_enabled: false
      responses:
        '201':
          description: Number registered.
          content:
            application/json:
              example:
                id: pn_a1b2c3d4
                number: '+919876543210'
                display_name: Sales line
                source: byo_trunk
                sip_trunk_id: trunk_x1y2z3
                sip_trunk_name: Acme SIP
                status: active
                outbound_enabled: true
                inbound_enabled: false
                inbound_agent_id: null
                provider: acme-telecom
                metadata: {}
                created_at: '2026-09-01T12:00:00Z'
                updated_at: '2026-09-01T12:00:00Z'
        '400':
          description: >-
            Invalid body: non-E.164 number, unknown source, non-object metadata,
            missing sip_trunk_id for byo_trunk, referenced SIP trunk not active,
            missing LOA acknowledgement for hosted, or missing customer context.
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: number must be E.164 (e.g. +919876543210)
        '401':
          description: Authentication required.
          content:
            application/json:
              example:
                error:
                  code: unauthorized
                  message: Authentication required
        '403':
          description: Missing scope, or a role that cannot manage phone numbers.
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: This role cannot manage phone numbers
        '404':
          description: >-
            Customer not found, or (for byo_trunk) the referenced SIP trunk was
            not found.
          content:
            application/json:
              example:
                error:
                  code: not_found
                  message: SIP trunk not found
        '409':
          description: The number is already registered to a live row.
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: This number is already registered
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````