Communications API
Manage communication profiles
To support calling, a unit must create a communications profile – communications Profiles aren't auto-created. When you create communication profile for a unit, it's assigned a unique identifier called a profileId
. You can then add the profileId
as a contact in the address book of a different unit.
Note: The
alexaCommunicationsProfileId
listed in the
Manage Contact APIs is the same as the
profileId
listed in this section.
Create a communication profile
Call POST /v1/communications/profile/
to create a communication profile. When you create a communication profile, it enables the communication capability and creates a profileId
for a unit. If a profile already exists for the unit, the existing profileID
for the unit is returned.
POST /v1/communications/profile/ HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
None.
Request body format
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{UnitId}"
}
}
Request body example
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.AFOVR3XKYQJ4REIHURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
}
}
Request body parameters
Field |
Description |
Type |
Required |
type |
The type of id you are using to create a communication profile. Accepted value: UNIT |
String |
Yes |
id |
The UnitId you are using to create a communications profile, in the format "amzn1.alexa.unit.did.{UnitId}" |
String |
Yes |
HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{UnitId}"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.{profileId}"
}
}
Response body example
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
}
}
Response body parameters
Field |
Description |
Type |
type |
The type of id used to create a communication profile. Possible value: UNIT |
String |
Id |
The UnitId used to create a communications profile. |
String |
profileId |
A unique profile id that identifies a communication profile. Generated when creating a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. |
String |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "UnitId is not valid. Please check your Input."
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
400 |
Bad Request |
UnitId is not valid. Please check your Input. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
400 |
Bad Request |
The profileId is not valid |
403 |
Limit exceeded |
The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not Found |
UnitId doesn't exist. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Get a communication profile by profileId
Call GET /v1/communications/profile/{profileId}
to get the UnitId associated with a communication profile.
GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
profileId |
The unique profile id that identifies the communication profile you are fetching. Generated when you created a communication profile for the first time. |
String |
Yes |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{UnitId}"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.{profileId}"
}
}
Response body example
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
}
}
Response body parameters
Field |
Description |
Type |
type |
The type of id used to create the communication profile. Accepted value: UNIT |
String |
Id |
The UnitId used to create the communications profile. |
String |
profileId |
The unique profile id of the communication profile. Generated when you created a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. |
String |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "ProfileId is not valid. Please check your Input"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Limit exceeded |
The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not Found |
UnitId doesn't exist. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Get a communication profile by entity id
Call GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id}
to get the UnitId associated with a communication profile.
GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
entity.type |
The type of id for the communication profile you are fetching. Accepted value: UNIT |
String |
Yes |
entity.id |
The UnitId of the communication profile you are fetching, in the format "amzn1.alexa.unit.did.{UnitId}" |
String |
Yes |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{UnitId}"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.{profileId}"
}
}
Response body example
{
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
},
"profileId": {
"profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
}
}
Response body parameters
Field |
Description |
Type |
type |
The type of id used to create the communication profile. Accepted value: UNIT |
String |
Id |
The UnitId used to create the communications profile. |
String |
profileId |
The unique profile id of the communication profile. Generated when you created a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. |
String |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Communication profile does not exist for the given entity"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The provided entity type isn't supported. Accepted values: UNIT |
400 |
Bad Request |
UnitId isn't valid. Please check your Input. |
400 |
Bad Request |
The profileId is not valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Limit exceeded |
The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not Found |
UnitId doesn't exist. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Delete a communication profile
Call DELETE /v1/communications/profile/{profileId}
to delete a communication profile. This call completes the following actions:
- Disables the communication capability.
- Deletes the
profileId
assigned to a unit.
- Delete any contacts in address books where
profileID
is the contact.
GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
profileId |
The unique profile id that identifies the communication profile you are deleting. Generated when you created a communication profile for the first time. |
String |
Yes |
Request body
None.
HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Communication profile does not exist"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
400 |
Bad Request |
The profileId is not valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not Found |
The communication profile doesn't exist. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Manage address books
Create an address book
Call POST /v1/addressBooks
to create an address book.
POST /v1/addressBooks HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
None.
Request body format
{
"name": "{addressbookName}"
}
Request body example
{
"name": "Example Hotel Seattle"
}
Request body parameters
Field |
Description |
Type |
Required |
name |
The address book name. Must be between 1 and 50 characters long. |
String |
Yes |
HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"addressBookId": "amzn1.alexa.addressbook.did.{id}"
}
Response body example
{
"addressBookId": "amzn1.alexa.addressbook.did.AFFIZRSWWLHI24RAVPYBTH435G63MEAVPYGFCCP3MR4DEGEE35CEX6I2KVU2PWNJG6FEZARP3B5NRWFJDJPTHAMAV35XSNW24NHRYNXEL4VY3P5ROWZGH7P2RE654AOX4E"
}
Response body parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID for the new address book, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Name must be between 1 and 50 characters"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Limit exceeded |
The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
List address books
Call GET /v1/addressBooks
to retrieve the list of address books. The optional maxResults
and nextToken
values provide pagination for the results.
GET /v1/addressBooks?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request query parameters
Field |
Description |
Type |
Required |
maxResults |
Maximum number of results per call. The value of this parameter must be between 1 and 1000. The default value is 100. |
Integer |
No |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body format
{
"results": [
{
"addressBookId": "amzn1.alexa.addressbook.did.{id}",
"name": "{addressBookName}"
},
],
"paginationContext": {
"nextToken": "{nextToken}"
}
}
Success response body example
{
"results": [
{
"addressBookId": "amzn1.alexa.addressbook.did.AEIDIDYHLJGARHFICBJKJFPOQF67CUTIU6QZA7DYPV5JEMPOQY4XVY323UUT7GWCXMAMRODWU55GLVRKWS4UTUJLFGVDCZ2DBVPOFUUCCHKW2J4557K56VLMJPVBNECJBE",
"name": "Example Hotel Seattle"
}
],
"paginationContext": {
"nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAF-ACXJUajwy_DQYFKIIKNHt9CS5EUCimxqdvXoJOiEoGUJ1oxvFCfj1lAy8bJ47fK85FjBF0j5Z95HyaxgqDPXsxHkHx7kuZ0ybI7r7N716qI0IxFM_XOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
}
}
Response body parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
name |
The address book name. |
String |
Yes |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Received invalid pagination token. Please check the pagination value passed"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Get an address book
Call GET /v1/addressBooks/{addressBookId}
to retrieve the metadata for an address book.
GET /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body format
{
"addressBookId": "amzn1.alexa.addressbook.did.{id}",
"name": "{addressbookName}"
}
Success response body example
{
"addressBookId": "amzn1.alexa.addressbook.did.AEWEYSYTUWWISWGD32TNVUP67Z2KEI3XGOTDTEYHWKFL2QB55D7IV2O3CAYIGO4PEEL3UUFOBPMHK6FWWZMBJUT4EY4WLJHY63HA7GATUOC3K7CH4EK3QHXEXOKGDGEJBQ",
"name": "Example Hotel Seattle"
}
Response body parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
name |
The address book name. |
String |
Yes |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "AddressBookId does not exist"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Update an address book
Call PUT /v1/addressBooks/{addressBookId}
to update the address book name.
PUT /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request body format
{
"name": "{addressbookName}"
}
Request body example
{
"name": "Example Hotel Seattle"
}
Request body parameters
Field |
Description |
Type |
Required |
name |
The new address book name. Must be between 1 and 50 characters long. |
String |
Yes |
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body
None.
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Address book name is mandatory"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Delete an address book
Call DELETE /v1/addressBooks/{addressBookId}
to delete an address book.
DELETE /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request body
None.
HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body
None.
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Address book ID must be between 10 and 1000 characters"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Call POST /v1/addressBooks/{addressBookId}/contacts
to add a contact to an address book. You can create a contact with either a phone number or a communication profile.
Note: Only one contact can be created in each API call.
POST /v1/addressBooks/{addressBookId}/contacts HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request body format with a phone number
{
"contact": {
"name": "{contactName}",
"phoneNumbers": [
{
"number": "{phoneNumber}"
}
]
}
}
Request body example with single phone number
{
"contact": {
"name": "Example Hotel Reception",
"phoneNumbers": [
{
"number": "+16055554411"
}
]
}
}
Request body example with multiple phone numbers
{
"contact": {
"name": "Example Hotel Laundry Service",
"phoneNumbers": [
{
"number": "+12055551233"
},
{
"number": "+12055551244"
}
]
}
}
Request body format with a communication profile
{
"contact": {
"name": "{contactName}",
"alexaCommunicationProfileId": "{communicationProfile}"
}
}
Request body example with a communication profile
{
"contact": {
"name": "Example Hotel Laundry Service",
"alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
}
}
Request body parameters
Field |
Description |
Type |
Required |
name |
The contact name. Must be between 1 and 50 characters long. |
String |
Yes |
number |
The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. |
String |
Yes |
alexaCommunicationProfileId |
The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. |
String |
Yes |
HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"contactId": "amzn1.alexa.contact.did.{id}"
}
Response body example
{
"contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
400 |
Bad Request |
A contact must have at least one number object or a alexaCommunicationProfileId . |
400 |
Bad Request |
A contact can't have both a number and a alexaCommunicationProfileId . |
400 |
Bad Request |
The alexaCommunicationProfileId must be between 40 and 200 characters. |
400 |
Bad Request |
The profileId is not valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Limit exceeded |
The request exceeds the limit on the number of contacts per unit. Per-user soft limit and config controlled. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Call GET /v1/addressBooks/{addressBookId}/contacts
to retrieve the contacts for a given address book. The optional maxResults
and nextToken
values provide pagination for the results.
GET /v1/addressBooks/{addressBookId}/contacts?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request query parameters
Field |
Description |
Type |
Required |
maxResults |
Maximum number of results per call. The value of this parameter must be between 1 and 1000. The default value is 100. |
Integer |
No |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"results": [
{
"contactName": "{contactName}",
"contactId": "amzn1.alexa.contacts.did.{id}"
}
],
"paginationContext": {
"nextToken": "{nextToken}"
}
}
Response body example
{
"results": [
{
"contactName": "Marriott Reception",
"contactId": "amzn1.alexa.contact.did.AGNA6I63RJBIV7EFEL73AJEIUZ7XGKDCB7VYRO6JTLMHX72F2P4YX4ZVZNCWB3SZR5ZS5ETPJTCCHCTV2NV2XU66GCKSNGF54PZCBCUE"
},
{
"contactName": "Blueacre Restaurant",
"contactId": "amzn1.alexa.contact.did.AEWC6RQGHIKFWT6UMMWWLHCS5Y6HBJACWEF35Y2FB7FO2QACH6MV7VEFE3CKLJZDFENFKAEQKFW6C4SCWO6ERFZ4KGGCXTKC2HXUYQMC"
}
],
"paginationContext": {
"nextToken": "AAEAAcpUKRGBVjzoVWM6lljL35vnWNJEqQmscd4Zm6oRLWl8AAAAAF-D0_sNXPigGsCK9AvcWkfVahZ0RTA0tTLrTBFRL81qFM2lGK0ZZ8erl47sqVEMPBRxIvSjNaQrmBIS8UjNvHDck-fQJHFkm-r27-0lylTI_oMPC1h4MIo6bAEeGZqWbq0JxmMUdRvTpRgoImeEW5GUccVq-2Zf21YFOaHIkvXmBkaFdBDP2T1i5WD5OxiAwd1PEBTRZ"
}
}
Response body parameters
Field |
Description |
Type |
Required |
contactId |
The contact ID, in the format "amzn1.alexa.contacts.did.{id}" . |
String |
Yes |
contactName |
The contact name. Must be between 1 and 50 characters long. |
String |
Yes |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Call GET /v1/addressBooks/{addressBookId}/contacts/{contactId}
to retrieve the metadata for a contact.
GET /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
contactId |
The contact ID, in the format "amzn1.alexa.contacts.did.{id}" . |
String |
Yes |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format with phone number
{
"contact": {
"name": "{contactName}",
"phoneNumbers": [
{
"number": "{phoneNumber}"
}
]
},
"contactId": "amzn1.alexa.contacts.did.{contactIdid}"
}
Response body example with phone number
{
"contact": {
"name": "Example Hotel Seattle Reception",
"phoneNumbers": [
{
"number": "+16055554411"
}
]
},
"contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}
Response body format with communication profile
{
"contact": {
"name": "{contactName}",
"alexaCommunicationProfileId": "{communicationProfile}"
},
"contactId": "amzn1.alexa.contact.did.{contactId}"
}
Response body example with communication profile
{
"contact": {
"name": "Example Hotel Seattle Reception",
"alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
},
"contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU""
}
Response body parameters
Field |
Description |
Type |
Required |
name |
The contact name. Must be between 1 and 50 characters long. |
String |
Yes |
number |
The contact phone number. Must be in E.164 format. Up to three phone numbers can be added. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. |
String |
Yes |
alexaCommunicationProfileId |
The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. |
String |
Yes |
contactId |
The contact ID, in the format "amzn1.alexa.contacts.did.{id}" . |
String |
Yes |
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or contact ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Call PUT /v1/addressBooks/{addressBookId}/contacts/{contactId}
to update the metadata for a contact.
PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
contactId |
The contact ID, in the format "amzn1.alexa.contacts.did.{id}" . |
String |
Yes |
Request body format with phone number
{
"contact": {
"name": "{contactName}",
"phoneNumbers": [
{
"number": "{phoneNumber}"
}
]
}
}
Request body example with phone number
{
"contact": {
"name": "Example Hotel Seattle Reception",
"phoneNumbers": [
{
"number": "+16055554412"
}
]
}
}
Request body format with communication profile
{
"contact": {
"name": "{contactName}",
"alexaCommunicationProfileId": "{communicationProfile}"
}
}
Request body example with communication profile
{
"contact": {
"name": "Example Hotel Seattle Reception",
"alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
}
}
Request body parameters
Field |
Description |
Type |
Required |
name |
The contact name. Must be between 1 and 50 characters long. |
String |
Yes |
number |
The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. |
String |
Yes |
alexaCommunicationProfileId |
The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. |
String |
Yes |
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body
None.
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or contact ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Call DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId}
to delete a contact from an address book.
DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
contactId |
The contact ID, in the format "amzn1.alexa.contacts.did.{id}" . |
String |
Yes |
Request body
None.
HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body
None.
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "Contact ID is not valid. Please check your input"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or contact ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Manage address book associations
Create an address book association
Call POST /v1/addressBooks/{addressBookId}/unitAssociations
to associate an address book with a unit.
POST /v1/addressBooks/{addressBookId}/unitAssociations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request body format
{
"unitId": "amzn1.alexa.unit.did.{id}"
}
Request body example
{
"unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU"
}
Request body parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID to associate with the address book, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"unitId": "amzn1.alexa.unit.did.{id}",
"addressBookId": "amzn1.alexa.addressbook.did.{id}"
}
Response body example
{
"unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
"addressBookId": "amzn1.alexa.addressbook.did.AFWNDND4TUBMMIU4P7HHXI2TY27FGYRODJVSYQUENRKSI4FTWTSJB3UUGI5WSH2LMQOYPSDDIJUG6NN336JKARWGXM2POYAB3LVOLVZ5XBO2WZX32SU5D54NF3RSEDGIPU"
}
Response body parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
addressBookId |
The address book ID for the new address book, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "You have reached maximum allowed limit of AddressBooks that can be associated per Unit: 3"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Limit exceeded |
The request exceeds the limit on the number of units that an address books can be associated with, or the number address books that can be associated with a unit. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or unit ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
List address book associations for a unit
Call GET /v1/addressBooks/unitAssociations
to retrieve the list of address books that are associated with a unit. The optional maxResults
and nextToken
values provide pagination for the results.
GET /v1/addressBooks/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request query parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
maxResults |
Maximum number of results per call. The default value is 10. |
Integer |
No |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"results": [
{
"unitId": "amzn1.alexa.unit.did.{id}",
"addressBookId": "amzn1.alexa.addressbook.did.{id}"
}
],
"paginationContext": {
"nextToken": "{nextToken}"
}
}
Response body example
{
"results": [
{
"unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
"addressBookId": "amzn1.alexa.addressbook.did.AF2B2LU7KDOZAMUJRTVCT66DWPFP3BOQ4RZ5GPHAVCIJTMQBJHEDHLANZOJFZSKLG6X2SVE3YCCUZVCP5R7RNZBKI6KHYHGFFLVFIVVJKNU24O45BRMHPBGQ35IPRBZTSI"
},
{
"unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
"addressBookId": "amzn1.alexa.addressbook.did.AFOEHWC2DFKIOVNRS7NXM7MCVHNTDODUUXZ5XCXFTBNNEL6QDLC6OTHOES6PRRKP6MRSKE4EZ6APO4TTVZF56QNQYUKYSHTATCGG4AKO2NGZPJ2ZXRZP5M2MUPJWU7FORE"
}
],
"paginationContext": {
"nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
}
}
Response body parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified unit ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Get an address book association
Call GET /v1/addressBooks/{addressBookId}/unitAssociations
to retrieve an address book association. The optional maxResults
and nextToken
values provide pagination for the results.
GET /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request query parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . When unitId is present, this call returns the association between addressBookId and unitId . If not, it returns a list of all units associated with the given addressBookId . |
String |
No |
maxResults |
Maximum number of results per call. The default value is 10. |
Integer |
No |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
Request body
None.
HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body format
{
"results": [
{
"unitId": "amzn1.alexa.unit.did.{id}",
"addressBookId": "amzn1.alexa.addressbook.did.{id}"
}
],
"paginationContext": {
"nextToken": "{nextToken}"
}
}
Response body example
{
"results": [
{
"unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU",
"addressBookId": "amzn1.alexa.addressbook.did.AHZO6C2F4A4AUHY4EPFA3R5KHVBQ763U3ZWPPLXEUAWCVCKYVSTMXH2GR6TN7CFM4KQXMMNWJVAQBP2Y2YBUKOBUPOPNDFDW434MJQ4ZKV6YQNIC575PUW6RVVVUKMEWYA"
}
],
"paginationContext": {
"nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
}
}
Response body parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. |
String |
No |
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or unit ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Delete an address book association
Call DELETE /v1/addressBooks/{addressBookId}/unitAssociations
to remove the association between an address book and a unit.
Note: All of a unit's address book associations must be deleted before the unit itself can be deleted.
DELETE /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field |
Description |
Type |
Required |
addressBookId |
The address book ID, in the format "amzn1.alexa.addressbook.did.{id}" . |
String |
Yes |
Request query parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
Request body
None.
HTTP/1.1 204 No Content
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field |
Description |
Type |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Success response body
None.
Error response body format
{
"message": "{errorMessage}"
}
Error response body example
{
"message": "AddressBook and Unit are not associated"
}
HTTP response codes
Status Code |
Description |
Reason |
400 |
Bad Request |
The request is missing one or more required parameters, or the parameter values aren't valid. |
401 |
Unauthorized |
The LWA token is expired or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The specified address book ID or unit ID wasn't found. |
429 |
Too many requests |
Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled. |
500 |
Internal Server Error |
An internal service error occurred. |
503 |
Service Unavailable |
The service is currently unavailable to handle the request. |
Resource limits
Resource |
Default |
Error message on exceeding the limit |
Maximum number of contacts allowed in an address book |
500 |
"You have reached the maximum number of contacts that can be created per address book: 500" |
Maximum number of address books that can be associated with a unit |
10 |
"You have reached the maximum number of address books that can be associated with a unit: 10" |
Maximum number of units that an address book can be associated with |
100 |
"You have reached the maximum number of units that can be associated with an address book: 100" |
Max number of phone numbers per contact |
3 |
"The number of phone numbers must be between 1 and 3" |
Max number of address books per organization |
2500 |
"You have reached maximum number of address books that you can create per organization: 2500" |