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

# Number Provision (Purchase/Order)

> **Prerequisites:**
- **Required:** Bearer token — `POST /v1.0/oauth2/tokens`
- **Required:** Message Route ID (MRID) — `POST /v1.0/message/routes`
- **Optional:** Voice Route ID (CRID) — `POST /v1.0/voice/routes` *(only needed if `VoiceEnabled: true`)*
- **Optional:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create` *(to assign the number at provision time)*

---

Purchase and activate a phone number on your account. Before provisioning, ensure you have already created a Message Route (MRID) and Voice Route (CRID) — numbers provisioned without routes will have no call or message handling. Specify the number classification (`mvno` for full messaging and voice, `iot` for data and p2p messaging only), and required capabilities. Returns an OrderId for status tracking.

**What this does:** Purchases and activates the number, returning an `OrderId`, the assigned phone number in E.164 format, a `PhoneNumberId` (`NID-`), and an eSIM QR code (if applicable). The `OrderId` can be used to track provisioning status.

**Next steps:**
- Check order status — `GET /v1.0/numbers/order`
- Send a test message — `POST /v1.0/message/outbound`



## OpenAPI

````yaml /api-reference/openapi.json post /v1.0/numbers/provision
openapi: 3.0.3
info:
  title: mPaaS Core APIs
  version: 1.0.8
  description: >-
    The Telegent mPaaS (Mobile Platform as a Service) API gives you full
    programmatic control over mobile phone numbers, messaging, voice routing,
    subscribers, and account management. Use these APIs to provision MVNO and
    IoT numbers, send and receive SMS/MMS, configure intelligent call routing,
    manage subscriber accounts, and apply AI Guardian controls. All requests
    require a Bearer token obtained from the Authentication endpoint. For
    support, visit https://support.telegent.com/support/home
  contact:
    name: Support
    email: support@telegent.com
  termsOfService: https://telegent.com/terms
  license:
    name: Use under LICX
    url: https://telegent.com/license
servers:
  - url: https://api.telegent.com/v1.0
security:
  - BearerAuth: []
tags:
  - name: OAuth2
  - name: AI Guardian
  - name: Accounts
  - name: Distributors
  - name: Message
  - name: Numbers
  - name: Voicemail
  - name: Packages
  - name: Products
  - name: Schedules
  - name: Services
  - name: Sims
  - name: Subscribers
  - name: Subscriptions
  - name: Voice
  - name: Workgroups
paths:
  /v1.0/numbers/provision:
    post:
      tags:
        - Numbers
      summary: Number Provision (Purchase/Order)
      description: >-
        **Prerequisites:**

        - **Required:** Bearer token — `POST /v1.0/oauth2/tokens`

        - **Required:** Message Route ID (MRID) — `POST /v1.0/message/routes`

        - **Optional:** Voice Route ID (CRID) — `POST /v1.0/voice/routes` *(only
        needed if `VoiceEnabled: true`)*

        - **Optional:** Subscriber ID (TSUID) — `POST /v1.0/subscribers/create`
        *(to assign the number at provision time)*


        ---


        Purchase and activate a phone number on your account. Before
        provisioning, ensure you have already created a Message Route (MRID) and
        Voice Route (CRID) — numbers provisioned without routes will have no
        call or message handling. Specify the number classification (`mvno` for
        full messaging and voice, `iot` for data and p2p messaging only), and
        required capabilities. Returns an OrderId for status tracking.


        **What this does:** Purchases and activates the number, returning an
        `OrderId`, the assigned phone number in E.164 format, a `PhoneNumberId`
        (`NID-`), and an eSIM QR code (if applicable). The `OrderId` can be used
        to track provisioning status.


        **Next steps:**

        - Check order status — `GET /v1.0/numbers/order`

        - Send a test message — `POST /v1.0/message/outbound`
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - NumberType
                - MessageType
                - MessageEnabled
                - VoiceEnabled
                - ProductType
              properties:
                NumberType:
                  type: string
                  enum:
                    - mvno
                    - iot
                  description: >-
                    Number classification: 'mvno' (supports both a2p and p2p),
                    'iot' (p2p only - cannot be provisioned as a2p; use mvno
                    NumberType for a2p MessageType)
                  example: iot
                MessageType:
                  type: string
                  enum:
                    - a2p
                    - p2p
                  description: >-
                    Message type: a2p (Application-to-Person) or p2p
                    (Person-to-Person)
                  example: p2p
                MessageEnabled:
                  type: boolean
                  description: Enable SMS/MMS capabilities
                  example: true
                VoiceEnabled:
                  type: boolean
                  description: Enable voice call capabilities
                  example: false
                DataEnabled:
                  type: boolean
                  description: Enable data capabilities (for IoT numbers)
                  example: true
                MessageRouteId:
                  type: string
                  description: MRID for message routing configuration
                  example: MRID-81dr9t90-....-....-....-..........
                VoiceRouteId:
                  type: string
                  description: CRID for voice routing configuration
                  example: CRID-5nov0yuy-....-....-....-.........
                AreaCode:
                  type: string
                  description: >-
                    Preferred 3-digit area code. Lookup searches AreaCode first
                    before ZipCode. If both AreaCode and ZipCode are left blank
                    or null, a randomized set of results will be returned
                  example: '201'
                ZipCode:
                  type: string
                  description: >-
                    5-digit zip code. Used as fallback if AreaCode is
                    unavailable. You may provide both AreaCode and ZipCode, or
                    just one; AreaCode takes priority if included. Please note
                    that zip codes must be valid and within the United States.
                  example: '84043'
                ICCID:
                  type: string
                  description: >-
                    Integrated Circuit Card Identifier. Optional field, but
                    required when provisioning a physical SIM (pSIM)
                  example: '8901240397190195850'
                ProductType:
                  type: string
                  enum:
                    - Sms-Only
                    - Data-Only
                    - Sms+Data
                    - Sms+Data+Voice
                  description: >-
                    Product type for the provisioned number. Options: Sms-Only,
                    Data-Only, Sms+Data, Sms+Data+Voice
                  example: Sms+Data
                AssignedSubscriberId:
                  type: string
                  description: Optional subscriber-id to be assigned to the new number
                  example: TSUID-1234567999
                AccountId:
                  type: string
                  description: >-
                    Account ID (AID) to provision the number under. Required
                    when a distributor account has more than one sub-account.
                  example: AID-ab12345-2725-45a1-bd5e-526ed19799xx
      responses:
        '200':
          description: >-
            Success — returns the order ID, assigned phone number, and
            provisioning status
          content:
            application/json:
              schema:
                type: object
              examples:
                example:
                  value:
                    OrderDate: '2025-10-29T12:36:19.338438+00:00'
                    OrderId: JNUOID-76ba71a8-d7a6-4489-b695-1ad363b8d596
                    OrderStatus: Complete
                    PhoneNumberAssigned: '+18016025346'
                    PhoneNumberId: NID-8bdf915a-ef65-46c9-8c66-96c98d42d9ca
                    QRCode: >-
                      https://quickchart.io/qr?text=LPA:1$T-MOBILE.IDEMIA.IO$LX9G1-Q12VI-CIIWA-WAQIN&centerImageUrl=https://joonto.com/wp-content/uploads/2022/07/cropped-Joonto-2022-Square-Icon-Black-Background.png&ecLevel=H&format=png&centerImageSizeRatio=.3
                    ZipCode: '84603'
                    ICCID: '12345678900987654321'
                    ErrorMessage: null
                    SubscriberId: TSUID-ac59a1f8-36b6-42cc-b124-c2aa29f7e3d2
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest_Result'
              example:
                StatusCode: 400
                Message: >-
                  Bad request: one or more required fields are missing or
                  contain an invalid value.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized_Result'
              example:
                StatusCode: 401
                Message: >-
                  Unauthorized: Bearer token is missing, expired, or invalid.
                  Re-authenticate via POST /v1.0/oauth2/tokens.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden_Result'
              example:
                StatusCode: 403
                Message: >-
                  Forbidden: your token does not have permission to access this
                  resource. Check the ApiEndpoint scope.
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound_Result'
              example:
                StatusCode: 404
                Message: >-
                  Not found: the requested resource does not exist or belongs to
                  a different account.
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed_Result'
              example:
                StatusCode: 405
                Message: >-
                  Method not allowed: verify the HTTP method required for this
                  endpoint.
        '408':
          description: Request Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestTimeout_Result'
              example:
                StatusCode: 408
                Message: >-
                  Request timeout: the server did not receive a complete request
                  within the allowed time. Retry with exponential backoff.
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests_Result'
              example:
                StatusCode: 429
                Message: >-
                  Too many requests: rate limit exceeded. Slow your request
                  cadence and retry after a short delay.
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError_Result'
              example:
                StatusCode: 500
                Message: >-
                  Internal server error: an unexpected error occurred. If the
                  problem persists contact support@telegent.com.
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailable_Result'
              example:
                StatusCode: 503
                Message: >-
                  Service unavailable: the API is temporarily unavailable. Retry
                  after a short delay.
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeout_Result'
              example:
                StatusCode: 504
                Message: >-
                  Gateway timeout: an upstream service did not respond in time.
                  Retry with exponential backoff.
      x-codeSamples:
        - lang: JSON
          source: |-
            {
              "NumberType": "iot",
              "MessageType": "p2p",
              "MessageEnabled": true,
              "VoiceEnabled": false,
              "DataEnabled": true,
              "MessageRouteId": "MRID-73af1e73-d7b3-4696-bdd9-5b407c96fc8a",
              "VoiceRouteId": "CRID-4dec6beb-3985-444b-8c06-8baa70dc145",
              "AreaCode": "201",
              "ZipCode": "84043",
              "ICCID": "8901240397190195850",
              "ProductType": "Sms+Data",
              "AssignedSubscriberId": "TSUID-1234567999"
            }
        - lang: cURL
          source: |-
            curl -X POST https://api.telegent.com/v1.0/numbers/provision \
              -H 'Authorization: Bearer YOUR_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{
                "NumberType": "iot",
                "MessageType": "p2p",
                "MessageEnabled": true,
                "VoiceEnabled": false,
                "DataEnabled": true,
                "MessageRouteId": "MRID-73af1e73-d7b3-4696-bdd9-5b407c96fc8a",
                "VoiceRouteId": "CRID-4dec6beb-3985-444b-8c06-8baa70dc145",
                "AreaCode": "201",
                "ZipCode": "84043",
                "ICCID": "8901240397190195850",
                "ProductType": "Sms+Data",
                "AssignedSubscriberId": "TSUID-1234567999"
              }'
components:
  schemas:
    BadRequest_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 400
        Message:
          type: string
          nullable: true
          example: >-
            Bad request: one or more required fields are missing or contain an
            invalid value.
      additionalProperties: false
      example:
        StatusCode: 400
        Message: >-
          Bad request: one or more required fields are missing or contain an
          invalid value.
    Unauthorized_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 401
        Message:
          type: string
          nullable: true
          example: 'Unauthorized: Bearer token is missing, expired, or invalid.'
      additionalProperties: false
      example:
        StatusCode: 401
        Message: 'Unauthorized: Bearer token is missing, expired, or invalid.'
    Forbidden_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 403
        Message:
          type: string
          nullable: true
          example: >-
            Forbidden: your token does not have permission to access this
            resource.
      additionalProperties: false
      example:
        StatusCode: 403
        Message: >-
          Forbidden: your token does not have permission to access this
          resource.
    NotFound_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 404
        Message:
          type: string
          nullable: true
          example: >-
            Not found: the requested resource does not exist or belongs to a
            different account.
      additionalProperties: false
      example:
        StatusCode: 404
        Message: >-
          Not found: the requested resource does not exist or belongs to a
          different account.
    MethodNotAllowed_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 405
        Message:
          type: string
          nullable: true
          example: >-
            Method not allowed: verify the HTTP method required for this
            endpoint.
      additionalProperties: false
      example:
        StatusCode: 405
        Message: 'Method not allowed: verify the HTTP method required for this endpoint.'
    RequestTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 408
        Message:
          type: string
          nullable: true
          example: >-
            Request timeout: the server did not receive a complete request in
            time.
      additionalProperties: false
      example:
        StatusCode: 408
        Message: >-
          Request timeout: the server did not receive a complete request in
          time.
    TooManyRequests_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 429
        Message:
          type: string
          nullable: true
          example: >-
            Too many requests: rate limit exceeded. Slow your request cadence
            and retry.
      additionalProperties: false
      example:
        StatusCode: 429
        Message: >-
          Too many requests: rate limit exceeded. Slow your request cadence and
          retry.
    InternalServerError_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 500
        Message:
          type: string
          nullable: true
          example: 'Internal server error: an unexpected error occurred.'
      additionalProperties: false
      example:
        StatusCode: 500
        Message: 'Internal server error: an unexpected error occurred.'
    ServiceUnavailable_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 503
        Message:
          type: string
          nullable: true
          example: 'Service unavailable: the API is temporarily unavailable.'
      additionalProperties: false
      example:
        StatusCode: 503
        Message: 'Service unavailable: the API is temporarily unavailable.'
    GatewayTimeout_Result:
      required:
        - StatusCode
      type: object
      properties:
        StatusCode:
          type: integer
          format: int32
          example: 504
        Message:
          type: string
          nullable: true
          example: 'Gateway timeout: an upstream service did not respond in time.'
      additionalProperties: false
      example:
        StatusCode: 504
        Message: 'Gateway timeout: an upstream service did not respond in time.'

````