# Create Porting Request

This endpoint allows you to request one or more phone numbers to be ported from your current number provider, to CM.com.

After your porting request has been created, we will keep you informed on the status of your order via the supplied email address and (if given) via the supplied callback URL. If your porting request has been completed, the phone numbers will be directly available for use inside our platform.

# 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}/portingrequests": {
      "post": {
        "tags": [
          "Porting Requests"
        ],
        "summary": "Create Porting Request",
        "description": "This endpoint allows you to request one or more phone numbers to be ported from your current number provider, to CM.com.\r\n\r\nAfter your porting request has been created, we will keep you informed on the status of your order via the supplied email address and (if given) via the supplied callback URL. If your porting request has been completed, the phone numbers will be directly available for use inside our platform.",
        "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": "CM.Voice.PhoneNumberRequestApi.Models.Api.PortingRequest.ApiCreatePortingRequest",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiCreatePortingRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiCreatePortingRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ApiCreatePortingRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiPortingRequestOrder"
                }
              }
            }
          },
          "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": {
      "ApiCreatePortingRequest": {
        "title": "Create Porting Request",
        "required": [
          "providerCompanyName"
        ],
        "type": "object",
        "properties": {
          "phoneNumbers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiPortingPhoneNumber"
            },
            "description": "Phone numbers to be ported over.",
            "nullable": true
          },
          "providerCompanyName": {
            "minLength": 1,
            "type": "string",
            "description": "Company name of the current number provider.",
            "example": "T-Mobile"
          },
          "preferredPortingDateTime": {
            "type": "string",
            "description": "**Only used for porting non-dutch numbers.** Preferred date and time to port the phone number(s) in UTC time. Will be picked up between 6:00 and 20:00 UTC time. Should be null when the porting request should be handled as soon as possible.",
            "format": "date-time",
            "nullable": true
          },
          "companyProfileGuid": {
            "type": "string",
            "description": "Unique identifier of the company profile that will be operating the ported numbers.",
            "format": "uuid"
          },
          "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 porting request order including the updated status.",
            "nullable": true,
            "example": "https://www.example.com"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiUploadPortingRequestDocument"
            },
            "description": "Optional documents to upload with the porting request (LoA, Telco Invoice, etc.)",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A porting requests that allows you to port you phone numbers from your current provider to the CM.com platform."
      },
      "ApiPortingPhoneNumber": {
        "title": "Porting Phone Number",
        "type": "object",
        "properties": {
          "phoneNumber": {
            "minimum": 0,
            "exclusiveMinimum": true,
            "type": "integer",
            "description": "The (first) phone number to be ported.",
            "format": "int64",
            "example": 31765727000
          },
          "lastPhoneNumber": {
            "type": "integer",
            "description": "When a range of phone numbers are being ported, this number should be the last number in the range. If you are porting a single number, this value can be left empty.",
            "format": "int64",
            "nullable": true,
            "example": 31765727009
          }
        },
        "additionalProperties": false,
        "description": "Phone number to be ported"
      },
      "ApiPortingRequest": {
        "title": "Porting Request",
        "type": "object",
        "properties": {
          "phoneNumbers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiPortingPhoneNumber"
            },
            "description": "Phone numbers to be ported over.",
            "nullable": true
          },
          "providerCompanyName": {
            "type": "string",
            "description": "Company name of the current number provider.",
            "nullable": true,
            "example": "T-Mobile"
          },
          "preferredPortingDateTime": {
            "type": "string",
            "description": "**Only used for porting non-dutch numbers.** Preferred date and time to port the phone number(s) in UTC time. Will be picked up between 6:00 and 20:00 UTC time. Should be null when the porting request should be handled as soon as possible.",
            "format": "date-time",
            "nullable": true
          },
          "companyProfileGuid": {
            "type": "string",
            "description": "Unique identifier of the company profile that will be operating the ported numbers.",
            "format": "uuid"
          },
          "comment": {
            "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 porting request order including the updated status.",
            "nullable": true,
            "example": "https://www.example.com"
          }
        },
        "additionalProperties": false,
        "description": "A porting requests that allows you to port you phone numbers from your current provider to the CM.com platform."
      },
      "ApiPortingRequestDocument": {
        "title": "Porting Request Document",
        "type": "object",
        "properties": {
          "documentType": {
            "type": "string",
            "description": "Type of document (LoA, TelcoInvoice, Other)",
            "nullable": true,
            "example": "LoA"
          },
          "documentGuid": {
            "type": "string",
            "description": "Unique identifier of the document",
            "format": "uuid",
            "example": "00000000-0000-0000-0000-000000000000"
          },
          "uploadedAt": {
            "type": "string",
            "description": "Date and time when the document was uploaded",
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "description": "Current status of the document (Pending, Approved, Rejected)",
            "nullable": true,
            "example": "Pending"
          },
          "approvedAt": {
            "type": "string",
            "description": "Date and time when the document was approved (if applicable)",
            "format": "date-time",
            "nullable": true
          },
          "rejectionReason": {
            "type": "string",
            "description": "Reason for rejection if the document was rejected",
            "nullable": true,
            "example": "Document is not legible"
          },
          "fileName": {
            "type": "string",
            "description": "Original filename of the document",
            "nullable": true,
            "example": "letter_of_authorization.pdf"
          }
        },
        "additionalProperties": false,
        "description": "Represents a document associated with a porting request"
      },
      "ApiPortingRequestOrder": {
        "title": "Porting Request Order",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier",
            "format": "uuid"
          },
          "orderId": {
            "type": "string",
            "description": "The order id",
            "nullable": true
          },
          "createdOn": {
            "type": "string",
            "description": "Date and time of creation",
            "format": "date-time"
          },
          "portingData": {
            "$ref": "#/components/schemas/ApiPortingRequest"
          },
          "firstPossibleDate": {
            "type": "string",
            "description": "Date and time of the first possible date on which the porting can be performed",
            "format": "date-time",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/ApiPortingRequestOrderStatus"
          },
          "statusReason": {
            "type": "string",
            "description": "Optional comment describing the reason for the current status of the porting request",
            "nullable": true
          },
          "errorDetails": {
            "type": "string",
            "description": "Optional error details showing the details of why a porting request has been blocked automatically",
            "nullable": true
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiPortingRequestDocument"
            },
            "description": "Documents associated with this porting request (LoA, Telco Invoice, etc.)",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Order for porting request retrieved from administration api"
      },
      "ApiPortingRequestOrderStatus": {
        "title": "Porting Request Order Status",
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier",
            "format": "int32"
          },
          "key": {
            "type": "string",
            "description": "Status key",
            "nullable": true
          },
          "displayValue": {
            "type": "string",
            "description": "The value to display",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The status of a porting request"
      },
      "ApiUploadPortingRequestDocument": {
        "title": "Upload Porting Request Document",
        "required": [
          "documentGuid",
          "documentType"
        ],
        "type": "object",
        "properties": {
          "documentType": {
            "minLength": 1,
            "type": "string",
            "description": "Type of document (LoA, TelcoInvoice, Other)",
            "example": "LoA"
          },
          "documentGuid": {
            "minLength": 1,
            "type": "string",
            "description": "Unique identifier of the document from the documents API",
            "format": "uuid",
            "example": "00000000-0000-0000-0000-000000000000"
          }
        },
        "additionalProperties": false,
        "description": "Document upload information for porting requests"
      },
      "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
    }
  }
}
```