Create a Port Order

Lets you submit a new port order. Note that at least one porting phone number is required in your request. If you are porting multiple numbers, there is a possibility that your numbers will be split into multiple port orders.

Method

POST /portorders

Body Parameters

data
object Required
Port order object to be submitted which is composed of type and attributes.
attributes
objectRequired
Object composed of the following attributes of a port order.

Attributes

numbers
arrayRequired
Array of phone numbers in E.164 format that you wish to port. For example, +12065661654.
loa_details
object
Email addresses to which the LOA (Letter of Agency) document will be sent. You can add these details in your port order submission but the email feature has not yet been implemented.
- email
  string
  Email address of the primary recipient of the LOA document.
- cc
  string
  Email address to be copied in the LOA document email.
billing_name
stringRequired
First and last name of the authorized contact on the account with the Losing Service Provider (LSP). For business orders, this person must be authorized to make changes with the Losing Service Provider (LSP).
city
stringRequired
City where the LSP services the porting phone numbers.
country
stringRequired
Country in ISO 3166-1 alpha-2 code format where the LSP services the porting phone numbers. Valid options are US and CA.
provider
stringRequired
Current provider for the porting phone numbers.
state
stringRequired
Two-character US state or Canadian province in ISO 3166-2 format where the service city is located.
street
stringRequired
Street address where the LSP services the porting phone numbers. This is often referred to as the “Service Address” and can be different from the “Billing Address”.
street2
string
Address line 2, if any. For example, Suite 600.
usage_type
stringRequired
Possible usage types are "Business" and "Residential".
zip
stringRequired
US zip or Canadian postal code where the LSP services the porting phone numbers. For example, 98104 for the US and M4C 5K7 for Canada.
alias
string
Friendly name to be assigned to the port order.
billing_number
string
Primary phone number on record for your account with the LSP; if your carrier has not listed a billing phone number please use one of the phone numbers on the port order.
business_documents
array
List of documents to be uploaded with your port order request. While the API has the ability to render other content types like png in the browser properly, we encourage you upload business documents in PDF format. For example, https://s3.console.aws.amazon.com/s3/object/port-orders/account_info.pdf.
company
string
Company name associated with the porting phone numbers.

Required if usage_type is 'Business'.
desired_completion_date
datetime
Desired completion date of the Port Order. For example, 2018-06-14 or 2018-06-14T19:19:01.00Z.

Note: the date specified must be in the future. If this field is left blank, we will request the earliest available date.
enable_cnam_lookups
boolean
Indicates whether CNAM lookups or "dips" for caller ID information on inbound calls will be enabled for the porting phone numbers.

The default is 'False'.
last_4_ssn
string
The last four digits of the authorized contact's (billing name) Social Security Number. This generally only applies to wireless porting phone numbers.
pin
string
PIN number of the account with your LSP that is associated with the porting phone number. This is usually mandatory for wireless numbers but optional for long code and toll-free numbers.
provider_account
stringRequired
The ID for your account with the current provider. If no account number has been provided, please use a phone number on the account.
status_url
string
URL to send port order notifications to; this can be unique per port order, or the same URL can be used across multiple port orders.

For information about how callbacks work, see the Callbacks page.
presets
object
Preset values for number services related to your porting phone numbers. The preset must be created first; use the Numbers API to determine the ID of the preset. The services will be activated when the port order completes, and your phone numbers are migrated to Flowroute. Please enter the values as strings.

Note: E911 and CNAM presets will not be visible in the Manage Portal, or via the Numbers API until the number port is complete. Porting can take some time, so we cannot change these services until porting has been verified.

The routing parameters and alias will be visible
- cnam_id integer - The unique CNAM ID to be assigned for CNAM storage on the porting phone numbers (the Caller-ID Name displayed on outbound calls). Note that only long code or local numbers can be associated with a CNAM record and it takes 5-7 business days for the Caller ID Name to be applied.
- e911_id integer - The unique E911 ID containing the E911 address details to be assigned to the porting phone numbers.
- primary_route_id integer - Primary voice route ID to be assigned to the porting phone number. See Update Primary Voice Route for A Phone Number for more details.
- failover_route_id integer - Failover voice route ID to be assigned to the porting phone number. See Update Failover Voice Route for A Phone Number for more details.
- alias string - A test string associated with the number. The same alias may be assigned to multiple numbers on your account. These 'alias' strings are included in the CDR reports to allow for number grouping.

Response Format

On success, the HTTP status code in the response header is 201 Created and the response body contains the newly-created portorder_group with the related portorder objects. Port orders are split according to whether a porting phone number is longcode or toll-free. Orders containing longcode phone numbers may be further split based on country (US vs CA) and operating carrier.

HTTP
cURL

Example Request

						
POST /v2/portorders HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "data": {
    "attributes": {
      "numbers": [
        "+12065013456",
        "+18002546788"
      ],
      "loa_details": {
        "email": "mbermudez@flowroute.com",
        "cc": "mbermudez+test@flowroute.com"
      },
      "billing_name": "John Doe",
      "city": "Seattle",
      "country": "US",
      "provider": "Verizon",
      "state": "WA",
      "street": "1218 3rd Ave",
      "usage_type": "Residential",
      "zip": "98101",
      "alias": "Port Order 6/12/2018",
      "business_documents": [
        "https://s3-us-west-2.amazonaws.com/port-order-docs/csr.pdf",
        "https://s3-us-west-2.amazonaws.com/port-order-docs/bill.pdf"
      ],
      "company": "Leather Inc.",
      "desired_completion_date": "2018-07-12",
      "enable_cnam_lookups": true,
      "provider_account": "123ABC",
      "status_url": "https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack"
    }
  }
}

Example Request

			
	curl -X POST https://api.flowroute.com/v2/portorders -u accessKey:secretKey -d '{"data":{"attributes":{"numbers":["12065013456","18002546788"],"loa_details":{"email":"mbermudez@flowroute.com","cc":"mbermudez+test@flowroute.com"},"billing_name":"John Doe","city":"Seattle","country":"US","provider":"Verizon","state":"WA","street":"1218 3rd Ave","usage_type":"Residential","zip":"98101","alias":"Port Order 6/12/2018","business_documents":["https://s3-us-west-2.amazonaws.com/port-order-docs/csr.pdf","https://s3-us-west-2.amazonaws.com/port-order-docs/bill.pdf"],"company":"Leather Inc.","desired_completion_date":"2018-07-12","enable_cnam_lookups":true,"provider_account":"123ABC","status_url":"https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack"}}}' -H 'Content-Type':'application/json'

Example Responses

201 Created

		
{
	"data": {
		"attributes": {
			"date_created": "2018-06-13T04:16:55.837736+00:00"
		},
		"id": "38697",
		"links": {
			"self": "https://api.flowroute.com/v2/portorders/38697"
		},
		"relationships": {
			"portorders": {
				"data": [
				{
					"id": "42361",
					"type": "portorder"
				},
				{
					"id": "42362",
					"type": "portorder"
				}
				]
			}
		},
		"type": "portorder_group"
	},
	"included": [
	{
		"attributes": {
		"alias": "Port Order 6/12/2018",
		"billing_address": {
			"city": "Seattle",
			"country": "US",
			"state": "WA",
			"street": "1218 3rd Ave",
			"street2": null,
			"zip": "98101"
		},
		"billing_name": "John Doe",
		"billing_number": "",
		"business_documents": [{
			"data": [
			{
				"attributes": {
					"filename": "https://mysite.com/port-order-docs/csr.pdf",
					"status": "processing"
				},
				"id": "0",
				"links": {
					"self": "https://api.flowroute.com/v2/portorders/42361/files/0",
				},
				"type": "portorder-file",
			},
			{
				"attributes": {
					"filename": "https://mysite.com/port-order-docs/bill.pdf",
				"status": "processing"
				},
				"id": "0",
				"links": {
					"self": "https://api.flowroute.com/v2/portorders/42361/files/1",
				},
				"type": "portorder-file",
			},
			],
		},
		],
		"comments": [],
		"company": "Leather Inc.",
		"cost": "7.5",
		"desired_completion_date": "2018-07-12",
		"enable_cnam_lookups": true,
		"group_id": "38697",
		"last_4_ssn": "",
		"loa_details": {
			"cc": "mbermudez+test@flowroute.com",
			"email": "mbermudez@flowroute.com"
		},
		"numbers": [
			"12065013456"
		],
		"pin": "",
		"presets": {
			"cnam_id": null,
			"e911_id": null,
			"alias": null,
			"failover_route_id": null,
			"primary_route_id": null
		},
		"provider": "Verizon",
		"provider_account": "123ABC",
		"status": "pending",
		"status_updated_at": null,
		"status_url": "https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack",
		"usage_type": "residential"
		},
		"id": "42361",
		"links": {
		"self": "https://api.flowroute.com/v2/portorders/42361"
		},
		"type": "portorder"
    },
	{
		"attributes": {
			"alias": "Port Order 6/12/2018",
			"billing_address": {
				"city": "Seattle",
				"country": "US",
				"state": "WA",
				"street": "1218 3rd Ave",
				"street2": null,
				"zip": "98101"
			},
			"billing_name": "Maria Bermudez",
			"billing_number": "",
			"business_documents": [{
				"data": [
					{
						"attributes": {
							"filename": "https://mysite.com/port-order-docs/csr.pdf",
							"status": "processing"
						},
						"id": "0",
						"links": {
							"self": "https://api.flowroute.com/v2/portorders/42361/files/0",
						},
						"type": "portorder-file",
					},
					{
						"attributes": {
							"filename": "https://mysite.com/port-order-docs/bill.pdf",
							"status": "processing"
						},
						"id": "0",
						"links": {
							"self": "https://api.flowroute.com/v2/portorders/42361/files/1",
						},
						"type": "portorder-file",
					},
				],
			},
			],
			"comments": [],
			"company": "Leather Inc.",
			"cost": "0",
			"desired_completion_date": "2018-07-12",
			"enable_cnam_lookups": true,
			"group_id": "38697",
			"last_4_ssn": "",
			"loa_details": {
				"cc": "mbermudez+test@flowroute.com",
				"email": "mbermudez@flowroute.com"
			},
			"numbers": [
				"18002546788"
			],
			"pin": "",
			"presets": {
				"cnam_id": null,
				"e911_id": null,
				"alias": null,
				"failover_route_id": null,
				"primary_route_id": null
			},
			"provider": "Verizon",
			"provider_account": "123ABC",
			"status": "pending",
			"status_updated_at": null,
			"status_url": "https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack",
			"usage_type": "residential"
		},
		"id": "42362",
		"links": {
			"self": "https://api.flowroute.com/v2/portorders/42362"
		},
		"type": "portorder"
	}
	],
	"links": {
		"self": "https://api.flowroute.com/v2/portorders/38697"
	}
}

422 Unprocessable Entity

		
	{
	  "errors": [
	    {
	      "detail": {
	        "data": {
	          "attributes": {
	            "last_4_ssn": [
	              "Not a valid string."
	            ]
	          }
	        }
	      },
	      "id": "8ff37f98-df5b-4322-af46-266c6b0782f6",
	      "status": 422
	    }
	  ]
	}

422 Unprocessable Entity

		
	422 Unprocessable Entity
	{
	  "errors": [
	    {
	      "detail": {
	        "data": {
	          "attributes": {
	            "country": [
	              "Country code can be US or CA only."
	            ]
	          }
	        }
	      },
	      "id": "9977e0c3-305f-421e-bb21-661ca7793ecf",
	      "status": 422
	    }
	  ]
	}

201 Created

	
{
	"data": {
		"attributes": {
			"date_created": "2018-06-13T04:16:55.837736+00:00"
		},
		"id": "38697",
		"links": {
			"self": "https://api.flowroute.com/v2/portorders/38697"
		},
		"relationships": {
			"portorders": {
				"data": [
				{
					"id": "42361",
					"type": "portorder"
				},
				{
					"id": "42362",
					"type": "portorder"
				}
				]
			}
		},
		"type": "portorder_group"
	},
	"included": [
	{
		"attributes": {
			"alias": "Port Order 6/12/2018",
			"billing_address": {
				"city": "Seattle",
				"country": "US",
				"state": "WA",
				"street": "1218 3rd Ave",
				"street2": null,
				"zip": "98101"
			},
			"billing_name": "John Doe",
			"billing_number": "",
			"business_documents": [{
				"data": [
				{
					"attributes": {
						"filename": "https://mysite.com/port-order-docs/csr.pdf",
						"status": "processing"
					},
					"id": "0",
					"links": {
						"self": "https://api.flowroute.com/v2/portorders/42361/files/0",
					},
					"type": "portorder-file",
				},
				{
					"attributes": {
						"filename": "https://mysite.com/port-order-docs/bill.pdf",
						"status": "processing"
					},
					"id": "0",
					"links": {
						"self": "https://api.flowroute.com/v2/portorders/42361/files/1",
					},
					"type": "portorder-file",
				},
				],
			},
			],
			"comments": [],
			"company": "Leather Inc.",
			"cost": "7.5",
			"desired_completion_date": "2018-07-12",
			"enable_cnam_lookups": true,
			"group_id": "38697",
			"last_4_ssn": "",
			"loa_details": {
				"cc": "mbermudez+test@flowroute.com",
				"email": "mbermudez@flowroute.com"
			},
			"numbers": [
				"12065013456"
			],
			"pin": "",
			"presets": {
				"cnam_id": null,
				"e911_id": null,
				"alias": null,
				"failover_route_id": null,
				"primary_route_id": null
			},
			"provider": "Verizon",
			"provider_account": "123ABC",
			"status": "pending",
			"status_updated_at": null,
			"status_url": "https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack",
			"usage_type": "residential"
		},
		"id": "42361",
		"links": {
			"self": "https://api.flowroute.com/v2/portorders/42361"
		},
		"type": "portorder"
	},
	{
		"attributes": {
			"alias": "Port Order 6/12/2018",
			"billing_address": {
				"city": "Seattle",
				"country": "US",
				"state": "WA",
				"street": "1218 3rd Ave",
				"street2": null,
				"zip": "98101"
			},
			"billing_name": "Maria Bermudez",
			"billing_number": "",
			"business_documents": [{
				"data": [
				{
					"attributes": {
						"filename": "https://mysite.com/port-order-docs/csr.pdf",
						"status": "processing"
					},
					"id": "0",
					"links": {
						"self": "https://api.flowroute.com/v2/portorders/42361/files/0",
					},
					"type": "portorder-file",
				},
				{
					"attributes": {
						"filename": "https://mysite.com/port-order-docs/bill.pdf",
						"status": "processing"
					},
					"id": "0",
					"links": {
						"self": "https://api.flowroute.com/v2/portorders/42361/files/1",
					},
					"type": "portorder-file",
				},
				],
			},
			],
			"comments": [],
			"company": "Leather Inc.",
			"cost": "0",
			"desired_completion_date": "2018-07-12",
			"enable_cnam_lookups": true,
			"group_id": "38697",
			"last_4_ssn": "",
			"loa_details": {
				"cc": "mbermudez+test@flowroute.com",
				"email": "mbermudez@flowroute.com"
			},
			"numbers": [
				"18002546788"
			],
			"pin": "",
			"presets": {
				"cnam_id": null,
				"e911_id": null,
				"alias": null,
				"failover_route_id": null,
				"primary_route_id": null
			},
			"provider": "Verizon",
			"provider_account": "123ABC",
			"status": "pending",
			"status_updated_at": null,
			"status_url": "https://ycx56aoy9j.execute-api.us-west-2.amazonaws.com/dev/message_to_slack",
			"usage_type": "residential"
		},
		"id": "42362",
		"links": {
			"self": "https://api.flowroute.com/v2/portorders/42362"
		},
		"type": "portorder"
	}
	],
	"links": {
		"self": "https://api.flowroute.com/v2/portorders/38697"
	}
}

porting v2

Porting API Endpoints

Errors

Create a Port Order

Method

Body Parameters

data

attributes

Attributes

numbers

loa_details

email

cc

billing_name

city

country

provider

state

street

street2

usage_type

zip

alias

billing_number

business_documents

company

desired_completion_date

enable_cnam_lookups

last_4_ssn

pin

provider_account

status_url

presets

Response Format

Example Request

Example Request

Example Responses

201 Created

422 Unprocessable Entity

422 Unprocessable Entity

201 Created