Number Port Requests

About Port Requests

Manage and track number port requests through the Port Requests API.

Table of Content

About
Port Request Listing
Port Request Management
Attachment Management
- Create
- List
- Get
- Update
- Delete
Update Status
Build an LOA PDF from a port request

Port request stats

A port request can be in one of seven states:

unconfirmed: A port request has been created, but the details have not been confirmed and the port process has not started.
submitted: Indicates the number port is ready to be processed and sent to the losing carrier.
pending: The port was submitted to the losing carrier.
scheduled: The port is in progress and the losing carrier has been notified.
completed: The port request has been finished, and numbers are activated.
rejected: Something has gone wrong during the port process. The port can be resubmitted.
canceled: The port request is definitely canceled and cannot be resubmitted.

Port states diagram

porting state flow

Port authority (Port Agent)

Port authority (sometimes called port agent or simply agent) is an account in Kazoo system which is responsible for managing their sub account port requests. They are responsible to submitted and oversees port request to losing/winner carrier.

Master account is default port authority.

If you want to manage port request for your sub account, you have to white label your account and set “I will manage port request from my account” in Branding application, “Advanced” tab. If you select that option, you have to set an Email address for port “Support Contact” in the same section.

Port Request Schema

Schema

Schema for a port request

Key	Description	Type	Default	Required	Support Level
`bill.account_number`	Account Number to identify account	`string()`		`false`
`bill.btn`	Billing Telephone Number (BTN) to identify account	`string()`		`false`
`bill.carrier`	The name of the losing carrier	`string()`		`false`
`bill.locality`	The locality (city) of the billing address the losing carrier has on record	`string()`		`false`
`bill.name`	The losing carrier billing/account name	`string()`		`false`
`bill.pin`	Personal Identification Number (PIN) to identify account	`string()`		`false`
`bill.postal_code`	The zip/postal code of the billing address the losing carrier has on record	`string()`		`false`
`bill.region`	The region (state) of the billing address the losing carrier has on record	`string()`		`false`
`bill.street_address`	The street name of the billing address the losing carrier has on record	`string()`		`false`
`bill.street_number`	The street number of the billing address the losing carrier has on record	`string()`		`false`
`bill.street_post_dir`	Street Post-Direction	`string()`		`false`
`bill.street_pre_dir`	Street Pre-Direction	`string()`		`false`
`bill.street_type`	The street type of the billing address the losing carrier has on record	`string()`		`false`
`bill`	Billing information of the losing carrier	`object()`		`false`
`comments`	The history of comments made on a port request	`["array(", "[#/definitions/comment](#comment)", ")"]`		`false`
`name`	A friendly name for the port request	`string(1..128)`		`true`
`notifications.email.send_to`	A list or string of email recipient(s)	`string()	array(string())`		`false`
`notifications.email`	Inbound Email Notifications	`object()`		`false`
`notifications`	Status notifications	`object()`		`false`
`numbers./\+?[0-9]+/`		`object()`		`false`
`numbers`	The numbers to port in	`object()`		`true`
`reference_number`	Winning carrier reference number or order ID	`string()`		`false`
`signee_name`	The name of the person authorizing the release of numbers from the losing carrier	`string()`		`false`
`signing_date`	The date in Gregorian timestamp on which the document releasing the numbers from the losing carrier was signed	`integer()`		`false`
`transfer_date`	Requested transfer date in Gregorian timestamp	`integer()`		`false`
`winning_carrier`	The name of winning carrier	`string()`		`false`

comment

Schema for a single comment

Key	Description	Type	Default	Required
`account_id`	Account ID of the commenter.	`string()`		`false`
`action_required`	Specified if an action is required by the user.	`boolean()`	`false`	`false`
`author`	Full name of the author	`string()`		`true`
`content`	Content of the comment	`string()`		`true`
`is_private`	Specified if this comment is private	`boolean()`	`false`	`false`
`timestamp`		`integer()`		`true`
`user_id`	User ID of the commenter	`string()`		`false`

List port requests

Port request API URL path has specific meaning:

/v2/port_requests: List port requests that the authenticated account is port authority for.
/v2/accounts/{ACCOUNT_ID}/port_requests: List only port request for a specific account.
/v2/accounts/{ACCOUNT_ID}/descendants/port_requests: List all sub-accounts port requests.

List port requests by type

You can issue GET requests to find all ports in a particular state.

All requests are not paginated, with the exception of the completed state. Use pagination toggles for date range as desired.

To do this add by_types query string to the request. If you don’t set by_types, by default active port request will be shown. Possible values are:

all: Lists port requests in any state
active: Lists port requests which are in these states:
- unconfirmed
- submitted
- pending
- scheduled
- rejected
progressing: Lists port requests which are in these states:
- submitted
- pending
- scheduled
suspended: Lists port requests which are in these states:
- unconfirmed
- rejected
completed: Lists port requests which are in these states:
- completed
- canceled
last_submitted: Lists all port requests by their last transition to the submitted state
Port requests states: List port requests bu their states:
- unconfirmed
- submitted
- pending
- scheduled
- completed
- rejected
- canceled

Example usage of by_type

Here an example of setting by_types:

/v2/port_requests?by_types=prgressing
/v2/accounts/{ACCOUNT_ID}/port_requests?by_types=prgressing

You can also specify multiple types by separating them by comma like example below:

/v2/port_requests?by_types=pending,scheduled,rejected
/v2/accounts/{ACCOUNT_ID}/port_requests?by_types=pending,scheduled,rejected

Search/list a port request by phone number

For finding a port request by a phone number set by_number in query string. Including an account ID in the URL will change how the port requests are searched:

/v2/port_requests?by_number={PHONE_NUMBER}: This will search for port request in the authenticated account and all its sub-accounts.
/v2/accounts/{ACCOUNT_ID}/port_requests: This will search in the {ACCOUNT_ID} and all its sub-account

Example request/response

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/port_requests?by_number={PHONE_NUMBER}

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": [
        {
            "account_id": "{ACCOUNT_ID}",
            "created": 63630107130,
            "id": "0684aa1e2785d62c76ce27d2451a1c26",
            "name": "Porting 202.555.9000",
            "numbers": {
                "{PHONE_NUMBER}": {}
            },
            "_read_only": {
              "account_id": "{ACCOUNT_ID}",
              "account_name": "{ACCOUNT_NAME}",
              "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
              "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
            },
            "comments": [],
            "port_state": "canceled",
            "sent": false,
            "updated": 63630120578,
            "uploads": {
                "file.pdf": {
                    "content_type": "application/pdf",
                    "length": 90931
                }
            }
        }
    ],
    "page_size": 1,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

List port requests that are managed by you

This lists all port requests that you (authenticated account) are managing and port authority for. See Port Authority for more details.

GET /v2/port_requests

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/port_requests

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": [
        {
            "account_id": "{ACCOUNT_ID}",
            "account_name": "{ACCOUNT_NAME}",
            "port_requests": [
                {
                    "account_id": "{ACCOUNT_ID}",
                    "created": 63630097779,
                    "id": "462da37f8be11e46161fb40bc71173a9",
                    "name": "Porting 202.555.9000",
                    "comments": [],
                    "numbers": {
                        "+12025559000": {}
                    },
                    "_read_only": {
                      "account_id": "{ACCOUNT_ID}",
                      "account_name": "{ACCOUNT_NAME}",
                      "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
                      "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
                    },
                    "port_state": "unconfirmed",
                    "sent": false,
                    "updated": 63630097779,
                    "uploads": {}
                }
            ]
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

List port requests for an account

This only lists port requests of a single account.

GET /v2/accounts/{ACCOUNT_ID}/port_requests

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests

Response is same as listing for agent.

List port requests of sub-accounts

GET /v2/accounts/{ACCOUNT_ID}/descendants/port_requests

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/descendants/port_requests

Response is same as listing for agent.

Listing all port requests by their last transition to the `submitted` state

GET /v2/accounts/{ACCOUNT_ID}/port_requests/last_submitted

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/last_submitted

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": [
        {
            "id": "{PORT_REQUEST_ID}",
            "transition": {
                "authorization": {
                    "reason": "this was approved by Jane Doe",
                    "account": {
                        "id": "{AUTH_ACCOUNT_ID}",
                        "name": "{AUTH_ACCOUNT_NAME}"
                    },
                    "user": {
                        "id": "0d46906ff1eb36bff4d09b5b32fc14be",
                        "first_name": "John",
                        "last_name": "Doe",
                        "full_name": "John Doe"
                    }
                },
                "reason": "this was approved by Jane Doe",
                "timestamp": 63664096014,
                "transition": {
                    "new": "submitted",
                    "previous": "unconfirmed"
                },
                "type": "transition"
            }
        }
    ],
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success",
    "timestamp": "2017-06-07T23:07:09",
    "version": "4.1.12"
}

Listing transitions and comments

GET /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/timeline

This shows the port request’s timeline as a sorted list of transitions and comments.

Admins are able to list every transitions and comments regardless of their privacy setting. Non admins only see transitions and public comments.

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/timeline

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
      "id": "{PORT_REQUEST_ID}",
      "created": 63663500760,
      "updated": 63664993901
    },
    "data": [
        {
            "authorization": {
                "account": {
                    "id": "{AUTH_ACCOUNT_ID}",
                    "name": "{AUTH_ACCOUNT_NAME}"
                },
                "user": {
                    "id": "0d46906ff1eb36bff4d09b5b32fc14be",
                    "first_name": "John",
                    "last_name": "Doe",
                    "full_name": "John Doe"
                }
            },
            "timestamp": 63663993575,
            "transition": {
                "new": "unconfirmed"
            },
            "type": "transition"
        },
        {
            "account_id": "0d46906ff1eb36bff4d09b5b32fc14be",
            "action_required": true,
            "content": "the comment is private, and user is required to make an action port request",
            "is_private": true,
            "timestamp": 63664000760,
            "user_id": "0d46906ff1eb36bff4d09b5b32fc14be"
        },
        {
            "account_id": "0d46906ff1eb36bff4d09b5b32fc14be",
            "content": "this is not private",
            "action_required": false,
            "is_private": false,
            "timestamp": 63664000768,
            "user_id": "0d46906ff1eb36bff4d09b5b32fc14be"
        },
        {
            "authorization": {
                "account": {
                    "id": "{AUTH_ACCOUNT_ID}",
                    "name": "{AUTH_ACCOUNT_NAME}"
                },
                "user": {
                    "id": "0d46906ff1eb36bff4d09b5b32fc14be",
                    "first_name": "John",
                    "last_name": "Doe"
                }
            },
            "reason": "this was approved by Jane Doe",
            "timestamp": 63664096014,
            "transition": {
                "new": "submitted",
                "previous": "unconfirmed"
            },
            "type": "transition"
        }
    ],
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success",
    "timestamp": "2017-06-07T23:07:09",
    "version": "4.1.12"
}

Port request management

Create a new port request

PUT /v2/accounts/{ACCOUNT_ID}/port_requests

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"numbers":{"{PHONE_NUMBER}":{}}, "name":"{PORT_REQUEST_NAME}"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests

Responses

Success

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880626267,
        "modified": 63880626267,
        "account_id": "{ACCOUNT_ID}",
        "account_name": "{ACCOUNT_NAME}",
        "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
        "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
  },
  "data": {
        "numbers": {
            "{PHONE_NUMBER}": {}
        },
        "name": "{PORT_REQUEST_NAME}",
        "comments": [],
        "id": "{PORT_REQUEST_ID}",
        "_read_only": {
            "account_id": "{ACCOUNT_ID}",
            "account_name": "{ACCOUNT_NAME}",
            "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
            "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
        },
        "sent": false,
        "port_state": "unconfirmed",
        "uploads": {},
        "updated": 63880626267,
        "created": 63880626267
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Failure: a port already exists for this number

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "{PHONE_NUMBER}": {
            "type": {
                "cause": "{PHONE_NUMBER}",
                "message": "Number is on a port request already: 41ed5722d24bfc69bc479208b274be6b"
            }
        }
    },
    "error": "500",
    "message": "invalid request",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Failure: an account already owns this number

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "{PHONE_NUMBER}": {
            "type": {
                "cause": "{PHONE_NUMBER}",
                "message": "Number exists on the system already"
            }
        }
    },
    "error": "500",
    "message": "invalid request",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Get port request details

GET /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

Sample response

{
  "auth_token": "{AUTH_TOKEN}",
  "data": {
    "created": 63630097779,
    "id": "{PORT_REQUEST_ID}",
    "name": "Porting 202.555.9000",
    "numbers": {
      "+12025559000": {
      }
    },
    "_read_only": {
      "account_id": "{ACCOUNT_ID}",
      "account_name": "{ACCOUNT_NAME}",
      "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
      "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
    },
    "comments": [],
    "port_state": "unconfirmed",
    "sent": false,
    "updated": 63630097779,
    "uploads": {
    }
  },
  "metadata": {
    "account_id": "{ACCOUNT_ID}",
    "account_name": "{ACCOUNT_NAME}",
    "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
    "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Edit a port request

POST /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"data":{"numbers":{"{PHONE_NUMBER}":{"state":"NY"}}, "name": "{PORT_REQUEST_NAME}"}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

Sample response

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
    "id": "{PORT_REQUEST_ID}",
    "created": 63630097779,
    "modified": 63630104652
  },  
  "data": {
    "id": "{PORT_REQUEST_ID}",
    "name": "{PORT_REQUEST_NAME}",
    "numbers": {
      "{PHONE_NUMBER}": {
        "state": "NY"
      }
    },
    "comments": [],
    "_read_only": {
      "account_id": "{ACCOUNT_ID}",
      "account_name": "{ACCOUNT_NAME}",
      "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
      "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
    },
    "port_state": "unconfirmed",
    "sent": false,
    "updated": 63630104652,
    "created": 63630097779,
    "uploads": {
    }
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Patch a port request

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"your_custom_info":{"carrier_port_id": "apc-8535937-gtk123", "carrier_name": "ace phone co"}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

Sample response

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
    "id": "{PORT_REQUEST_ID}",
    "created": 63630097779,
    "modified": 63630104652
  },
  "data": {
    "id": "{PORT_REQUEST_ID}",
    "name": "{PORT_REQUEST_NAME}",
    "numbers": {
      "{PHONE_NUMBER}": {
        "state": "NY"
      }
    },
    "comments": [],
    "_read_only": {
      "account_id": "{ACCOUNT_ID}",
      "account_name": "{ACCOUNT_NAME}",
      "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
      "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
    },
    "port_state": "unconfirmed",
    "sent": false,
    "updated": 63630104652,
    "created": 63630097779,
    "uploads": {
    },
    "your_custom_info": {
      "carrier_port_id": "apc-8535937-gtk123",
      "carrier_name": "ace phone co"
    }
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

DELETE a port request

DELETE /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}

Sample response

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
    "id": "{PORT_REQUEST_ID}",
    "created": 63630097779,
    "modified": 63630104652,
    "deleted": true
  },
  "data": {
    "id": "{PORT_REQUEST_ID}",
    "name": "Porting 202.555.9000",
    "comments": [],
    "numbers": {
      "+12025559000": {
        "state": "NY"
      }
    }
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Check Local Number Portability

This API is an interface to Local Number Portability (LNP) service providers. During creating Port Request you can use this API to check if numbers are portable, determine their current carrier and which carriers they are portable to.

LNP service providers can be carriers (like Bandwidth) or other services. Calling this API will query all these providers and perform an LNP lookup for all the numbers specified.

POST /v2/accounts/{ACCOUNT_ID}/port_requests/lnp_lookup

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{ "data": { "numbers": [ "{PHONE_NUMBER}" ] } }' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/lnp_lookup

Sample response

{
  "auth_token": "{AUTH_TOKEN}",
  "data": {
    "numbers": {
      "{PHONE_NUMBER}": {
        "rate_center": {
          "name": "BALTIMORE",
          "city": "BALTIMORE",
          "state": "MD",
          "lata": "238",
          "tier": "0"
        },
        "losing_carrier": {
          "spid": "6529",
          "name": "T-Mobile US:6529 - SVR/2",
          "is_wireless": true,
          "account_number_required": true,
          "minimum_porting_interval": "1"
        },
        "carriers": [
          {
            "name": "bandwidth",
            "portability": true
          }
        ]
      }
    },
    "port_state": "unconfirmed"
  },
  "metadata": {
    "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
    "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Attachment Management

List attachments on a port request

GET /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880665140
    },
    "data": {
        "file.pdf": {
            "content_type": "application/pdf",
            "length": 90931
        },
        "otherfile.pdf": {
            "content_type": "application/pdf",
            "length": 767684
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Add an attachment to a port request

Note: if ATTACHMENT_ID does not end with .pdf the extension will be appended.

PUT /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/pdf" \
    --data-binary @/path/to/file.pdf \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments?filename={ATTACHMENT_ID}

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880664678
    },    
    "data": {
        "numbers": {
            "{PHONE_NUMBER_ON_PORT_REQUEST}": {}
        },
        "name": "{PORT_REQUEST_NAME}",
        "comments": [],
        "id": "{PORT_REQUEST_ID}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Get an attachment from a port request

GET /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Accept: application/pdf" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

Streams back the contents of the PDF file {ATTACHMENT_ID}.

Replace an attachment on a port request

POST /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Content-Type: application/pdf" \
    --data-binary @/path/to/file.pdf \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880664865
    },    
    "data": {
        "numbers": {
            "{PHONE_NUMBER_ON_PORT_REQUEST}": {}
        },
        "name": "{PORT_REQUEST_NAME}",
        "comments": [],
        "id": "{PORT_REQUEST_ID}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Delete an attachment on a port request

DELETE /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/attachments/{ATTACHMENT_ID}

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "deleted": true
    },
    "data": {},
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Updating a port request status

When PATCHing a port request a reason can be added to the transition with the following request value:

reason: an optional string that can be used to describe the reason for the transition

This information will then be available in the timeline.

Note: request values can be set either in the query string or in the data payload.

Indicate a port is ready to be processed

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/submitted

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/submitted?reason=this+was+approved+by+Jane+Doe

Sample response

Success

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63630107130,
        "modified": 63630120443
    }, 
    "data": {
        "created": 63630107130,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "numbers": {
            "+12025559000": {}
        },
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
        },
        "comments": [],
        "port_state": "submitted",
        "sent": false,
        "updated": 63630120443,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Failure: charges have to be accepted

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880670722
    },
    "data": {
        "activation_charges": 10.0,
        "number_services": {
            "port": {
                "activation_charges": 10.0
            }
        }
    },
    "error": "402",
    "message": "accept charges",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Put port in pending

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/pending

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/pending

Sample response

Success

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880670722
    }, 
    "data": {
        "created": 63630107130,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "numbers": {
            "+12025559000": {}
        },
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
        },
        "comments": [],
        "port_state": "pending",
        "sent": false,
        "updated": 63880670722,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Failure: target state illegal given current state

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880670722
    }, 
    "data": {
        "port_state": {
            "enum": {
                "cause": "pending",
                "message": "Cannot move to new state from current state"
            }
        }
    },
    "error": "500",
    "message": "invalid request",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Put port in progress (sent to losing carrier)

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/scheduled

!!! note

schedule_on is a required field for this state transition.

!!! note

scheduled_date is an automatically added timestamp computed from the value of the schedule_on object.

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"schedule_on": {"timezone":"America/Los_Angeles", "date_time":"2017-06-24 12:00"}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/scheduled

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880670722
    }, 
    "data": {
        "created": 63630107130,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "schedule_on": {
            "timezone": "America/Los_Angeles",
            "date_time": "2024-06-24 12:00"
        },
        "scheduled_date": 63886474800,
        "numbers": {
            "+12025559000": {}
        },
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
        },
        "comments": [],
        "port_state": "scheduled",
        "sent": false,
        "updated": 63630120443,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Complete port, numbers will activate in the system, account will be billed

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/completed

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/completed

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63630107130
    }, 
    "data": {
        "created": 63630107130,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "schedule_on": {
            "timezone": "America/Los_Angeles",
            "date_time": "2024-06-24 12:00"
        },
        "scheduled_date": 63886474800,
        "numbers": {
            "+12025559000": {}
        },
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}",
          "ported_numbers": {
                "+14167775590": {}
            }
        },
        "comments": [],
        "port_state": "completed",
        "sent": false,
        "updated": 63630120443,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Reject a port

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/rejected

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/rejected

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880710850
    },
    "data": {
        "created": 63880664096,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "numbers": {
            "+12025559000": {}
        },
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
        },
        "comments": [],
        "port_state": "rejected",
        "sent": false,
        "updated": 63880710850,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Cancel a port

PATCH /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/canceled

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/canceled

Sample response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "id": "{PORT_REQUEST_ID}",
        "created": 63880664096,
        "modified": 63880710850
    },
    "data": {
        "created": 63880664096,
        "id": "{PORT_REQUEST_ID}",
        "name": "Porting 202.555.9000",
        "numbers": {
            "+12025559000": {}
        },
        "comments": [],
        "_read_only": {
          "account_id": "{ACCOUNT_ID}",
          "account_name": "{ACCOUNT_NAME}",
          "port_authority": "{PORT_AUTHORITY_ACCOUNT_ID}",
          "port_authority_name": "{PORT_AUTHORITY_ACCOUNT_NAME}"      
        },
        "port_state": "canceled",
        "sent": false,
        "updated": 63880710850,
        "uploads": {
            "file.pdf": {
                "content_type": "application/pdf",
                "length": 90931
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Build an LOA PDF from a port request

Download the generated Letter Of Authorization PDF file.

GET /v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/loa

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "Accept: application/x-pdf" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/port_requests/{PORT_REQUEST_ID}/loa

Number Port Requests

About Port Requests

Port request stats

Port states diagram

Port authority (Port Agent)

Schema

comment

List port requests

List port requests by type

Example usage of by_type

Search/list a port request by phone number

List port requests that are managed by you

List port requests for an account

List port requests of sub-accounts

Listing all port requests by their last transition to the submitted state

Listing transitions and comments

Port request management

Create a new port request

Success

Failure: a port already exists for this number

Failure: an account already owns this number

Get port request details

Edit a port request

Patch a port request

DELETE a port request

Check Local Number Portability

Attachment Management

List attachments on a port request

Add an attachment to a port request

Get an attachment from a port request

Replace an attachment on a port request

Delete an attachment on a port request

Updating a port request status

Indicate a port is ready to be processed

Success

Failure: charges have to be accepted

Put port in pending

Success

Failure: target state illegal given current state

Put port in progress (sent to losing carrier)

Complete port, numbers will activate in the system, account will be billed

Reject a port

Cancel a port

Build an LOA PDF from a port request

On this Page

Listing all port requests by their last transition to the `submitted` state