Unified Emergency Services Provisioning API
This integration guide describes how to provision emergency services data using the Unified Emergency Services Provisioning API.
The Unified Emergency Services Provisioning API supports a singular, global customer experience, and enables the ability to provision and manage endpoints records and addresses via a single API.
Authentication
The authentication basis for the Unified Emergency Services Provisioning API is either Basic (username/password) or Bearer Authentication (via token).
Region
You will see a region designation for GET and POST commands.
The region designation “ROW” (for non-North American countries) is used in the underlying provisioning processes to accommodate variations in the service and must be included.
The designation has the format:
region
string (region)
Enum: "ROW"
Example: region=ROW
Important: The region designation is required even if the underlying POST contains context information that would otherwise identify the region. For example, when adding an address for the United Kingdom, both the region designation of “ROW” and the country designation of “GBR” are required.
Addresses
Central to Bandwidth emergency services is the entry and validation of emergency response location (also known as “address”) data.
Generally, address provisioning and validation occurs first when configuring emergency services.
Address validation is a synchronous process which will return a unique address ID upon successful validation.
The address ID can be used in subsequent API requests, so it is important that your application maintains the full set of returned address IDs for future use (such as linking an address ID to an endpoint).
Full descriptions of address management commands can be found here: ADDRESSES
Create an Address
POST Add Address (civic address) to create and validate the supplied address.
Your code should retain the address ID returned in the response for use in the next step.
The SUCCESS case means that the address is a valid address and can be successfully used for future emergency calls.
POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/addresses?region=ROW
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/addresses?region=ROW
Authorization: Basic abcdefghijklmnopqrs=
Content-Type: application/json
{
"addressLine1": "51 Main Street",
"cityOrLocality": "London",
"postCode": "EC1Y 8SY",
"countryCodeA3": "GBR"
}
Endpoints
An endpoint record (also known as “endpoint”) is more than just a phone number.
An endpoint record is a collection of data fields that together comprise the needed caller information for an emergency call.
When setting up endpoint records, addresses are assumed to be used in future emergency calls.
Endpoint management is an asynchronous process which will return an order ID.
It is important that your application maintains the full set of returned order IDs to check the resulting status of your transactions.
When examining your order results, the individual endpoint transactions will return with the results of SUCCESS, IN_PROGRESS, or ERROR.
Full descriptions of endpoint management commands can be found here: ENDPOINTS
Create an Endpoint
POST Add Endpoints (phone number, address ID) to create an endpoint record for your phone number and assign the address to by including the previously retained address ID.
Your code should retain the order ID returned in the response for use in the next step.
POSThttps://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/endpoints?region=ROW
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/endpoints?region=ROW
Authorization: Basic abcdefghijklmnopqrs=
Content-Type: application/json
{
"endpoints": [
{
"phoneNumber": "+44798080101",
"callerName": "John Doe",
"lang": "en",
"country": "GBR",
"addressId": "e454ac5a-8c2c-45b0-8c7d-e6dd0b1a3582"
}
]
}
Orders
For every API POST, an order ID is returned.
It is important to store this returned order ID for future reference in checking your order details.
Order commands have the ability to return all orders on an account and all details on a specific order, including order type, user, status, and history of all changes (who and what).
The three functions in order-management are List Orders, Get Order History and Get Order Details.
GET Order Details
GET Order Details (order ID) to check the order and determine when it is COMPLETED (as opposed to PENDING or FAILED).
GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/orders/{orderId}/details
Response
GET https://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/orders/{orderId}/details
Authorization: Basic abcdefghijklmnopqrs=
Content-Type: application/json
{
"links": [
{
"href": "/orders/uUbvouVW/details",
"rel": "self",
"method": "GET"
}
],
"id": "uUbvouVW",
"type": "ADD_ENDPOINTS",
"status": "CREATED",
"acceptedCount": 1,
"invalidCount": 0,
"updated": "2023-11-27T20:14:20Z",
"totalNumber": 1,
"endpoints": [
{
"id": "+31798080101",
"updatedBy": "myUser",
"status": "SUCCESS",
"error": "",
"errorCode": ""
}
]
}
GET Order History
GET Order History (order ID) to check the order and determine when it progresses through each stage of the provisioning process.
GEThttps://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/orders/{orderId}/history?region=ROW
Response
GET https://api.bandwidth.com/api/v2/accounts/{accountId}/emergency/orders/{orderId}/history?region=ROW
Authorization: Basic abcdefghijklmnopqrs=
Content-Type: application/json
{
"id": "kj8WzoJQ",
"type": "ADD_ENDPOINTS",
"status": "COMPLETED",
"created": "2023-09-07T17:34:27Z",
"orderHistory": [
{
"status": "RECEIVED",
"updatedBy": "myUser",
"updated": "2023-09-07T17:34:27Z",
"note": ""
},
{
"status": "PROCESSING",
"updatedBy": "myUser",
"updated": "2023-09-07T17:34:27Z",
"note": ""
},
{
"status": "COMPLETED",
"updatedBy": "myUser",
"updated": "2023-09-07T17:34:30Z",
"note": ""
}
]
}