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
    string

    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.

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"
	}
}