Phone Numbers API

About Phone Numbers

The 2600Hz API for managing numbers.

Per-number CRUD operations

  • {PHONE_NUMBER} has to be URL-encoded
    • e.g. turn +14155555555 into %2B14155555555
    • Note 4123456789 is turned into +14123456789
    • Note however, 41234567 is turned into +41234567, so be careful!
  • To add/modify numbers, either:
    • Account document must be showing pvt_wnm_allow_additions as true
    • Or auth must be done via master account.

Schema

Schema for a number

KeyDescriptionTypeDefaultRequiredSupport Level
carrier_nameName of the carrier providerstring(1..30)false
cnam.display_nameName that displayed in the callee sidestring(1..15)false
cnam.inbound_lookupLookup name that associated with the number in provider database and display it for inbound callboolean()false
cnamCaller ID Name of a person or business that is placing a callobject()false
create_with_stateThe state to create numbers in`string(‘aging''available''deleted''discovery'
e911.activated_timeThe time stamp e911 was provisionedstring()false
e911.callback_cid_number10-digit DID used as caller ID to PSAP, overrides CIDstring(10)false
e911.caller_nameThe name that will show to emergency servicesstring(3..)false
e911.countryThe country is identified by the two-letter ISO 3166 code. Example: USstring(2)false
e911.delivery_methodHow the emergency call is routed by the destination handler (not applicable to all providers)`string(‘direct''three_way''security_desk’)`
e911.extended_addressThe suite/floor/apt. address where the number is in servicestring()false
e911.latitudeThe geo-position of a location, north or south of the equator, using WGS84 formattingstring(0..11)false
e911.legacy_data.house_numberHouse number, numeric part only. Example: 123string()false
e911.legacy_data.predirectionalThe name that will show to emergency servicesstring()false
e911.legacy_data.streetnameThe name that will show to emergency servicesstring()false
e911.legacy_data.suiteThe name that will show to emergency servicesstring()false
e911.legacy_dataLegacy E911 informationobject()false
e911.localityThe locality (city) where the number is in servicestring()true
e911.location_idThe e911 provisioning system internal id for this service addressstring()false
e911.location_identifierUnited States unique 10-digit number known as an E911 location identifier (ELIN)integer()false
e911.longitudeThe geo-position of a location, east or west of the prime meridian, using WGS84 formattingstring(0..11)false
e911.notification_contact_emails.[]string()false
e911.notification_contact_emailsA list of email addresses to receive notification when this number places an emergency callarray(string())[]false
e911.plus_fourThe extended zip/postal code where the number is in servicestring()false
e911.postal_codeThe zip/postal code where the number is in servicestring()true
e911.regionThe region (state) where the number is in servicestring(2)true
e911.statusThe e911 provisioning system status for this service address`string(‘INVALID''GEOCODED''PROVISIONED''REMOVED'
e911.street_addressThe street address where the number is in servicestring()true
e911E911 information for the current phone numberobject()false
porting.billing_account_idThe account id the losing carrier has on filestring()false
porting.billing_extended_addressThe suit/floor/apt. address the losing carrier has on filestring()false
porting.billing_localityThe locality (city) the losing carrier has on filestring()false
porting.billing_nameThe name or company name the losing carrier has on filestring()false
porting.billing_postal_codeThe zip/postal code the losing carrier has on filestring()false
porting.billing_regionThe region (state) the losing carrier has on filestring()false
porting.billing_street_addressThe street address the losing carrier has on filestring()false
porting.billing_telephone_numberThe BTN of the account the number belongs tostring()false
porting.comments.[]string()false
porting.commentsAn array of commentsarray(string())false
porting.customer_contactThe phone number that can be used to contact the owner of the numberstring()false
porting.port_idThe id of the port requeststring()false
porting.requested_port_dateThe requested port datestring()false
porting.service_providerThe name of the losing carrierstring()false
portingPorting (in) information for the phone numberobject()false

Search For Available Numbers On System

  • PREFIX: a 3-digit number prefix or an URL-encoded e164 prefix (e.g. 499 or %2B1499)
  • QUANTITY: maximum amount of numbers to be returned (e.g. 2)
  • OFFSET: page number (e.g. 0)

GET /v2/phone_numbers?prefix={PREFIX}&quantity={QUANTITY}&offset={OFFSET}&country={COUNTRY}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/phone_numbers?prefix=415&quantity=2
{
    "auth_token": "",
    "metadata": {},
    "data": [
        {
            "e164": "+14152338397",
            "formatted_number": "1-415-233-8397",
            "npa_nxx": "415233",
            "number": "+14152338397",
            "number_id": "4AA418FB-3409-4340-8210-E7EAFE2AB118",
            "rate_center": {
                "lata": "722",
                "name": "SAN RAFAEL",
                "state": "CA"
            },
            "status": "Available",
            "ten_digit": "4152338397"
        },
        {
            "e164": "+14152338421",
            "formatted_number": "1-415-233-8421",
            "npa_nxx": "415233",
            "number": "+14152338421",
            "number_id": "0CD68E85-F149-477F-9C13-1E720ACCC3EE",
            "rate_center": {
                "lata": "722",
                "name": "SAN RAFAEL",
                "state": "CA"
            },
            "status": "Available",
            "ten_digit": "4152338421"
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Search for available numbers you own

  • PREFIX: a 3-digit number prefix or an URL-encoded e164 prefix (e.g. 499 or %2B1499)
  • QUANTITY: maximum amount of numbers to be returned (e.g. 2)
  • OFFSET: page number (e.g. 0)

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers?prefix={PREFIX}&quantity={QUANTITY}&offset={OFFSET}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers?prefix=555&quantity=3&offset=6
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": [
        {
            "number": "+15552225562",
            "state": "available"
        },
        {
            "number": "+15554445558",
            "state": "discovery"
        },
        {
            "number": "+15552225562",
            "state": "available"
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

See How Many Digits A {PREFIX} Can Take

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/carriers_info

Depending on your carriers configuration you may be allowed to query numbers by NPA-NXX instead of just NPA.

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/carriers_info
{
    "auth_token": "{AUTH_TOKEN}",
    "meta_data": "{META_DATA}",
    "data": {
        "maximal_prefix_length": 3,
        "usable_carriers": [
            "bandwidth2",
            "bandwidth",
            "inum",
            "local",
            "inventory",
            "managed",
            "mdn",
            "other",
            "simwood",
            "telnyx",
            "vitelity",
            "voip_innovations"
        ],
        "usable_creation_states": [
            "aging",
            "available",
            "in_service",
            "port_in",
            "reserved"
        ]
    },
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "timestamp": "2024-04-12T14:04:37Z",
    "version": "4.0.0"
}

List Account’s Phone Numbers

This lists the numbers an account owns, along with their properties.

Note

one can apply filters such as ?filter_state=in_service or ?created_from=63627345744

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers?page_size=2&start_key=%2B14152338421
{
    "auth_token": "{AUTH_TOKEN}",
    "meta_data": "{META_DATA}",
    "data": {
        "cascade_quantity": 1,
        "numbers": {
            "+14152338421": {
                "state": "in_service",
                "features": [],
                "features_allowed": [],
                "features_denied": [],
                "assigned_to": "{ACCOUNT_ID}",
                "created": 63628550806,
                "updated": 63628550806,
                "features_available":[
                    "carrier_name",
                    "cnam",
                    "e911",
                    "force_outbound",
                    "inbound_cnam",
                    "outbound_cnam",
                    "port",
                    "prepend",
                    "ringback"
                    ]
            },
            "+14152338397": {
                "state":"reserved",
                "features": [
                    "local"
                ],
                "features_allowed": [],
                "features_denied": [],
                "assigned_to": "{ACCOUNT_ID}",
                "created": 63880145085,
                "updated": 63880145085,
                "features_available": [
                    "carrier_name",
                    "force_outbound",
                    "prepend",
                    "ringback"
                ]
            }
        }
    },
    "next_start_key": "{NEXT_START_KEY}",
    "page_size": 2,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Remove a number from the account owning it

DELETE /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

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

Response

Success

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880388893,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880369851,
        "carrier_module": "bandwidth2",
        "deleted": true
    },
  "data": {
        "id": "{PHONE_NUMBER}",
        "state": "available"
  },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Number not in account

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "message": "bad identifier",
        "not_found": "The number could not be found",
        "cause": "{PHONE_NUMBER}"
    },
    "error": "404",
    "message": "bad_identifier",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Remove A Number From Account (admin Only)

DELETE /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}?hard=true

Response

{
  "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "modified": 63880152016,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "cnam",
                "e911",
                "force_outbound",
                "inbound_cnam",
                "outbound_cnam",
                "port",
                "prepend",
                "ringback"
            ]
        },
        "created": 63863803040,
        "carrier_module": "bandwidth2",
        "deleted": true
    },
    "data": {
        "ui_metadata": {
            "version": "5.2-3",
            "ui": "monster-ui",
            "origin": "common"
        },
        "id": "{PHONE_NUMBER}",
        "state": "deleted"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

List An Account’s Specific Phone Number

Show the number’s properties along with user-defined properties.

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

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

Success Response

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880152996,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880145085,
        "carrier_module": "local"
    },
  "data": {
        "ui_metadata": {
            "version": "5.2-3",
            "ui": "monster-ui",
            "origin": "common"
        },
        "id": "{PHONE_NUMBER}",
        "features": [
            "local"
        ],
        "my_own_fields": {
        },
        "used_by": "callflow",
        "state": "reversed"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Failure Response

Possible reasons for failure:

  • Account does not have enough privileges to read number
  • Number does not exist
{
    "auth_token": "{AUTH_TOKEN}",
    "metadate": {},
    "data": {
        "message": "bad identifier",
        "not_found": "The number could not be found",
        "case": "{PHONE_NUMBER}"
    },
    "error": "404",
    "message": "bad_identifier",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Update Public Fields Of A Number

Note

some public fields are used to configure number features.

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"my_own_field":"some other value", "cnam":{"display_name":"My caller ID", "inbound_lookup":true}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}
{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880390159,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "cnam",
                "e911",
                "force_outbound",
                "inbound_cnam",
                "outbound_cnam",
                "port",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880369851,
        "carrier_module": "bandwidth2"
    },
  "data": {
        "my_own_field": "some other value",
        "cnam": {
            "inbound_lookup": true,
            "display_name": "My caller ID"
        },
        "id": "{PHONE_NUMBER}",
        "features": [
            "inbound_cnam",
            "outbound_cnam"
        ],
        "state": "in_service"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Patch Public Fields Of A Number

PATCH /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"my_own_field":42}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}
{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880390308,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "cnam",
                "e911",
                "force_outbound",
                "inbound_cnam",
                "outbound_cnam",
                "port",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880369851,
        "carrier_module": "bandwidth2"
    },
  "data": {
        "my_own_field": 42,
        "cnam": {
            "inbound_lookup": true,
            "display_name": "My caller ID"
        },
        "id": "{PHONE_NUMBER}",
        "features": [
            "inbound_cnam",
            "outbound_cnam"
        ],
        "state": "in_service"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Add a number to the database

Adds a number to the database, returning its properties.

Note

Set field "create_with_state" in payload to your desired number state (defaults to "in_service").

Note

Payload is optional.

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"my_own_field": {}}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

Success Response

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880412858,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880412858,
        "carrier_module": "local"
    },
    "data": {
        "my_own_field": {},
        "id": "{PHONE_NUMBER}",
        "features": [
            "local"
        ],
        "state": "in_service"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Failure Responses

Number already exists

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "cause": "{PHONE_NUMBER}",
        "code": 409,
        "error": "number_exists",
        "message": "number {PHONE_NUMBER} already exists"
    },
    "error": "409",
    "message": "number_exists",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Number does not conform to E.164 format

A non-conforming {PHONE_NUMBER}: "+141510010+15".

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "cause": "{PHONE_NUMBER}",
        "code": 400,
        "error": "not_reconcilable",
        "message": "number {PHONE_NUMBER} is not reconcilable"
    },
    "error": "404",
    "message": "not_reconcilable",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Account unauthorized

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "code": 403,
        "error": "forbidden",
        "cause": "creating number in state 'in_service' is not allowed",
        "message": "requestor is unauthorized to perform operation"
    },
    "error": "403",
    "message": "forbidden",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Check Availability Of Phone Numbers

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/check

This API checks if the numbers are still available for purchase.

A status of "error" may be due to:

  • Number not being handled by carrier knm_other
  • PhoneBook being unresponsive
curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"numbers": [{PHONE_NUMBER1}, {PHONE_NUMBER2}]}}'
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/check

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "meta_data": {},
    "data": {
        "{PHONE_NUMBER1}": "success",
        "{PHONE_NUMBER2}": "error"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Get Locality Information For A Collection Of Numbers

PhoneBook

Phonebook is an external service that “abstract” carrier number inventory and the sysadmin need to provide and configure it for this API endpoint to work.

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/locality

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/locality

Success Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "{PHONE_NUMBER1}": {
            "carrier": {
                "company": "T-Mobile USA Inc",
                "dba": "T-Mobile USA Inc",
                "id": "6529",
                "type": "WIRELESS"
            },
            "country": "US",
            "e164_number": "{PHONE_NUMBER1}",
            "geocode": {
                "locality": "California"
            },
            "locality": {
                "alt_postal_codes": [
                    "94965",
                    "94941"
                ],
                "extended_postal_code": null,
                "latitude": "37.8725359094361",
                "locality": "Belvedere",
                "longitude": "-122.465900466078",
                "postal_code": "94920",
                "province": "CA",
                "switch": "OKLECAZVGT0",
                "type": "WIRELESS"
            },
            "number": "{PHONE_NUMBER1}",
            "status": "success"
        },
        "{PHONE_NUMBER2}": {
            "carrier": {
                "company": "Bandwidth.com CLEC LLC - CA",
                "dba": "Bandwidth.com CLEC LLC",
                "id": "981E",
                "type": "CLEC"
            },
            "country": "US",
            "e164_number": "{PHONE_NUMBER2}",
            "geocode": {
                "locality": "California"
            },
            "locality": {
                "alt_postal_codes": [
                    "94939",
                    "94976"
                ],
                "extended_postal_code": null,
                "latitude": "37.9267845442655",
                "locality": "Corte Madera",
                "longitude": "-122.527924297914",
                "postal_code": "94904",
                "province": "CA",
                "switch": "SNFCCA21XUY",
                "type": "LANDLINE"
            },
            "number": "{PHONE_NUMBER2}",
            "status": "success"
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Backend to PhoneBook not set up

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": "Unable to acquire numbers missing carrier url",
    "error": "500",
    "message": "init failed",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

List Available Numbers Of A Given US City

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/prefix

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/prefix?city={CITY}

Success Response

Country or city not found

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "data": {},
        "error": 404,
        "message": "Not Found",
        "status": "error"
    },
    "error": "500",
    "message": "init failed",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Backend to PhoneBook not set up

{
    "auth_token": "{AUTH_TOKEN}",
    "data": "Unable to acquire numbers missing carrier url",
    "error": "500",
    "message": "init failed",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Remove a list of numbers from the database

DELETE /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}", "{PHONE_NUMBER3}"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {
            "{PHONE_NUMBER1}": {
                "id": "{PHONE_NUMBER1}",
                "features": [
                    "local"
                ],
                "state": "available",
                "_read_only": {
                    "modified": 63880454152,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880145085,
                    "carrier_module": "local"
                }
            },
            "{PHONE_NUMBER2}": {
                "id": "{PHONE_NUMBER2}",
                "state": "available",
                "_read_only": {
                    "modified": 63880454152,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880369851,
                    "carrier_module": "bandwidth2"
                }
            },
            "{PHONE_NUMBER3}": {
                "id": "{PHONE_NUMBER3}",
                "state": "available",
                "_read_only": {
                    "modified": 63880454152,
                    "id": "{PHONE_NUMBER3}",
                    "features": {
                        "settings": {},
                        "available": [
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880369851,
                    "carrier_module": "bandwidth2"
                }
            }
        },
        "error": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Remove a list of numbers from account (admin only)

DELETE /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}", "{PHONE_NUMBER3}"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection?hard=true
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {
            "{PHONE_NUMBER1}": {
                "myfield": 1337,
                "id": "{PHONE_NUMBER1}",
                "state": "deleted",
                "_read_only": {
                    "modified": 63880454928,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "cnam",
                            "e911",
                            "force_outbound",
                            "inbound_cnam",
                            "outbound_cnam",
                            "port",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880369851,
                    "carrier_module": "bandwidth2"
                }
            },
            "{PHONE_NUMBER2}": {
                "my_global_field": 12345,
                "id": "{PHONE_NUMBER2}",
                "features": [
                    "local"
                ],
                "state": "deleted",
                "_read_only": {
                    "modified": 63880454928,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            },
            "{PHONE_NUMBER3}": {
                "my_global_field": 12345,
                "id": "{PHONE_NUMBER3}",
                "features": [
                    "local"
                ],
                "state": "deleted",
                "_read_only": {
                    "modified": 63880454928,
                    "id": "{PHONE_NUMBER3}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            }
        },
        "error": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Update public fields of a list of numbers

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}"], "myfield": 1337}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {
            "+14157770055": {
                "myfield": 1337,
                "id": "{PHONE_NUMBER1}",
                "state": "in_service",
                "_read_only": {
                    "modified": 63880415140,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "cnam",
                            "e911",
                            "force_outbound",
                            "inbound_cnam",
                            "outbound_cnam",
                            "port",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880369851,
                    "carrier_module": "bandwidth2"
                }
            },
            "+13050038901": {
                "myfield": 1337,
                "id": "{PHONE_NUMBER2}",
                "features": [
                    "local"
                ],
                "state": "port_in",
                "_read_only": {
                    "modified": 63880415140,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880371131,
                    "carrier_module": "local"
                }
            }
        },
        "error": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Patch public fields of a list of numbers

PATCH /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

curl -v -X PATCH \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}"], "my_global_field": 12345}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {
            "{PHONE_NUMBER1}": {
                "my_global_field": 12345,
                "id": "{PHONE_NUMBER1}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880384092,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            },
            "{PHONE_NUMBER2}": {
                "my_global_field": 12345,
                "id": "{PHONE_NUMBER2}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880384092,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            }
        },
        "error": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Add a list of numbers to the database

Note: set field "create_with_state" in payload to your desired number state (defaults to "in_service").

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}", "{PHONE_NUMBER3}"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection

Success Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "success": {
            "{PHONE_NUMBER1}": {
                "id": "{PHONE_NUMBER1}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880383793,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            },
            "{PHONE_NUMBER2}": {
                "id": "{PHONE_NUMBER2}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880383793,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880383793,
                    "carrier_module": "local"
                }
            }
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Failure

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {},
        "error": {
            "+14157770012": {
                "code": 409,
                "error": "number_exists",
                "cause": "{PHONE_NUMBER1}",
                "message": "number {PHONE_NUMBER1} already exists"
            },
            "+14157770022": {
                "code": 409,
                "error": "number_exists",
                "cause": "{PHONE_NUMBER2}",
                "message": "number {PHONE_NUMBER2} already exists"
            }
        }
    },
    "request_id": "{REQUEST_ID}"
}

List classifiers

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/classifiers

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/classifiers
{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": "{META_DATA}",
  "data": [
    {
      "name": "caribbean",
      "friendly_name": "Caribbean",
      "pretty_print": "SS(###) ###-####",
      "regex": "^\\+?1((?:684|264|268|242|246|441|284|345|767|809|829|849|473|671|876|664|670|787|939|869|758|784|721|868|649|340)\\d{7})$"
    },
    {
      "name": "did_us",
      "friendly_name": "US DID",
      "pretty_print": "SS(###) ###-####",
      "regex": "^\\+?1?([2-9][0-9]{2}[2-9][0-9]{6})$"
    },
    {
      "name": "emergency",
      "friendly_name": "Emergency Dispatcher",
      "regex": "^(911)$"
    },
    {
      "name": "international",
      "friendly_name": "International",
      "regex": "^(011\\d*)$|^(00\\d*)$"
    },
    {
      "name": "toll_us",
      "friendly_name": "US Toll",
      "pretty_print": "SS(###) ###-####",
      "regex": "^\\+1(900\\d{7})$"
    },
    {
      "name": "tollfree_us",
      "friendly_name": "US TollFree",
      "pretty_print": "SS(###) ###-####",
      "regex": "^\\+1((?:800|888|877|866|855)\\d{7})$"
    },
    {
      "name": "unknown",
      "friendly_name": "Unknown",
      "regex": "^(.*)$"
    }
  ],
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Fix issues

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/fix

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/fix
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "numbers": {
            "+14157771155": {
                "state": "reserved",
                "features": [],
                "features_allowed": [],
                "features_denied": [],
                "assigned_to": "{ACCOUNT_ID}",
                "created": 63880369851,
                "updated": 63880370278,
                "features_available": [
                    "carrier_name",
                    "cnam",
                    "e911",
                    "force_outbound",
                    "inbound_cnam",
                    "outbound_cnam",
                    "port",
                    "prepend",
                    "ringback"
                ]
            },
            "+14157770055": {
                "state": "in_service",
                "features": [],
                "features_allowed": [],
                "features_denied": [],
                "assigned_to": "{ACCOUNT_ID}",
                "created": 63880369851,
                "updated": 63880369851,
                "features_available": [
                    "carrier_name",
                    "cnam",
                    "e911",
                    "force_outbound",
                    "inbound_cnam",
                    "outbound_cnam",
                    "port",
                    "prepend",
                    "ringback"
                ]
            }
        },
        "cascade_quantity": 2
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Fix used_by field (and others) of a specific number

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/fix/{PHONE_NUMBER}

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/fix/%2B15554445563
{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {},
  "data": {},
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Return which account a number belongs to

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/identify

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

Success Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "account_id": "account0000000000000000000000002",
        "number": "{PHONE_NUMBER}"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Number not in service or account disabled

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "account_id": "009deaaadc97b2ae693c6cc4920988e8",
        "cause": "not_in_service"
    },
    "error": "400",
    "message": "client error",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Number not found or not enough privileges

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "message": "bad identifier",
        "not_found": "The number could not be found"
    },
    "error": "404",
    "message": "bad_identifier",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Create a number in the port_in state

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/port

curl -v -X PUT \
     -H "X-Auth-Token: {AUTH_TOKEN}" \
     -d '{"data": {"blip": 432}}' \
     http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/port
{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880371131,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880371131,
        "carrier_module": "local"
    },
    "data": {
        "blip": 432,
        "id": "{PHONE_NUMBER}",
        "features": [
            "local"
        ],
        "state": "port_in"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Move a number to the reserved state

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/reserve

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/reserve

Success Response

{
  "auth_token": "{AUTH_TOKEN}",
    "metadata": {
        "modified": 63880369479,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880145085,
        "carrier_module": "local"
    },
    "data": {
        "ui_metadata": {
            "version": "5.2-3",
            "ui": "monster-ui",
            "origin": "common"
        },
        "id": "{PHONE_NUMBER}",
        "features": [
            "local"
        ],
        "state": "reserved"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Number already in reserved state

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "code": 400,
        "error": "no_change_required",
        "message": "no change required"
    },
    "error": "400",
    "message": "no_change_required",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Number does not exist

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "message": "bad identifier",
        "not_found": "The number could not be found"
    },
    "error": "404",
    "message": "bad_identifier",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Buy a number once searched for

Note: one is not charged if number is already in service.

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/activate

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}/activate

Success

{
  "auth_token": "{AUTH_TOKEN}",
  "metadata": {
        "modified": 63880482878,
        "id": "{PHONE_NUMBER}",
        "features": {
            "settings": {},
            "available": [
                "carrier_name",
                "force_outbound",
                "prepend",
                "ringback"
            ]
        },
        "created": 63880482866,
        "carrier_module": "local"
    },
    "data": {
        "id": "{PHONE_NUMBER}",
        "features": [
            "local"
        ],
        "state": "in_service"
    },
  "request_id": "{REQUEST_ID}",
  "revision": "{REVISION}",
  "status": "success"
}

Number was not returned in previous search results or other error

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "code": 500,
        "error": "unspecified_fault",
        "message": "missing_provider_url"
    },
    "error": "500",
    "message": "unspecified_fault",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Carrier fault

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "cause": "{PHONE_NUMBER}",
        "code": 500,
        "error": "unspecified_fault",
        "message": "fault by carrier"
    },
    "error": "500",
    "message": "unspecified_fault",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

Classify a number

GET /v2/accounts/{ACCOUNT_ID}/phone_numbers/classifiers/{PHONE_NUMBER}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/classifiers/{PHONE_NUMBER}
{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": "{META_DATA}",
    "data": {
        "e164": "+1{PHONE_NUMBER}",
        "friendly_name": "US DID",
        "name": "did_us",
        "number": "{PHONE_NUMBER}",
        "pretty_print": "SS(###) ###-####",
        "regex": "^\\+?1?([2-9][0-9]{2}[2-9][0-9]{6})$"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Buy a list of numbers

Note: numbers must have appeared as part of the results of a numbers search.

PUT /v2/accounts/{ACCOUNT_ID}/phone_numbers/collection/activate

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}"]}}' \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection/activate

Success Response

{
    "auth_token": "{AUTH_TOKEN}",
    "metadata": {},
    "data": {
        "success": {
            "+14167775544": {
                "id": "{PHONE_NUMBER1}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880498842,
                    "id": "{PHONE_NUMBER1}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880498566,
                    "carrier_module": "local"
                }
            },
            "+14167775555": {
                "id": "{PHONE_NUMBER2}",
                "features": [
                    "local"
                ],
                "state": "in_service",
                "_read_only": {
                    "modified": 63880498842,
                    "id": "{PHONE_NUMBER2}",
                    "features": {
                        "settings": {},
                        "available": [
                            "carrier_name",
                            "force_outbound",
                            "prepend",
                            "ringback"
                        ]
                    },
                    "created": 63880498566,
                    "carrier_module": "local"
                }
            }
        },
        "error": []
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Number not found or other error

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "{PHONE_NUMBER2}": {
            "code": 500,
            "error": "unspecified_fault",
            "message": "missing_provider_url"
        }
    },
    "error": "400",
    "message": "client error",
    "request_id": "{REQUEST_ID}",
    "status": "error"
}

E911

Add an emergency address to a phone number (and enable the e911 feature).

POST /v2/accounts/{ACCOUNT_ID}/phone_numbers/{NUMBER}

With a sample payload like below:

{
    "data": {
        "used_by": "callflow",
        "id": "{NUMBER}",
        "e911": {
            "caller_name": "{NAME}",
            "postal_code": "{ZIP_CODE}",
            "street_address": "{ADDRESS}",
            "extended_address": "{EXTENDED}",
            "locality": "{CITY}",
            "region": "{STATE}"
        }
    }
}
curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{_ABOVE_SAMPLE_}' \
    'http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/phone_numbers/{NUMBER}'

Responses

Invalid address

{
    "data": {
        "address": {
            "invalid": {
                "cause": {
                    "caller_name": "{NAME}",
                    "postal_code": "{ZIP_CODE}",
                    "street_address": "{ADDRESS}",
                    "extended_address": "{EXTENDED}",
                    "locality": "{CITY}",
                    "region": "{STATE}"
                },
                "message": "Location is not geocoded"
            }
        }
    },
    "error": "400",
    "message": "invalid data",
    "status": "error"
}

Multiple choice

{
    "data": {
        "multiple_choice": {
            "e911": {
                "cause": {
                    "postal_code": "{ZIP_CODE}",
                    "street_address": "{ADDRESS}",
                    "extended_address": "{EXTENDED}",
                    "locality": "{CITY}",
                    "region": "{STATE}"
                },
                "details": [{
                    "postal_code": "{ZIP_CODE}",
                    "street_address": "{ADDRESS}",
                    "extended_address": "{EXTENDED}",
                    "locality": "{CITY}",
                    "region": "{STATE}"
                }, {
                    "postal_code": "{ZIP_CODE}",
                    "street_address": "{ADDRESS}",
                    "extended_address": "{EXTENDED}",
                    "locality": "{CITY}",
                    "region": "{STATE}"
                }],
                "message": "more than one address found"
            }
        }
    },
    "error": "400",
    "message": "multiple_choice",
    "status": "error"
}

Success

{
    "data": {
        "used_by": "callflow",
        "id": "{NUMBER}",
        "e911": {
            "street_address": "116 NATOMA ST",
            "extended_address": "APT 116",
            "caller_name": "Michel Mabel",
            "locality": "SAN FRANCISCO",
            "latitude": "37.786861",
            "longitude": "-122.399484",
            "location_id": "27578725",
            "plus_four": "3745",
            "postal_code": "94105",
            "region": "CA",
            "status": "PROVISIONED",
            "legacy_data": {
                "house_number": "116",
                "streetname": "NATOMA ST",
                "suite": "APT 116"
            }
        }
    },
    "status": "success"
}

On this page