Communications API
Note: This API is only available to registered Alexa for Hospitality partners. See Get Started with Alexa for Hospitality APIs.
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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 unit ID you are using to create a communications profile, in the format "amzn1.alexa.unit.did.{UnitId}" |
String | Yes |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 unit ID 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. |
Create communication profiles in bulk
Call POST /v1/communications/profiles/batch to create communication profiles in bulk. You can create profiles for up to 100 units in a single request (one profile per unit). Each unit receives a unique profileId. You can then add the profileId as a contact in the address book of a different unit.
Note: This request isn't supported in the UK (en-GB) or France (fr-FR).
Request format
POST /v1/communications/profiles/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
None.
Request body format
{
"items": [
{
"itemId": {uniqueRequestItemId1},
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{unitId-1}"
},
"name": "{optionalProfileDisplayName1}"
},
{
"itemId": {uniqueRequestItemId2},
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{unitId-2}"
},
"name": "{optionalProfileDisplayName2}"
}
]
}
Request body example
{
"items": [
{
"itemId": 1,
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
},
"name": "Front desk"
},
{
"itemId": 2,
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
},
"name": "Hotel Restaurant"
}
]
}
Request body parameters
| Field | Description | Type | Required |
|---|---|---|---|
items |
A list of items for which to execute the operation. | List | Yes |
itemId |
The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. | Integer | Yes |
type |
The type of ID you are using to create a communication profile. Accepted value: UNIT |
String | Yes |
id |
The unit ID you are using to create a communications profile, in the format "amzn1.alexa.unit.did.{UnitId}" |
String | Yes |
name |
Profile display name for communication profile. This name appears on the target Alexa device or in the Alexa app when a guest makes an outbound call. It also appears when a contact is created for this unit on an Alexa device in another unit in the same property. | String | No |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 for individual items
The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.
Response body format
{
"successfulResults": [
{
"itemId": {uniqueRequestItemId},
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.{unitId}"
},
"profileId": "amzn1.alexa.communications.profile.did.{profileId}"
}
],
"errors": [
{
"itemId": {uniqueRequestItemId},
"status": {StatusCode},
"errorCode": "{ErrorCode}",
"errorDescription": "{ErrorMessage}"
}
]
}
Response body example
{
"successfulResults": [
{
"itemId": 1,
"entity": {
"type": "UNIT",
"id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
},
"profileId": "amzn1.alexa.communications.profile.did.XDTYU7678IJ3DT4EDFT4WSDFT776REWER"
}
],
"errors": [
{
"itemId": 2,
"status": 500,
"errorCode": "INTERNAL_ERROR",
"errorDescription": "Something went wrong."
}
]
}
Response body parameters for individual items
| Field | Description | Type | Required |
|---|---|---|---|
successfulResults |
This object contains the communication profiles that were successfully created for request items. |
Object | Yes |
itemId |
The unique ID of a request item for which communication profile creation succeeded or failed. | Integer | Yes |
type |
The type of ID for the communication profile. Accepted value: UNIT |
String | Yes |
id |
The unit ID for the communications profile. | String | Yes |
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 | Yes |
errors |
This object contains failed communication profile creation information for request items. |
Object | Yes |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages for individual items
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "UnitId is not valid. Please check your Input." |
| 400 | INVALID_PARAM | "Given entityType in request is not supported. Currently we only support UNIT entityType." |
| 400 | INVALID_PARAM | "Entity is mandatory." |
| 400 | INVALID_PARAM | "EntityType must be between 1 and 10 characters." |
| 400 | INVALID_PARAM | "EntityId must be between 1 and 1000 characters." |
| 400 | INVALID_PARAM | "Name must consist of 1 to 128 characters." |
| 403 | FORBIDDEN | "Requested action cannot be performed as you don't have access over the specified resource." |
| 500 | INTERNAL_ERROR | "An internal service error occurred." |
Error response body for overall request failure
The following example shows an error response body for an entire request, not for individual items.
Error response body format for HTTP status codes 401, 429, and 503
{
"message": "{ErrorMessage}"
}
Error response body example for HTTP status codes 401, 429, and 503
{
"message": "Invalid access token"
}
Response body parameters for overall request failure for error codes 401, 429, and 503
| Field | Description | Type | Required |
|---|---|---|---|
message |
Error message for HTTP status codes 401, 429, and 503. | String | Yes |
Error response body format for other 4xx and 5xx HTTP status codes
{
"errors": [
{
"itemId": {uniqueRequestItemId}, // This is optional if error is for request level
"status": {StatusCode},
"errorCode": "{ErrorCode}",
"errorDescription": "{ErrorMessage}"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, with itemId
{
"errors": [
{
"itemId": 0,
"status": 400,
"errorCode": "",
"errorDescription": "Given entityType in request is not supported. Currently we only support UNIT entityType."
},
{
"itemId": 2,
"status": 400,
"errorCode": "",
"errorDescription": "UnitId is not valid. Please check your Input"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, without itemId
{
"errors": [
{
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "Request item list size must be between 1 to 100"
}
]
}
Response body parameters for overall request failure for other 4xx and 5xx HTTP status codes
| Field | Description | Type | Required |
|---|---|---|---|
errors |
This object contains failed communication profile creation information for request items. |
Object | Yes |
itemId |
The unique identifier of the request item for which profile creation failed. | Integer | No |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages for overall request failure
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "ItemId is mandatory for all request items" |
| 400 | INVALID_PARAM | "ItemId should be unique for each request item. Multiple requests with itemId [X] present." |
| 400 | INVALID_PARAM | "Request item list size must be between 1 to 100" |
| 401 | Unauthorized | "The LWA token is expired or invalid." |
| 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_ERROR | "Something went wrong" |
| 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 unit ID associated with a communication profile.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 unit ID 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 unit ID associated with a communication profile.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 unit ID of the communication profile you are fetching, in the format "amzn1.alexa.unit.did.{UnitId}" |
String | Yes |
Request body
None.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 unit ID 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
profileIdassigned to a unit. - Delete any contacts in address books where
profileIDis the contact.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. |
| 409 | Conflict | The address book can't be deleted, because it's associated with a unit. The user must delete the association first, and then delete the address book. |
| 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 contacts
Create a contact
Call POST /v1/addressBooks/{addressBookId}/contacts to add a contact to an address book. A contact is an address book entry that represents a callable Alexa device or PSTN number. You can create a contact with either a phone number or a communication profile.
Note: The
phoneNumbers object must be omitted in requests for France (fr-FR).Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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. Note: Phone number isn't supported in France (fr-FR). |
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 |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. |
Create contacts in bulk
Call POST /v1/addressBooks/{addressBookId}/contacts/batch to create address book contacts in bulk. You can create up to 100 contacts in a single request. A contact is an address book entry that represents a callable Alexa device or PSTN number. You can create a contact with either a phone number or a communication profile.
Note: This request isn't supported in the UK (en-GB) or France (fr-FR).
Request format
POST /v1/addressBooks/{addressBookId}/contacts/batch 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 path parameters
None.
Request body format with a phone number and with a communication profile
{
"items": [
{
"itemId": {uniqueRequestItemId1},
"contact": {
"name": "{contactName}",
"phoneNumbers": [
{
"number": "{phoneNumber}"
}
]
}
},
{
"itemId": {uniqueRequestItemId2},
"contact": {
"name": "{contactName}",
"alexaCommunicationProfileId": "{communicationProfile}"
}
}
]
}
Request body example with a Phone number and with a communication profile
{
"items": [
{
"itemId": 1,
"contact": {
"name": "Diego Ramirez",
"phoneNumbers": [
{
"number": "{phoneNumber}"
}
]
}
},
{
"itemId": 2,
"contact": {
"name": "Nurse station",
"alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.XER5678IJHYTREW45678I9OLKI876REDS"
}
}
]
}
Request body parameters
| Field | Description | Type | Required |
|---|---|---|---|
items |
A list of items for which to execute the operation. | List | Yes |
itemId |
The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. | Integer | Yes |
number |
The contact phone number. Must be in E.164 format. Up to three phone numbers can be added. Note: You can't add both a phone number and a alexaCommunicationProfileId to the same contact. |
String | Yes |
alexaCommunicationProfileId |
The id of your communication profile. Note: 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 |
name |
The contact name. Must be between 1 and 50 characters long. | String | Yes |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 for individual items
The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.
Response body format
{
"successfulResults": [
{
"itemId": {uniqueRequestItemId1},
"contactId": "amzn1.alexa.contact.did.{contactId}"
}
],
"errors": [
{
"itemId": {uniqueRequestItemId2},
"status": {StatusCode},
"errorCode": {ErrorCode},
"errorDescription": "{ErrorMessage}"
}
]
}
Response body example
{
"successfulResults": [
{
"itemId": 1,
"contactId": "amzn1.alexa.contact.did.XDFTYHUJKKMIUT56E45DER5678IJJRF"
}
],
"errors": [
{
"itemId": 2,
"status": 500,
"errorCode": "INTERNAL_ERROR",
"errorDescription": "Something went wrong."
}
]
}
Response body parameters for individual items
| Field | Description | Type | Required |
|---|---|---|---|
successfulResults |
This object contains the contacts that were successfully created for request items. |
Object | Yes |
itemId |
The unique ID of a request item for which contact creation succeeded. | Integer | Yes |
contactId |
A unique contact ID that identifies a contact. Generated when creating a contact for the first time. | String | Yes |
errors |
This object contains failed contact creation information for request items. |
Object | Yes |
itemId |
The unique identifier of the request item for which contact creation failed. | Integer | Yes |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages for individual items
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "Contact must have atleast one PhoneNumber or a CommunicationProfileId" |
| 400 | INVALID_PARAM | "A Contact cannot contain both PhoneNumber and a CommunicationProfileId. You must add either one." |
| 400 | INVALID_PARAM | "AlexaCommunicationProfileId 'amzn1.AESAS5HB7E4RMTCQHMOHA2' is not in standard format" |
| 400 | INVALID_PARAM | "Given phone number is not per E.164 format" |
| 400 | INVALID_PARAM | "Contact is mandatory" |
| 400 | INVALID_PARAM | "Contact Name must be between 1 and 50 characters" |
| 400 | INVALID_PARAM | "Number of phonenumbers has to be between 1 and 3" |
| 400 | INVALID_PARAM | "Contact Name must be between 1 and 50 characters" |
| 403 | FORBIDDEN | "Requested action cannot be performed as you don't have access over the specified resource" |
| 500 | INTERNAL_ERROR | "An internal service error occurred." |
Error response body for overall request failure
The following example shows an error response body for an entire request, not for individual items.
Error response body format for HTTP status codes 401, 429, and 503
{
"message": "{ErrorMessage}"
}
Error response body example for HTTP status codes 401, 429, and 503
{
"message": "Invalid access token"
}
Response body parameters for overall request failure
| Field | Description | Type | Required |
|---|---|---|---|
message |
Error message for HTTP status codes 401, 429 and 503. | String | Yes |
Error response body format for other 4xx and 5xx HTTP status codes
{
"errors": [
{
"itemId": {uniqueRequestItemId}, // This is optional if error is for request level
"status": {StatusCode},
"errorCode": "{ErrorCode}",
"errorDescription": "{ErrorMessage}"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, with itemId
{
"errors": [
{
"itemId": 1,
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "AlexaCommunicationProfileId 'xyz' is not in standard format"
},
{
"itemId": 2,
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "Given phone number is not per E.164 format"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, without itemId
{
"errors": [
{
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "ItemId is mandatory for all request items"
}
]
}
Response body parameters for other 4xx and 5xx HTTP status codes
| Field | Description | Type | Required |
|---|---|---|---|
errors |
This object contains failed contact creation information for request items. |
Object | Yes |
itemId |
The unique ID of a request item for which contact creation succeeded or failed. | Integer | No |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "ItemId is mandatory for all request items" |
| 400 | INVALID_PARAM | "ItemId should be unique for each request item. Multiple requests with itemId [X] present." |
| 400 | INVALID_PARAM | "Request item list size must be between 1 to 100" |
| 401 | Unauthorized | "The LWA token is expired or invalid." |
| 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_ERROR | "Something went wrong" |
| 503 | Service Unavailable | "The service is currently unavailable to handle the request." |
List contacts
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.
Note: The
phoneNumbers object isn't returned in requests for France (fr-FR).Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. |
Get a contact
Call GET /v1/addressBooks/{addressBookId}/contacts/{contactId} to retrieve the metadata for a contact.
Note: Phone number isn't supported in France (fr-FR).
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. Note: The phoneNumbers object isn't returned in requests for France (fr-FR) accounts. |
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. |
Update a contact
Call PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} to update the metadata for a contact.
Note: Phone number isn't supported in France (fr-FR).
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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. Note: Phone number isn't supported in France (fr-FR). |
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 |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. |
Delete a contact
Call DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId} to delete a contact from an address book.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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. |
| 409 | Conflict | The address is already associated with the unit. |
| 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. |
Create address book associations in bulk
Call POST /v1/addressBooks/{addressBookId}/unitAssociations/batch to associate an address book with up to 100 units.
Note: This request isn't supported in the UK (en-GB) or France (fr-FR).
Request format
POST /v1/addressBooks/{addressBookId}/unitAssociations/batch 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
{
"items": [
{
"itemId": {uniqueRequestItemId1},
"unitId": "amzn1.alexa.unit.did.{unitId-1}"
},
{
"itemId": {uniqueRequestItemId2},
"unitId": "amzn1.alexa.unit.did.{unitId-2}"
}
]
}
Request body example
{
"items": [
{
"itemId": 1,
"unitId": "amzn1.alexa.unit.did. XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ "
},
{
"itemId": 2,
"unitId": "amzn1.alexa.unit.did.DRR56T7UIOLKI76TREDFTY998TYGDFGT4DFR "
}
]
}
Request body parameters
| Field | Description | Type | Required |
|---|---|---|---|
items |
A list of items for which to execute the operation. | List | Yes |
itemId |
The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. | Integer | Yes |
unitId |
The unit ID you are using to create an address book association, in the format "amzn1.alexa.unit.did.{UnitId}". |
String | Yes |
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 for individual items
The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.
Response body format
{
"successfulResults": [
{
"itemId": {uniqueRequestItemId1},
"unitId": "amzn1.alexa.unit.did.{unitId-1}",
"addressBookId": "amzn1.alexa.addressbook.did.{addressBookId}"
}
],
"errors": [
{
"itemId": {uniqueRequestItemId2}
"status": {StatusCode},
"errorCode": {ErrorCode},
"errorDescription": "{ErrorMessage}"
}
]
}
Response body example
{
"successfulResults": [
{
"itemId": 1,
"unitId": "amzn1.alexa.unit.did.XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ",
"addressBookId": "amzn1.alexa.addressbook.did.DRFDCFRT6789876TR56789OLIUYTFY7654EDDF"
}
],
"errors": [
{
"itemId": 2,
"status": 409,
"errorCode": "INVALID_PARAM",
"errorDescription": "AddressBook is already associated with the Unit"
}
]
}
Response body parameters for individual items
| Field | Description | Type | Required |
|---|---|---|---|
successfulResults |
This object contains the address book associations that were successfully created for request items. |
Object | Yes |
itemId |
The unique ID of a request item for which address book association creation succeeded or failed. | Integer | Yes |
unitId |
The unit ID for the address book association. | String | Yes |
addressBookId |
A unique ID that identifies an address book association. Generated when creating an address book association for the first time. | String | Yes |
errors |
This object contains failed address book association creation information for request items. |
Object | Yes |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages for individual items
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "UnitId is not valid. Please check your Input." |
| 400 | INVALID_PARAM | "UnitId is mandatory." |
| 403 | FORBIDDEN | "Requested action cannot be performed as you don't have access over the specified resource." |
| 404 | INVALID_PARAM | "UnitId doesn't exist." |
| 409 | INVALID_PARAM | "AddressBook is already associated with the Unit" |
| 500 | INTERNAL_ERROR | "An internal service error occurred." |
Error response body for overall request failure
The following example shows an error response body for an entire request, not for individual items.
Error response body format for HTTP status codes 401, 429, and 503
{
"message": "{ErrorMessage}"
}
Error response body example for HTTP status codes 401, 429, and 503
{
"message": "Invalid access token"
}
Response body parameters for overall request failure for error codes 401, 429, and 503
| Field | Description | Type | Required |
|---|---|---|---|
message |
Error message for HTTP status codes 401, 429, and 503. | String | Yes |
Error response body format for other 4xx and 5xx HTTP status codes
{
"errors": [
{
"itemId": {uniqueRequestItemId}, // This is optional if error is for request level
"status": {StatusCode},
"errorCode": "{ErrorCode}",
"errorDescription": "{ErrorMessage}"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, with itemId
{
"errors": [
{
"itemId": 2,
"status": 403,
"errorCode": "FORBIDDEN",
"errorDescription": "Requested action cannot be performed as you don't have access over the specified resource"
}
]
}
Error response body example for other 4xx and 5xx HTTP status codes, without itemId
{
"errors": [
{
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "ItemId is mandatory for all request items"
}
]
}
Response body parameters for overall request failure for other 4xx and 5xx HTTP status codes
| Field | Description | Type | Required |
|---|---|---|---|
errors |
This object contains failed address book association creation information for request items. |
Object | Yes |
itemId |
The unique ID of a request item for which address book association creation succeeded or failed. | Integer | No |
status |
HTTP response code for a failed request item. | Integer | Yes |
errorCode |
The error code for the error. | Enum | Yes |
errorDescription |
The error message for the error. | String | Yes |
HTTP status codes and error messages for overall request failure
| Status Code | Error Code | Error Message |
|---|---|---|
| 400 | INVALID_PARAM | "ItemId is mandatory for all request items" |
| 400 | INVALID_PARAM | "AddressBookId is not valid. Please check your Input" |
| 400 | INVALID_PARAM | "ItemId should be unique for each request item. Multiple requests with itemId [X] present." |
| 400 | INVALID_PARAM | "Request item list size must be between 1 to 100" |
| 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_ERROR | "Something went wrong" |
| 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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 maximum value is 100. 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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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 maximum value is 100. 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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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.
Request format
Note: In the request header, set
Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.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.
Response header
Note: In the response header, the returned
Host value is the same as the Host value in the request.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 | 2000 | "You have reached the maximum number of contacts that can be created per address book: 2000" |
| 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 | 2500 | "You have reached the maximum number of units that can be associated with an address book: 2500" |
| 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" |