Create a Requirements Package
Many national telecom regulators require that the end user of a phone number is verified, typically with proof of ID and/or proof of address, before services on the number can be activated. In some cases, Bandwidth is required to submit daily and monthly end user data reports to regulators, and must follow each country's guidelines for storing or deleting the data. Not sending this data, or incorrectly managing collected Personally Identifiable Information (PII), can result in $millions in fines and/or loss of operating license in the country.
End user validation requirements vary by country, phone number type, and end user type, which causes a lot of confusion. We've introduced a tool to reduce the complexity for customers and make it as easy as possible to remain compliant, as well as to automate internal data management, by informing users of all requirements for a particular use case up front and “packaging” all end user information in a Requirements Package.
This guide will provide an overview of how to:
- View Account Requirements
- Create a Requirements Package
- Create an End User, Address, and Documents
- Attach Assets
- Submit a Requirements Package
- Approval Process
- Edit
- Manage Requirements Packages
- Attach Phone Numbers
Get Requirements
Your account requirements will inform you of the information that is required to validate an end-user for a given country, number type and end-user type. These requirements may change periodically, so for the best experience, check requirements each time you create a new package. For more details, view the reference here.
Example
Request
GET https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirements?countryCodeA3%5Beq%5D=ITA
Authorization: Bearer mySecretToken
Response
{
"data": [
{
"countryCodeA3": "ITA",
"endUserType": "BUSINESS",
"phoneNumberType": "GEOGRAPHIC",
"requirement": {
"address": {
"location": "NATIONAL"
},
"endUser": {
"fields": [
{
"fieldName": "salutation",
"friendlyName": "Salutation",
"maxLength": 10,
"required": true,
"type": "String",
"values": ["Mr.", "Mrs."]
}
],
"type": "BUSINESS"
},
"supportingDocuments": [
{
"acceptedDocuments": [
{
"fields": [
{
"fieldName": "companyName",
"friendlyName": "Company Name",
"maxLength": 500,
"type": "String"
},
{
"fieldName": "issueDate",
"friendlyName": "Issue Date",
"type": "Date"
}
],
"friendlyName": "Business registration",
"type": "businessRegistration"
}
],
"description": "The business registration document",
"name": "Business registration",
"type": "ADDRESS"
}
]
}
}
],
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirements",
"rel": "self",
"type": "GET"
}
]
}
Create a Requirements Package
The requirements package will package together the “assets” required for end-user validation. First, create a package and then create and attach the required “assets”.
View the API reference for more details.
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"acknowledgements": {
"allDetailsAccurate": true
},
"callback": "http://somehost.com/new-callback",
"countryCodeA3": "ITA",
"customReference": "home_office",
"email": "foo@bar.com",
"endUserType": "BUSINESS",
"phoneNumberType": "GEOGRAPHIC"
}
Response
204 No Content
Create Assets
Create an End User
Create an end-user with all required fields. If you already have an end-user you would like to reuse, skip this step and attach the existing end-user.
To view all acceptable end-user fields, call GET /endUserTypes. For more information about creating and end-user, view the reference here.
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/endUsers
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"customReference": "Custom reference",
"fields": {
"businessName": "Bandwidth",
“businessDescription”: “My favorite communications provider”
},
"type": "BUSINESS"
}
Response
{
"data": {
"createdDateTime": "2024-09-09T04:09:25.399Z",
"customReference": "Custom reference",
"endUserId": "dcb9dd0f-de97-4103-8530-b31bf4be8fc0",
"fields": {
"businessName": "Bandwidth",
"businessDescription": "My favorite communications provider"
},
"status": "DRAFT",
"type": "BUSINESS",
"updatedDateTime": "2024-09-09T04:09:25.399Z"
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/endUsers/{endUserId}",
"rel": "get-endUser",
"type": "GET"
}
]
}
You can also update an existing end-user while the status is in “DRAFT”. The end-user status will change with the status of the requirements package.
View the API reference for more details.
PATCH https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/endUsers/{endUserId}
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"customReference": "New custom reference",
"fields": {
"companyVat": "AB123456",
"authorizedRepresentativeFirstName": "Jane",
"authorizedRepresentativeLastName": “Doe”,
"dateOfBirth": "1992-11-23"
}
}
Create an Address
Create an address with all required fields. More detailed information on creating an address can be found here.
If the address requirement is local, check get /cityInfo and use only postal codes provided in the response for the country.
Example
Request
GET https://api.bandwidth.com/api/v2/addresses/{countryCodeA3}/cityInfo
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://dashboard.bandwidth.com/api/v2/addresses/{countryCodeA3}/cityInfo",
"method": "GET",
"rel": "self"
}
]
}
Create Documents
You may only attach a documentId to one RP at this time. To view all acceptable document types and fields, call GET /documentTypes.
Documents will be automatically deleted once verified in countries where required. At this point, fileContentsExists will be set to false.
For more information about creating documents, view the reference here.
Example
Request
Response
{
"data": {
"createdDateTime": "2024-09-11T04:09:25.399Z",
"documentId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
"fileContentExists": true,
"fileName": "Untitled.png",
"status": "SUBMITTED",
"updatedDateTime": "2024-03-11T04:09:25.399Z",
"customReference": "home_office",
"description": "Trade License",
"fields": {
"firstName": "First Name",
"issueDate": "2020-11-23"
},
"type": "tradeLicense"
},
"errors": [],
"links": [
{
"href": "https://dashboard.bandwidth.com/api/v2/accounts/{accountId}/compliance/documents/{documentId}",
"rel": "get-document",
"type": "GET"
}
]
}
Attach Assets
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/{requirementsPackageId}/assets
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"assetReferenceId": "05ee3231-ad80-4fc5-9c13-68ffc26846a5",
"assetType": "ADDRESS"
}
Response
{
"data": {
"assetId": "93ac73e8-20a7-95ec-bd32-4e8270e66c31",
"assetReferenceData": {
"addressId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
"addressLine1": "14111 NE 145th St",
"addressLine2": "Apt. 8",
"city": "Roma",
"countryCodeA3": "ITA",
"createdDateTime": "2024-09-10T04:09:25.399Z",
"customReference": "home_office",
"postalCode": "00042",
"updatedDateTime": "2024-09-10T04:09:25.399Z"
},
"assetReferenceId": "05ee3231-ad80-4fc5-9c13-68ffc26846a5",
"assetType": "ADDRESS",
"createdDateTime": "2024-09-10T04:09:25.399Z",
"updatedDateTime": "2024-09-10T04:09:25.399Z"
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/1/requirementsPackages/46bd4a91-582d-442f-bd1b-bcf17ca7fc6a/assets",
"rel": "self",
"type": "GET"
}
]
}
Submit and Manage
Submit
At this point, your package is in a DRAFT status. To submit a requirements package, send a PATCH request with the status set to SUBMITTED.
When updating the status of the package, you are required to also set allDetailsAccurate to true, confirming that the end-user information is accurate to the best of your knowledge.
Specify or change the callback and/or email to receive notifications when the status changes. The ability to subscribe to receive notifications for all requirements packages and designate specific states is coming soon.
Example
Request
PATCH https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/{requirementsPackageId}
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"customReference": "home_office",
"email": "foo@bar.com",
"status": "SUBMITTED",
"Acknowledgements": {
"allDetailsAccurate": true
}
}
Response
{
"data": {
"acknowledgements": {
"allDetailsAccurate": true
},
"callback": "http://myServer.com/bandwidth/callbacks",
"countryCodeA3": "ITA",
"createdDateTime": "2024-09-10T04:09:25.399Z",
"customReference": "home_office",
"email": "foo@bar.com",
"endUserType": "BUSINESS",
"phoneNumberType": "GEOGRAPHIC",
"remarks": "Remarks provided by Admin",
"requirementsPackageId": "93ac73e8-20a7-95ec-bd32-4e8270e66c31",
"status": "SUBMITTED",
"updatedDateTime": "2024-09-10T04:09:25.399Z"
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/{requirementsPackageId}",
"rel": "get-requirements-package",
"type": "GET"
}
]
}
Approval Process
An admin will review the submitted requirements package and if anything needs to be updated, the package will transition to state VERIFICATION_FAILED and admin will add remarks explaining the issue with the package.
Edit
Assets can be removed and added to the package while the package is in a DRAFT or VERIFICATION_FAILED status only
You can modify the customReference, callback, or email at any time by submitting a PATCH request
Delete
VERIFIED requirements packages will be auto-deleted if unassigned to a phone number for >2 years, but they must remain on your account for 2 years after the
last assignment in the event that Bandwidth must comply with a regulatory or local law enforcement request, so they cannot be manually deleted.
DRAFT requirements packages will be auto-deleted if they remain in a DRAFT state for >1 year.
Attach Phone Numbers
Once your package is VERIFIED, you can attach phone numbers for activation.
The ability to attach numbers to a package in a SUBMITTED state to auto-activate service once VERIFIED is coming soon.
For more details on adding or removing phone numbers from a requirements package view the API reference here.
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/{requirementsPackageId}/bulk
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"action": "add",
"allDetailsAccurate": true,
"phoneNumbers": [
"+390144230024",
"+390144230034"
]
}
Response
{
"data": {
"description": "The +390144230024, +390144230034 numbers has been successfully added to requirements package:55f9f932-6136-48cf-a724-401ec8fe5ff2. A link to the note is included in the Location header of the response.",
"phoneNumbers": [
{
"phoneNumber": "+390144230024"
},
{
"phoneNumber": "+390144230034"
}
]
},
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/1234/compliance/requirementsPackages/55f9f932-6136-48cf-a724-401ec8fe5ff2/phoneNumbers/bulk",
"method": "POST",
"rel": "self"
}
]
}