Phone Number API

Introduction

With OneUC’s Phone Number Lookup API, you can quickly and easily manage U.S. and Canadian-based phone numbers to better target how you connect with and send communications to your customers.

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!

Schema

Schema for a number

Key	Description	Type	Default	Required
`carrier_name`		`string(1..30)`		`false`
`cnam.display_name`		`string(1..15)`		`false`
`cnam.inbound_lookup`		`boolean()`		`false`
`cnam`		`object()`		`false`
`create_with_state`	The state to create numbers in	`string('aging' \| 'available' \| 'deleted' \| 'discovery' \| 'in_service' \| 'port_in' \| 'port_out' \| 'released' \| 'reserved')`		`false`
`e911.activated_time`	The time stamp e911 was provisioned	`string()`		`false`
`e911.caller_name`	The name that will show to emergency services	`string(3..)`		`false`
`e911.extended_address`	The suit/floor/apt. address where the number is in service	`string()`		`false`
`e911.latitude`	The e911 provisioning system calculated service address latitude	`string()`		`false`
`e911.legacy_data.house_number`	The name that will show to emergency services	`string()`		`false`
`e911.legacy_data.predirectional`	The name that will show to emergency services	`string()`		`false`
`e911.legacy_data.streetname`	The name that will show to emergency services	`string()`		`false`
`e911.legacy_data.suite`	The name that will show to emergency services	`string()`		`false`
`e911.legacy_data`	Legacy E911 information	`object()`		`false`
`e911.locality`	The locality (city) where the number is in service	`string()`		`true`
`e911.location_id`	The e911 provisioning system internal id for this service address	`string()`		`false`
`e911.longitude`	The e911 provisioning system calculated service address longitude	`string()`		`false`
`e911.notification_contact_emails.[]`		`string()`		`false`
`e911.notification_contact_emails`	A list of email addresses to receive notification when this number places an emergency call	`array(string())`	`[]`	`false`
`e911.plus_four`	The extended zip/postal code where the number is in service	`string()`		`false`
`e911.postal_code`	The zip/postal code where the number is in service	`string()`		`true`
`e911.region`	The region (state) where the number is in service	`string(2)`		`true`
`e911.status`	The e911 provisioning system status for this service address	`string('INVALID' \| 'GEOCODED' \| 'PROVISIONED' \| 'REMOVED' \| 'ERROR')`		`false`
`e911.street_address`	The street address where the number is in service	`string()`		`true`
`e911`		`object()`		`false`
`porting.billing_account_id`	The account id the losing carrier has on file	`string()`		`false`
`porting.billing_extended_address`	The suit/floor/apt. address the losing carrier has on file	`string()`		`false`
`porting.billing_locality`	The locality (city) the losing carrier has on file	`string()`		`false`
`porting.billing_name`	The name or company name the losing carrier has on file	`string()`		`false`
`porting.billing_postal_code`	The zip/postal code the losing carrier has on file	`string()`		`false`
`porting.billing_region`	The region (state) the losing carrier has on file	`string()`		`false`
`porting.billing_street_address`	The street address the losing carrier has on file	`string()`		`false`
`porting.billing_telephone_number`	The BTN of the account the number belongs to	`string()`		`false`
`porting.comments.[]`		`string()`		`false`
`porting.comments`	An array of comments	`array(string())`		`false`
`porting.customer_contact`	The phone number that can be used to contact the owner of the number	`string()`		`false`
`porting.port_id`	The id of the port request	`string()`		`false`
`porting.requested_port_date`	The requested port date	`string()`		`false`
`porting.service_provider`	The name of the losing carrier	`string()`		`false`
`porting`	Porting (in) information for the phone number	`object()`		`false`

Search For Available Numbers

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

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)

Example

curl -v -X GET \
    https://api.oneuc.com/v2/phone_numbers?prefix=415&quantity=2

Response

{
    "auth_token": "",
    "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"
}

Buy a number once searched for

This is how you can purchase a number you have just searched for

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

Example

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

Response

There are a number of different responses that will be provided depending on the outcome on the number purchase and activation action

Successful

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "_read_only": {
            "created":  63628027112 ,
            "modified":  63628027112 ,
            "state": "in_service"
        },
        "id": "{PHONE_NUMBER}",
        "state": "in_service"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Errors

The following are different errors that may be returned depending on the outcome of the purchase and activation process.

The 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 or Network provisioning/activation 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"
}

Buy a Collection (List) of numbers

This endpoint allows you to purchase and activate more than one number at a time

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

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

Example

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data":{"numbers": ["{PHONE_NUMBER1}", "{PHONE_NUMBER2}"]}}' \
    https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers/collection/activate

Success Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "success": {
            "{PHONE_NUMBER1}": {
                "_read_only": {
                    "created":  63628542222 ,
                    "modified":  63628542222 ,
                    "state": "in_service"
                },
                "id": "{PHONE_NUMBER1}",
                "state": "in_service"
            },
            "{PHONE_NUMBER2}": {
                "_read_only": {
                    "created":  63628542222 ,
                    "modified":  63628542222 ,
                    "state": "in_service"
                },
                "id": "{PHONE_NUMBER2}",
                "state": "in_service"
            }
        }
    },
    "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"
}

Search for available numbers you own

Here you can search for numbers that are already provisioned to your account

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}

Example

curl -v -X GET \
    https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers?prefix=555&quantity=3&offset=6

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "number": "+15552225562",
            "state": "available"
        },
        {
            "number": "+15554445558",
            "state": "discovery"
        },
        {
            "number": "+15552225562",
            "state": "available"
        }
    ],
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

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

Example

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers?page_size=3&start_key=%2B14152338421

Response

"auth_token": "{AUTH_TOKEN}",
    "data": {
        "cascade_quantity": 0,
        "numbers": {
            "+14152338421": {
                "assigned_to": "{ACCOUNT_ID}",
                "created":  63628550806 ,
                "features": [],
                "state": "in_service",
                "updated":  63628550806 
            },
            "+14155234712": {
                "assigned_to": "{ACCOUNT_ID}",
                "created":  63636963275 ,
                "features": [
                    "local"
                ],
                "state": "in_service",
                "updated":  63636963275 
            },
            "+14155558920": {
                "assigned_to": "{ACCOUNT_ID}",
                "created":  63633211146 ,
                "features": [
                    "local"
                ],
                "state": "reserved",
                "updated":  63633211146 
            }
        }
    },
    "next_start_key": "+14155558921",
    "page_size": 3,
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "start_key": "+14152338421",
    "status": "success"
}

Removing Numbers from an Account

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

Example

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

Response

Successful

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "_read_only": {
            "created":  63627848588 ,
            "modified":  63627848588 ,
            "state": "available"
        },
        "id": "{PHONE_NUMBER}",
        "state": "available"
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Number not on Account

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

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}

Example

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers/{PHONE_NUMBER}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "_read_only": {
            "created":  63627848989 ,
            "features": [
                "local"
            ],
            "modified":  63627848989 ,
            "state": "reserved"
        },
        "features": [
            "local"
        ],
        "id": "{PHONE_NUMBER}",
        "state": "reserved",
        "my_own_field": {}
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

E911

This allows you to activate E911 on a number.

Note
e911 services are only offered in the US and Canada at the current moment. International emergency services such as 112 can be provided but need to be registered manually. Please contact support for assistance and to see if we provide international emergency services in your area.

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

With a sample payload like below:

Example

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    'https://api.oneuc.com/v2/accounts/{ACCOUNT_ID}/phone_numbers/{NUMBER}'

Body

{
    "data": {
        "used_by": "callflow",
        "id": "{NUMBER}",
        "e911": {
            "caller_name": "{NAME}",
            "postal_code": "{ZIP_CODE}",
            "street_address": "{ADDRESS}",
            "extended_address": "{EXTENDED}",
            "locality": "{CITY}",
            "region": "{STATE}"
        }
    }
}

Note
Please see the Schema at the beginning of this article for details on the e911 keys

Responses

There are a number of responses depending on the outcome of the e911 provisioning request

Successful

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

Multiple choice

OneUC employs advanced address verification and matching algorithms to automatically match and adjust the address provided to the one which matches the location identification in the Master Streets Database which use used by e911 Public Safety Centers to accurately provide location information to emergency services.

From time to time an address may not be matched by the algorithm. In the event that should happen, we will provide multiple choices for review.

At this point, the correct address needs to be selected, and the body of your submission needs to be adjusted to match the address that has been selected from this list.

Response

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

Invalid address

If this is returned, then the address provided is not valid or could not be found in the master streets database. You will need to check the address and resubmit the request.

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

Updated on February 15, 2023

Was this article helpful?

Yes No