Create Addresses
Multiple services require users to provide an address, so we've created a centralized address management service to reduce complexity and redundancy. Users can now create an address once and reuse the address across porting, requirements packages, emergency services, sub-account management, etc.
This guide will outline how to:
- Get address fields by country
- Pre-validate an address
- Create an address
- Manage addresses
Get Address Fields by Country
Example
Request
GET https://dashboard.bandwidth.com/api/v2/addresses/fields/ITA
Authorization: Bearer mySecretToken
Response
{
"links": [
{
"href": "https://api.bandwidth.com/api/v2/addresses",
"rel": "create-address",
"method": "POST"
}
],
"data": {
"addressFields": [
{
"fieldName": "customReference",
"type": "String",
"maxLength": 1000,
"required": false,
"changeable": true
},
{
"fieldName": "countryCodeA3",
"type": "String",
"maxLength": 3,
"required": true,
"changeable": false
},
{
"fieldName": "addressLine1",
"type": "String",
"maxLength": 1000,
"required": true,
"changeable": false
},
{
"fieldName": "addressLine2",
"type": "String",
"maxLength": 1000,
"required": false,
"changeable": false
},
{
"fieldName": "municipality",
"type": "String",
"usedBy": [
{
"feature": "EMERGENCY",
"required": true
}
],
"maxLength": 256,
"required": false,
"changeable": false
},
{
"fieldName": "district",
"type": "String",
"usedBy": [
{
"feature": "EMERGENCY",
"required": true
}
],
"maxLength": 128,
"required": false,
"changeable": false
},
{
"fieldName": "city",
"type": "String",
"maxLength": 128,
"required": true,
"changeable": false
},
{
"fieldName": "province",
"type": "String",
"usedBy": [
{
"feature": "EMERGENCY",
"required": true
}
],
"maxLength": 256,
"required": false,
"changeable": false
},
{
"fieldName": "county",
"type": "String",
"maxLength": 256,
"required": true,
"changeable": false
},
{
"fieldName": "postalCode",
"type": "String",
"maxLength": 128,
"required": true,
"changeable": false
}
]
},
"errors": []
}
If you are creating an address for a requirements package and the country has local address requirements, check the GET /cityInfo API and use only postal codes specified for the country.
Example
Request
GET https://dashboard.bandwidth.com/api/v2/addresses/ITA/cityInfo
Authorization: Bearer mySecretToken
Response
{
"data": [
[
{
"city": "Aalen",
"postalCode": "73430"
},
{
"city": "Aalen",
"postalCode": "73431"
},
{
"city": "Aalen",
"postalCode": "73433"
},
{
"city": "Aalen",
"postalCode": "73434"
},
{
"city": "Aalen",
"postalCode": "73460"
}
]
],
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/addresses/{countryCodeA3}/cityInfo",
"method": "GET",
"rel": "self"
}
]
}
Pre-Validate an Address
Before creating the address, validate that you meet the pre-requisites for the country and use cases you intend to use the address.
Geo-validation is coming soon. View the API reference for more details.
Note: the validator is intended to guide users to successfully create addresses, but it does not guarantee that the address is valid/accurate for a particular service.
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/addresses/validator
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"customReference": "home_office",
"postalCode": "00042",
"county": "Roma"
}
Response
{
"data": {
"address": {
"addressId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"createdDateTime": "2024-03-11T04:09:25.399Z",
"customReference": "home_office",
"postalCode": "00042",
"county": "Roma",
"updatedDateTime": "2024-03-11T04:09:25.399Z"
},
"unsupportedFeatures": [
{
"addressCriteria": [
{
"description": "missing fields: municipality, district, province"
}
],
"featureName": "EMERGENCY"
}
]
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/addresses/validator",
"method": "POST",
"rel": "self"
}
]
}
Create an Address
Create an address with the same request you used for the validator.
Address creation will only require that the basic required fields are provided to allow for overrides.
Provide a customReference to easily find your address and reuse it in the future.
See the API reference for more details.
Example
Request
POST https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/addresses
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"customReference": "home_office",
"postalCode": "00042",
"county": "Roma"
}
Response
{
"data": {
"address": {
"addressId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"createdDateTime": "2024-03-11T04:09:25.399Z",
"customReference": "home_office",
"postalCode": "00042",
"county": "Roma",
"updatedDateTime": "2024-03-11T04:09:25.399Z"
}
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/addresses",
"method": "POST",
"rel": "self"
}
]
}
Manage Addresses
You can search addresses by customReference, countryCodeA3, city, and postalCode. 10 results will be returned by default, but the limit can be increased to 100. For more details on viewing addresses check out the API reference.
Addresses can be used across multiple services by specifying the addressId as required by each service. customReference can be changed at anytime for an easier search experience, and the ability to update additional address fields is coming soon.
Any fields marked as changeable in the /fields endpoint as referenced above can be updated. Address deletion coming soon. For more details on updating an address view the API reference.
Example
Request
PATCH https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/addresses/{addressId}
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"customReference": "ITA office"
}
Response
{
"data": {
"address": {
"addressId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"createdDateTime": "2024-03-11T04:09:25.399Z",
"customReference": "ITA office",
"postalCode": "00042",
"county": "Roma",
"updatedDateTime": "2024-03-11T04:09:25.399Z"
}
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/addresses",
"method": "PATCH",
"rel": "self"
}
]
}