The Middleware API enables PBXware to validate, provision, update, and delete emergency dispatchable locations using third-party providers (e.g., Bandwidth). This document defines the HTTP endpoints that must be implemented by the external middleware, including required request/response formats and expected status codes. The base URL that PBXware uses to send requests to the middleware is configured through PBXware's GUI, along with an API key that can be used for authentication.
Authentication is optional from the perspective of PBXware. If no API key is specified in PBXware, the requests to the middleware will be sent without it. An API key can be configured in the PBXware GUI and will be sent as a Bearer token in the Authorization header in requests to the middleware:
Authorization: Bearer <api_key>
It is the responsibility of the middleware to determine how to handle and validate the API key, since PBXware does not enforce authentication.
The address object represents a dispatchable location and uses the structure defined in the table below. All fields are treated as strings, regardless of numeric or alphanumeric formatting (supports ZIP+4 codes, alphanumeric house numbers, etc.). When used in requests or responses, the address object must include all required fields. Optional fields may be included as needed.
NOTE: The floor and room fields are sent in requests to the middleware as additional information. However, if the response contains adjusted values for these fields, they will not be processed or applied by PBXware, unlike the other address fields.
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| state | string | Yes | State name |
| city | string | Yes | City name |
| house_number | string | Yes | House or building number |
| street_name | string | Yes | Name of the street |
| street_suffix | string | No | Street type or suffix (e.g., Avenue, Blvd) |
| predirectional | string | No | Street pre-direction (e.g., N, S, NE, SW) |
| postdirectional | string | No | Street post-direction (e.g., N, S, NE, SW) |
| zip5 | string | Yes | 5-digit ZIP code |
| zip4 | string | No | Optional 4-digit ZIP code |
| address_line_2 | object | No | Optional second line for address details |
| address_line_2.floor | string | No | Floor number |
| address_line_2.room | string | No | Room name or number |
Example Address Object
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
Validate and provision a new dispatchable location.
To validate an address and provision it with a provider, PBXware will send an HTTP POST request to the /addresses endpoint with a json body containing the necessary address data. The request will include the tenant code of the tenant where the dispatchable location is created, as well as a unique ID for the dispatchable location.
POST /addresses
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| tcode | int | Yes | For Multi Tenant PBXware, the tenant code of the tenant where the dispatchable location is created. For other editions, use 1. |
| id | string | Yes | Unique ID of the Dispatchable Location. Used for editing and deleting the location. |
| address | object | Yes | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example request body
{
"tcode": 200,
"id": "20053",
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
Middleware received a response from the provider confirming successful address provisioning on their side. The provider may send back adjusted address fields, so the middleware must always return all address fields from the provider's response exactly as received, without modification or omission. If an address field was present in the request to the middleware but is omitted in the provider's response, the middleware must include that field in its response and set its value to an empty string. The response from the middleware must also include the value to be used in the SIP Geolocation header (e.g., Bandwidth Geolocation URL, might be something else for other providers).
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| geolocation_reference | string | The value to be used in the SIP geolocation header (e.g., Bandwidth Geolocation URL). |
| address | object | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example response body
{
"geolocation_reference": "https://emergency.bandwidth.com/locations/{account_number}/{location_id}",
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
Middleware failed to process the request or has received a response from the provider stating that the address is invalid and could not be validated or provisioned. The response from the middleware must contain the error message received from the provider or generated in the middleware itself.
NOTE: The error string can be max. 255 characters long.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| error | string | Error message received from the provider or generated in the middleware. |
Example response body
{
"error": "This address could not be validated.",
}
The API key in the request to the middleware is missing or invalid. This response does not have a body.
Middleware received a response from the provider indicating that the address could not be validated, but containing details on what needs to be changed in order for the address to be successfully provisioned. The response from the middleware must contain the error message received from the provider, along with all address fields from the provider's response exactly as received, without modification or omission. If an address field was present in the request to the middleware but is omitted in the provider's response, the middleware must include that field in its response and set its value to an empty string.
NOTE: The error string can be max. 255 characters long.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| error | string | Error message received from the provider. |
| address | object | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example response body
{
"error": "Some adjustments are required to allow the address to pass geocoding.",
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
When an address has already been provisioned with a provider, but it has since been edited and needs to be validated again and updated on the provider's side, PBXware will send an HTTP PUT request to the /addresses/{id} endpoint. The id is the id value sent in the original POST request for the same address.
PUT /addresses/{id}
Content-Type: application/json
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| address | object | Yes | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example request body
{
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
Middleware received a response from the provider confirming successful address provisioning on their side. The provider may send back adjusted address fields, so the middleware must always return all address fields from the provider's response exactly as received, without modification or omission. If an address field was present in the request to the middleware but is omitted in the provider's response, the middleware must include that field in its response and set its value to an empty string. The response from the middleware must also include the value to be used in the SIP Geolocation header (e.g., Bandwidth Geolocation URL, might be something else for other providers).
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| geolocation_reference | string | The value to be used in the SIP geolocation header (e.g., Bandwidth Geolocation URL). |
| address | object | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example response body
{
"geolocation_reference": "https://emergency.bandwidth.com/locations/{account_number}/{location_id}",
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
Middleware failed to process the request or has received a response from the provider stating that the address is invalid and could not be validated or provisioned. The response from the middleware must contain the error message received from the provider or generated in the middleware itself.
NOTE: The error string can be max. 255 characters long.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| error | string | Error message received from the provider or generated in the middleware. |
Example response body
{
"error": "This address could not be validated.",
}
The API key in the request to the middleware is missing or invalid. This response does not have a body.
An address with the specified id does not exist. This response does not have a body.
Middleware received a response from the provider indicating that the address could not be validated, but containing details on what needs to be changed in order for the address to be successfully provisioned. The response from the middleware must contain the error message received from the provider, along with all address fields from the provider's response exactly as received, without modification or omission. If an address field was present in the request to the middleware but is omitted in the provider's response, the middleware must include that field in its response and set its value to an empty string.
NOTE: The error string can be max. 255 characters long.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| error | string | Error message received from the provider. |
| address | object | Address object representing the dispatchable location. See Address Object Structure for field details. |
Example response body
{
"error": "Some adjustments are required to allow the address to pass geocoding.",
"address":
{
"state": "NY",
"city": "NEW YORK",
"house_number": "33",
"street_name": "3RD",
"street_suffix": "AVE",
"predirectional": "",
"postdirectional": "",
"zip5": "10003",
"zip4": "5525",
"address_line_2":
{
"floor": "5",
"room": "17"
}
}
}
In order to delete an address on the provider's side, PBXware will send an HTTP DELETE request to the /addresses/{id} endpoint. The id is the id value sent in the original POST request for the same address.
DELETE /addresses/{id}
The address with the specified id has successfully been deleted. This response does not have a body.
The API key in the request to the middleware is missing or invalid. This response does not have a body.
An address with the specified id does not exist. This response does not have a body.
Middleware has received a response from the provider stating that the address could not be deleted (e.g. because it is in use). The response from the middleware must contain the error message received from the provider.
NOTE: The error string can be max. 255 characters long.
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| error | string | Error message received from the provider. |
Example response body
{
"error": "Address could not be deleted.",
}