

Ports

Mobile Ports#

Introduction#

Below are all the APIs related to number porting in TOP.

Here are some important points to know: * For every API where you can specify a carrier, that parameter may be ignored depending on your MVNO. * For every API that uses a {DEVICE_ID}, this is currently the mdn of the device (the doc ID), but will be changed to the esn of the device once v2 is fully built.

Port status#

Port In#

status.code	status.extended	status.source
submitted	request_sent	top
submitted	update_sent	top
submitted	cancel_sent	top
rejected	{PORT_REASON_CODE}	carrier
pending	-	carrier
scheduled	-	carrier
canceled	-	carrier
completed	-	carrier

Port Out#

status.code	status.extended	status.source
submitted	initial_request	carrier
submitted	updated_request	carrier
confirmed	-	top
delayed	{PORT_REASON_CODE}	top
rejected	{PORT_REASON_CODE}	top
canceled	-	carrier
completed	-	carrier

Port reasons#

When a port is rejected or delayed, either by the carrier or TOP, a reason is provided. Below is an exhaustive is of the possible port reasons

Code	Message
scheduling_invalid_due_date	The requested due date is invalid.
scheduling_unreachable_due_date	The due date cannot be met.
scheduling_issue	Scheduling issue.
sp_network_issue	The service provider network is not ready.
sp_outside_business_hours	The request was received outside of business hours.
sp_existing_port_request	Another port request currently exists for this number.
sp_multiline_request	The carrier cannot process a multi-line request.
sp_system_down	The service provider suffers system outages.
sp_heavy_load	The service provider is under heavy load.
sp_user_not_ready	The end user is not ready.
sp_port_complexity	Port complexity issue.
sp_illegible_fax	Illegible FAX.
sp_invalid_ver_id	VER ID invalid.
mdn_not_found	This MDN was not found or does not belong to this service provider.
mdn_already_on_sp	Same new and old service provider.
mdn_not_active	This MDN is not active.
mdn_not_portable	This MDN is not portable.
mdn_pending_confirmation	This MDN is pending an order confirmation.
mdn_prepay	This MDN is a prepay MDN.
incorrect_customer_info	Customer information does not match.
incorrect_account_number	Account number required or incorrect.
incorrect_ssn	SSN required or incorrect.
incorrect_tax_id	Tax ID required or incorrect.
incorrect_password	Password/PIN required or incorrect.
incorrect_postal_code	Postal code required or incorrect.
incorrect_first_name	First name required or incorrect.
incorrect_last_name	Last name required or incorrect.
incorrect_business_name	Business name required or incorrect.
other	An unknown issue occured.

APIs#

Verify a MDN's validity for porting#

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/ports/{MDN}/validity?carrier=sprint

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/sprint/ports/{MDN}/validity
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "mdn": "{MDN}",
        "csa": "SFRSMO650",
        "provider": "Bandwidth LLC",
        "message": "{MDN} is valid for porting.",
        "number_type": "wireline",
        "valid": true
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Submit a port-in request#

Required Authentication Level: basic

PUT http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in

curl -v -X PUT \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in \
    -d '{ \
        "data": { \
            "device_id": "{DEVICE_ID}", \
            "first_name": "John", \
            "last_name": "Doe", \
            "address": { \
                "street": "Fake St", \
                "street_number": "123", \
                "extended": "", \
                "locality": "Fakeville", \
                "region": "CA", \
                "postal_code": "12345" \
            }, \
            "current_carrier": { \
                "mdn": "+12223334444", \
                "account_id": "0123456789", \
                "subscriber_full_name": "John Doe", \
                "password": "0000" \
            }, \
            "ssn": "1234" \
        } \
    }'
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{PORT_ID}",
        "esn": "{ESN}",
        "mdn" "+12223334444",
        "mvno": "2600hz",
        "account_id": "{ACCOUNT_ID}",
        "status": {
            "source": "carrier",
            "code": "scheduled"
        },
        "request_data": {
            "device_id": "{DEVICE_ID}",
            "business_name": "VoIP Inc",
            "address": {
                "street": "Natoma St",
                "street_number": "116",
                "locality": "San Francisco",
                "region": "CA",
                "postal_code": "94105"
            },
            "current_carrier": {
                "mdn": "+16502499422",
                "account_id": "2007366",
                "subscriber_full_name": "Darren Schreiber"
            },
            "device_mdn": "+12223334444"
        },
        "due_date": 63639943201,
        "origin_provider": "Bandwidth LLC",
        "messages": [
            {MESSAGE_ID}
        ]
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Alternative parameters:

Key	Value	Description
business_name	{STRING}	If the number belongs to a business, `business_name` should be provided instead of `first_name` and `last_name`
tax_id	{STRING}	If the number belongs to a business, the business Tax ID (`tax_id`) may need to be provided instead of an SSN (`ssn`)

Get a port-in document#

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{PORT_ID}",
        "esn": "{ESN}",
        "mdn" "+12223334444",
        "mvno": "2600hz",
        "account_id": "{ACCOUNT_ID}",
        "status": {
            "source": "carrier",
            "code": "scheduled"
        },
        "request_data": {
            "device_id": "{DEVICE_ID}",
            "business_name": "VoIP Inc",
            "address": {
                "street": "Natoma St",
                "street_number": "116",
                "locality": "San Francisco",
                "region": "CA",
                "postal_code": "94105"
            },
            "current_carrier": {
                "mdn": "+16502499422",
                "account_id": "2007366",
                "subscriber_full_name": "Darren Schreiber"
            },
            "device_mdn": "+12223334444"
        },
        "due_date": 63639943201,
        "origin_provider": "Bandwidth LLC",
        "messages": [
            {MESSAGE_ID}
        ]
    },
    "carrier": "sprint"
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Update a port-in request#

Required Authentication Level: basic

POST http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID}

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID} \
    -d '{ "data": { \
        "address": { \
            "street": "Right St", \
            "postal_code": "12354" \
        }, \
        "current_carrier": { \
            "account_id": "9876543210" \
        } \
    }}'

Cancel a port-in request#

Required Authentication Level: basic

DELETE http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID}

curl -v -X DELETE \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in/{PORT_ID}'

List all port-in for your MVNO#

Required Authentication Level: master

GET http://{SERVER}:{PORT}/v2/ports/in

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/ports/in
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{PORT_ID}",
            "mdn" "+12223334444",
            "esn": "{ESN}",
            "account_id": "{ACCOUNT_ID}",
            "carrier": "sprint",
            "status": {
                "code": "pending",
                "source": "carrier"
            },
            "stale": false,
            "submission_date": 63636877163,
            "additional_properties": {}
        },
        {
            "id": "{PORT_ID}",
            "mdn" "+13334445555",
            "esn": "{ESN}",
            "account_id": "{ACCOUNT_ID}",
            "carrier": "sprint",
            "status": {
                "code": "completed",
                "source": "carrier"
            },
            "stale": false,
            "submission_date": 63636877163,
            "additional_properties": {}
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

List all port-in for an account#

Required Authentication Level: basic

GET http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/accounts/{ACCOUNT_ID}/ports/in
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{PORT_ID}",
            "mdn" "+12223334444",
            "esn": "{ESN}",
            "carrier": "sprint",
            "status": {
                "code": "pending",
                "source": "carrier"
            },
            "stale": false,
            "submission_date": 63636877163,
            "additional_properties": {}
        },
        {
            "id": "{PORT_ID}",
            "mdn" "+13334445555",
            "esn": "{ESN}",
            "carrier": "sprint",
            "status": {
                "code": "completed",
                "source": "carrier"
            },
            "stale": false,
            "submission_date": 63636877163,
            "additional_properties": {}
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

List all port-out requests for your MVNO#

Required Authentication Level: master

GET http://{SERVER}:{PORT}/v2/ports/out

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/ports/out
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "id": "{PORT_ID}",
            "mdn" "+12223334444",
            "esn": "{ESN}",
            "account_id": "{ACCOUNT_ID}",
            "carrier": "sprint",
            "status": {
                "code": "rejected",
                "extended": "incorrect_last_name",
                "source": "top"
            }
        },
        {
            "id": "{PORT_ID}",
            "mdn" "+13334445555",
            "esn": "{ESN}",
            "account_id": "{ACCOUNT_ID}",
            "carrier": "sprint",
            "status": {
                "code": "completed",
                "source": "carrier"
            }
        }
    ],
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Get a port-out request document#

Required Authentication Level: master

GET http://{SERVER}:{PORT}/v2/ports/out/{PORT_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/ports/out/{PORT_ID}
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{PORT_ID}",
        "esn": "{ESN}",
        "mdn" "+12223334444",
        "mvno": "2600hz",
        "account_id": "{ACCOUNT_ID}",
        "status": {
            "source": "carrier",
            "code": "submitted",
            "extended": "initial_request"
        },
        "request_data": {
            "first_name": "John",
            "last_name": "Doe",
            "address": {
                "street": "Fake St",
                "street_number": "123",
                "extended": "",
                "locality": "Fakeville",
                "region": "CA",
                "postal_code": "12345"
            },
            "current_carrier": {
                "mdn": "+12223334444",
                "account_id": "0123456789",
                "subscriber_full_name": "John Doe",
                "password": "0000"
            },
            "ssn": "1234"
        },
        "due_date": 63639943201,
        "origin_provider": "Bandwidth LLC",
        "messages": [
            {MESSAGE_ID}
        ]
    },
    "carrier": "sprint",
    "request_id": "{REQUEST_ID}",
    "status": "success"
}

Reply to a port-out request#

Required Authentication Level: master

POST http://{SERVER}:{PORT}/v2/ports/out/{PORT_ID}

curl -v -X POST \
    -H "Content-Type:application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H "X-Kazoo-Cluster-ID: {CLUSTER_ID}" \
    http://{SERVER}:{PORT}/v2/ports/out/{PORT_ID} \
    -d '{ \
        "data": { \
            "action": "reject",
            "port_code": "incorrect_first_name" \
        } \
    }'

Note: The three possible values for action are "confirm", "delay", and "reject". No port_code should be provided for the action "confirm".

KAZOO Support Channels

Ports

Mobile Ports#

Introduction#

Port status#

Port In#

Port Out#

Port reasons#

API Index#

APIs#

Verify a MDN's validity for porting#

Submit a port-in request#

Get a port-in document#

Update a port-in request#

Cancel a port-in request#

List all port-in for your MVNO#

List all port-in for an account#

List all port-out requests for your MVNO#

Get a port-out request document#

Reply to a port-out request#