CM.com Number Requests API

openapi: 3.2.0
info:
  title: Phone Number Request Number Requests API
  version: v1
servers:
- url: https://api.cm.com
security:
- X-CM-PRODUCTTOKEN: []
tags:
- name: Number Requests
paths:
  /voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests:
    get:
      tags:
      - Number Requests
      summary: Get Number Requests
      description: Get all number request orders for the given Account.
      parameters:
      - name: accountGuid
        in: path
        description: Unique identifier of the Logical Account or Voice Account.
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-0000-0000-000000000000
      - name: skip
        in: query
        description: Amount of items being skipped.
        schema:
          type: integer
          format: int32
          default: 0
        example: 0
      - name: take
        in: query
        description: Amount of items being retrieved.
        schema:
          type: integer
          format: int32
          default: 30
        example: 30
      - name: q
        in: query
        description: Search for order ID.
        schema:
          type: string
          default: ''
      - name: statuses
        in: query
        description: Filter on given statusses.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Success
          headers:
            X-CM-PAGINATION-SKIP:
              description: The amount of items that have been skipped
              schema:
                type: number
            X-CM-PAGINATION-TAKE:
              description: The amount of items that have been taken
              schema:
                type: number
            X-CM-PAGINATION-TOTAL:
              description: The total amount of available items
              schema:
                type: number
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiNumberRequestOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
      operationId: getVoicePhonenumberrequestapiV1ByAccountGuidNumberrequests
      x-operation-id-source: derived
    post:
      tags:
      - Number Requests
      summary: Create Number Request
      description: 'This endpoint allows you to request one or more phone numbers for use in our platform. The prices bound to purchasing new numbers can be found in the voice management App.


        If the requested numbers are directly available, they will be immediately assigned to the specified voice account. If they are not directly available, your order may take some time to complete. We will keep you informed on the status of your order via the supplied email address and (if given) via the supplied callback URL.'
      parameters:
      - name: accountGuid
        in: path
        description: Unique identifier of the Logical Account or Voice Account.
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-0000-0000-000000000000
      requestBody:
        description: Request data for new phone number ranges
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateNumberRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ApiCreateNumberRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ApiCreateNumberRequest'
      responses:
        '200':
          description: If the numbers are not directly assignable, the `id`, `start`, `validFrom` and `validTo` fields will be null.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiPhoneNumberRange'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
      operationId: postVoicePhonenumberrequestapiV1ByAccountGuidNumberrequests
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests/{orderId}:
    get:
      tags:
      - Number Requests
      summary: Get Number Request
      description: Get a specific phone number request based on the given order ID.
      parameters:
      - name: accountGuid
        in: path
        description: Unique identifier of the Logical Account or Voice Account.
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-0000-0000-000000000000
      - name: orderId
        in: path
        description: Unique identifier of the number request order, this can be found in your confirmation email or the Voice Management App.
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiNumberRequestOrder'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
      operationId: getVoicePhonenumberrequestapiV1ByAccountGuidNumberrequestsByOrderId
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/numberrequests/statuses:
    get:
      tags:
      - Number Requests
      summary: Get Number Request Statuses
      description: A phone number request goes through a set of predefined statuses during its lifespan. With this request you can retrieve all possible statuses.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiNumberRequestOrderStatus'
      operationId: getVoicePhonenumberrequestapiV1NumberrequestsStatuses
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/numberrequests/{countryCode}/requirements:
    get:
      tags:
      - Number Requests
      summary: Get Country Requirements
      description: 'Because of different rules and regulation in different countries, we may need additional information (for example documents) after your request has been created. The required information will be checked by our support staff. Necessary documents can later be requested via email. With this endpoint you can retrieve the additional information based on the country related to the request.


        If the response contains only an empty array, it means the country that the request is bound to does not require any information.'
      parameters:
      - name: countryCode
        in: path
        description: Country code to retrieve the required fields for in ISO 3166 alpha-2 format.
        required: true
        schema:
          type: string
        example: NL
      - name: numberType
        in: query
        description: Optional type of phone number to filter requirements on
        schema:
          $ref: '#/components/schemas/ApiNumberType'
        example: Local
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiRequirement'
      operationId: getVoicePhonenumberrequestapiV1NumberrequestsByCountryCodeRequirements
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/numberrequests/restrictions:
    get:
      tags:
      - Number Requests
      summary: Get Request Restrictions
      description: Get restrictions on the number request for the given country code and number type combination. (e.g. maximum amount of numbers per request, supported range sizes)
      parameters:
      - name: CountryCode
        in: query
        description: The country code in ISO 3166-1 alpha-2 format.
        schema:
          type: string
          example: NL
        example: NL
      - name: NumberType
        in: query
        description: The phone number type (Local, National, TollFree).
        schema:
          $ref: '#/components/schemas/ApiNumberType'
        example: Local
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRequestRestrictions'
      operationId: getVoicePhonenumberrequestapiV1NumberrequestsRestrictions
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests/availability:
    get:
      tags:
      - Number Requests
      summary: Get Availability
      description: Check the availability of phone numbers based on the provided request details.
      parameters:
      - name: accountGuid
        in: path
        description: Unique identifier of the Logical Account or Voice Account.
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-0000-0000-000000000000
      - name: Quantity
        in: query
        description: The quantity of numbers to check availability for.
        schema:
          type: integer
          format: int32
          example: 25
        example: 25
      - name: RangeSize
        in: query
        description: 'The size of the range to check availability for. **Only required if a range of numbers is requested.

          Requires number ranges to be supported. See the order restrictions endpoint for the allowed ranges**'
        schema:
          type: integer
          format: int32
          example: 10
        example: 10
      - name: CountryCode
        in: query
        description: The country code in ISO 3166-1 alpha-2 format.
        schema:
          type: string
          example: NL
        example: NL
      - name: NumberType
        in: query
        description: The type of the number, either Local, National, or TollFree.
        schema:
          $ref: '#/components/schemas/ApiNumberType'
        example: Local
      - name: AreaCode
        in: query
        description: 'The area code to check availability for. Required when city is not provided.

          If the city is also provided, this will be used in combination with city.'
        schema:
          type: string
          example: '76'
        example: '76'
      - name: City
        in: query
        description: 'City to check availability for. Required when area code is not provided.

          If the area code is also provided, this will be used in combination with area code.'
        schema:
          type: string
          example: Amsterdam
        example: Amsterdam
      - name: Region
        in: query
        description: The region the city is located in (only required for Nanpa).
        schema:
          type: string
          example: Alabama
        example: Alabama
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiAvailableNumbers'
        '401':
          description: Unauthorized
      operationId: getVoicePhonenumberrequestapiV1ByAccountGuidNumberrequestsAvailability
      x-operation-id-source: derived
  /voice-phonenumberrequestapi/v1/numberrequests/locale-options:
    get:
      tags:
      - Number Requests
      summary: Get Locale Options
      description: Get locale options when requesting numbers for a specific country.
      parameters:
      - name: CountryCode
        in: query
        description: The country code in ISO 3166-1 alpha-2 format.
        schema:
          type: string
          example: NL
        example: NL
      - name: NanpaCity
        in: query
        description: City to filter regions on when requesting NANPA numbers, the result will contain only regions that have numbers available in this city.
        schema:
          type: string
          example: Los Angeles
        example: Los Angeles
      - name: NanpaRegion
        in: query
        description: Region to filter cities on when requesting NANPA numbers, the result will contain only cities that have numbers available in this region.
        schema:
          type: string
          example: California
        example: California
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiLocaleOptions'
      operationId: getVoicePhonenumberrequestapiV1NumberrequestsLocaleOptions
      x-operation-id-source: derived
components:
  schemas:
    ApiLocaleOptions:
      title: Locale Options
      type: object
      properties:
        countryCode:
          type:
          - string
          - 'null'
          description: The country code in ISO 3166-1 alpha-2 format.
          example: NL
        nanpaCity:
          type:
          - string
          - 'null'
          description: City to filter regions on when requesting NANPA numbers, the result will contain only regions that have numbers available in this city.
          example: Los Angeles
        nanpaRegion:
          type:
          - string
          - 'null'
          description: Region to filter cities on when requesting NANPA numbers, the result will contain only cities that have numbers available in this region.
          example: California
        cities:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of cities to choose from for requesting a number
        regions:
          type:
          - array
          - 'null'
          items:
            type: string
          description: List of regions to choose from for requesting a number, only for NANPA
      additionalProperties: false
      description: Locale options when requesting numbers for a specific country and number type
    ApiNumberRequest:
      title: Number Request
      type: object
      properties:
        companyProfileGuid:
          type: string
          description: Unique identifier of the company profile that will be operating the requested numbers.
          format: uuid
          example: 11111111-1111-1111-1111-111111111111
        quantity:
          type: integer
          description: The requested quantity. **Only required if no requested ranges are supplied.**
          format: int32
          example: 25
        rangeSize:
          type: integer
          description: The size of the range to be requested. **Only required if number blocks are supported. See the order restrictions endpoint for allowed ranges**
          format: int32
        countryCode:
          type:
          - string
          - 'null'
          description: The country code in ISO 3166-1 alpha-2 format.
          example: NL
        numberType:
          type:
          - string
          - 'null'
          description: The type of the number, either Local, National, or TollFree.
          example: Local
        areaCode:
          type:
          - string
          - 'null'
          description: The area code (prefix) of the requested numbers.
          example: '76'
        city:
          type:
          - string
          - 'null'
          description: 'City to request numbers for. Required when area code is not provided.

            If the area code is also provided, this will be used in combination with area code.'
          example: Breda
        region:
          type:
          - string
          - 'null'
          description: Region to request numbers for. Only required for NANPA.
          example: Alabama
        comment:
          type:
          - string
          - 'null'
          description: Additional comment for customers to for example add a distribution group or IP address.
          example: Room for extra comments or requests regarding this phone number request
        callbackUrl:
          type:
          - string
          - 'null'
          description: URL that we'll send a POST request to when the status of the request has been updated. The body of this post request will contain the entire number request order including the updated status.
          example: https://www.example.com
      additionalProperties: false
      description: Request model for requesting new phone numbers.
    ApiAvailableNumbers:
      title: Available Numbers
      type: object
      properties:
        quantity:
          type: integer
          description: The amount of number blocks.
          format: int32
          example: 25
        rangeSize:
          type: integer
          description: The size of the number blocks.
          format: int32
          example: 10
        countryCode:
          type:
          - string
          - 'null'
          description: The country code in ISO 3166-1 alpha-2 format.
          example: NL
        numberType:
          type:
          - string
          - 'null'
          description: The phone number type (Local, National, TollFree).
          example: Local
        areaCode:
          type:
          - string
          - 'null'
          description: The area code.
          example: '76'
        city:
          type:
          - string
          - 'null'
          description: The city or town.
          example: Amsterdam
        region:
          type:
          - string
          - 'null'
          description: The region or state, only for NANPA.
          example: Alabama
        hasAvailableNumbers:
          type: boolean
          description: If true, the phone numbers to request are available
          example: true
        immediatelyAvailable:
          type: boolean
          description: If true, the numbers are available for immediate provisioning, otherwise there may be a delay
          example: false
      additionalProperties: false
      description: Result of checking for number availability
    ApiRequirement:
      title: Requirement
      type: object
      properties:
        key:
          type:
          - string
          - 'null'
          description: The key of the requirement.
          example: proof_of_company_address
        type:
          $ref: '#/components/schemas/ApiRequirementType'
        downloadLink:
          type:
          - string
          - 'null'
          description: URL where the requirement can be downloaded if it's a document that needs to be signed (Type = 4).
          example: https://api.cm.com/resources/v2/public/00000000-0000-0000-0000-000000000000/content
        isForReseller:
          type: boolean
          description: Determines whether the requirement is specifically for resellers
      additionalProperties: false
      description: A country specific rule or regulation that a request must meet. This can for example be a certain document that must be provided.
    ApiNumberRequestOrder:
      title: Number Request Order
      type: object
      properties:
        id:
          type: string
          description: Unique identifier
          format: uuid
          example: 11111111-1111-1111-1111-111111111111
        orderId:
          type: integer
          description: The order id
          format: int32
          example: 250101001
        createdOn:
          type: string
          description: Date and time of creation
          format: date-time
          example: '2025-01-01T00:00:00'
        requestData:
          $ref: '#/components/schemas/ApiNumberRequest'
        status:
          type:
          - string
          - 'null'
          description: The status key of the phone number request
          example: InProgress
        comment:
          type:
          - string
          - 'null'
          description: Optional comment describing the reason for the current status of the phone number request
          example: Your request is currently in progress.
      additionalProperties: false
      description: Request model for a phone number request order
    ApiRequirementType:
      title: Requirement Type
      enum:
      - Document
      - CompanyRule
      - NumberRule
      - SignedDocument
      type: string
      description: The type of the requirement where `1` = document, `2` = requirement for a company, `3` = requirement for a number request and `4` = signed document..
    ErrorCollection:
      title: Error Collection
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
        errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ApiNumberRequestOrderStatus:
      title: Number Request Order Status
      type: object
      properties:
        key:
          type:
          - string
          - 'null'
          description: Status key
          example: InProgress
        displayValue:
          type:
          - string
          - 'null'
          description: The value to display
          example: In Progress
      additionalProperties: false
      description: The status of a phone numbers request order
    ApiPhoneNumberRange:
      title: Phone Number Range
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the phone number range.
          example: 11111111-1111-1111-1111-111111111111
        start:
          type:
          - integer
          - 'null'
          description: The starting phone number in a range.
          format: int64
          example: 311234567890
        size:
          type: integer
          description: The size of the range.
          format: int32
          example: 10
        countryCode:
          type:
          - string
          - 'null'
          description: The country code in ISO 3166-1 alpha-2 format.
          example: NL
        voiceAccountGuid:
          type:
          - string
          - 'null'
          description: Unique identifier of the Voice Account.
          example: 11111111-1111-1111-1111-111111111111
        validFrom:
          type:
          - string
          - 'null'
          description: Date and time the range is assigned to, and in use by the Voice Account.
          format: date-time
          example: '2025-01-01T00:00:00'
        validTo:
          type:
          - string
          - 'null'
          description: Date and time the range is no longer assigned to, nor in use by the Voice Account.
          format: date-time
          example: '2025-01-01T00:00:00'
        orderId:
          type:
          - string
          - 'null'
          description: Unique identifier of the order in which the range was requested.
          example: '250101001'
      additionalProperties: false
      description: Details of a phone number range.
    Error:
      title: Error
      type: object
      properties:
        code:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
      additionalProperties: false
    ApiRequestRestrictions:
      title: Request Restrictions
      type: object
      properties:
        countryCode:
          type:
          - string
          - 'null'
          description: The country code in ISO 3166-1 alpha-2 format.
          example: NL
        numberType:
          type:
          - string
          - 'null'
          description: The phone number type (Local, National, TollFree).
          example: Local
        supportedRangeSizes:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int32
          description: Supported range sizes for number requests
          example:
          - 1
          - 10
          - 100
          - 1000
        maxNumbersPerRequest:
          type:
          - integer
          - 'null'
          description: The maximum amount of numbers that can be requested in a single request, can be null if there is no limit
          format: int32
          example: 1000
      additionalProperties: false
      description: Restrictions for number requests
    ApiCreateNumberRequest:
      title: Create Number Request
      type: object
      properties:
        companyProfileGuid:
          type: string
          description: Unique identifier of the company profile that will be operating the requested numbers.
          format: uuid
          example: 11111111-1111-1111-1111-111111111111
        quantity:
          maximum: 1000
          minimum: 1
          type: integer
          description: The quantity of numbers to be requested.
          format: int32
          example: 25
        rangeSize:
          type: integer
          description: 'The size of the range to be requested. **Only required if a range of numbers is requested.

            Requires number ranges to be supported. See the order restrictions endpoint for the allowed ranges**'
          format: int32
          example: 10
        numberType:
          $ref: '#/components/schemas/ApiNumberType'
        areaCode:
          type:
          - string
          - 'null'
          description: 'The area code to request numbers for. Required when city is not provided.

            If the city is also provided, this will be used in combination with city.'
          example: '76'
        city:
          type:
          - string
          - 'null'
          description: 'City to request numbers for. Required when area code is not provided.

            If the area code is also provided, this will be used in combination with area code.'
          example: Amsterdam
        region:
          type:
          - string
          - 'null'
          description: Region to request numbers for. Only required for NANPA.
          example: Alabama
        comment:
          maxLength: 500
          type:
          - string
          - 'null'
          description: Additional comment for customers to for example add a distribution group or IP address.
          example: Room for extra comments or requests regarding this phone number request
        callbackUrl:
          type:
          - string
          - 'null'
          description: URL that we'll send a POST request to when the status of the request has been updated. The body of this post request will contain the entire number request order including the updated status.
          example: https://www.example.com
      additionalProperties: false
      description: Request model for requesting new phone numbers.
    ApiNumberType:
      title: Number Type
      enum:
      - Local
      - National
      - TollFree
      type: string
      description: Phone number type
  securitySchemes:
    X-CM-PRODUCTTOKEN:
      type: apiKey
      description: Your producttoken
      name: X-CM-PRODUCTTOKEN
      in: header
x-readme:
  explorer-enabled: true
  proxy-enabled: true