# Create Number Request

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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Phone Number Request API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.cm.com"
    }
  ],
  "paths": {
    "/voice-phonenumberrequestapi/v1/{accountGuid}/numberrequests": {
      "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.\r\n\r\nIf 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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "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.\r\nRequires 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",
            "description": "The area code to request numbers for. Required when city is not provided.\r\nIf the city is also provided, this will be used in combination with city.",
            "nullable": true,
            "example": "76"
          },
          "city": {
            "type": "string",
            "description": "City to request numbers for. Required when area code is not provided.\r\nIf the area code is also provided, this will be used in combination with area code.",
            "nullable": true,
            "example": "Amsterdam"
          },
          "region": {
            "type": "string",
            "description": "Region to request numbers for. Only required for NANPA.",
            "nullable": true,
            "example": "Alabama"
          },
          "comment": {
            "maxLength": 500,
            "type": "string",
            "description": "Additional comment for customers to for example add a distribution group or IP address.",
            "nullable": true,
            "example": "Room for extra comments or requests regarding this phone number request"
          },
          "callbackUrl": {
            "type": "string",
            "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.",
            "nullable": true,
            "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"
      },
      "ApiPhoneNumberRange": {
        "title": "Phone Number Range",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the phone number range.",
            "nullable": true,
            "example": "11111111-1111-1111-1111-111111111111"
          },
          "start": {
            "type": "integer",
            "description": "The starting phone number in a range.",
            "format": "int64",
            "nullable": true,
            "example": 311234567890
          },
          "size": {
            "type": "integer",
            "description": "The size of the range.",
            "format": "int32",
            "example": 10
          },
          "countryCode": {
            "type": "string",
            "description": "The country code in ISO 3166-1 alpha-2 format.",
            "nullable": true,
            "example": "NL"
          },
          "voiceAccountGuid": {
            "type": "string",
            "description": "Unique identifier of the Voice Account.",
            "nullable": true,
            "example": "11111111-1111-1111-1111-111111111111"
          },
          "validFrom": {
            "type": "string",
            "description": "Date and time the range is assigned to, and in use by the Voice Account.",
            "format": "date-time",
            "nullable": true,
            "example": "2025-01-01T00:00:00"
          },
          "validTo": {
            "type": "string",
            "description": "Date and time the range is no longer assigned to, nor in use by the Voice Account.",
            "format": "date-time",
            "nullable": true,
            "example": "2025-01-01T00:00:00"
          },
          "orderId": {
            "type": "string",
            "description": "Unique identifier of the order in which the range was requested.",
            "nullable": true,
            "example": "250101001"
          }
        },
        "additionalProperties": false,
        "description": "Details of a phone number range."
      },
      "Error": {
        "title": "Error",
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ErrorCollection": {
        "title": "Error Collection",
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Error"
            },
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "X-CM-PRODUCTTOKEN": {
        "type": "apiKey",
        "description": "Your producttoken",
        "name": "X-CM-PRODUCTTOKEN",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "X-CM-PRODUCTTOKEN": []
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 102,
      "1": 244,
      "2": 3,
      "3": 143,
      "4": 59,
      "5": 172,
      "6": 25,
      "7": 0,
      "8": 32,
      "9": 139,
      "10": 61,
      "11": 227
    }
  }
}
```