Communications API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties in senior living partners. See Get Started with Alexa Smart Properties in Senior Living APIs.

You can use the Alexa Communications REST API to create and manage communication profiles, address books, and contacts.

API endpoint

The endpoint of the Communications API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Communications API includes the following operations.

Operation	HTTP Method and URI
Create a communication profile	`POST /v1/communications/profile`
Create communication profiles in bulk	`POST /v1/communications/profiles/batch`
Update a communication profile	`PUT /v1/communications/profile/{profileId}`
Get a communication profile by profileId	`GET /v1/communications/profile/{profileId}`
Get a communication profile by entity id	`GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id}`
Delete a communication profile	`DELETE /v1/communications/profile/{profileId}`
Create an address book	`POST /v1/addressBooks`
List address books	`GET /v1/addressBooks`
Get an address book	`GET /v1/addressBooks/{addressBookId}`
Update an address book	`PUT /v1/addressBooks/{addressBookId}`
Delete an address book	`DELETE /v1/addressBooks/{addressBookId}`
Create a contact	`POST /v1/addressBooks/{addressBookId}/contacts`
Create contacts in bulk	`POST /v1/addressBooks/{addressBookId}/contacts/batch`
List contacts	`GET /v1/addressBooks/{addressBookId}/contacts`
Get a contact	`GET /v1/addressBooks/{addressBookId}/contacts/{contactId}`
Update a contact	`PUT /v1/addressBooks/{addressBookId}/contacts/{contactId}`
Delete a contact	`DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId}`
Create an address book association	`POST /v1/addressBooks/{addressBookId}/unitAssociations`
Create address book associations in bulk	`POST /v1/addressBooks/{addressBookId}/unitAssociations/batch`
List address book associations for a unit	`GET /v1/addressBooks/unitAssociations`
Get an address book association	`GET /v1/addressBooks/{addressBookId}/unitAssociations`
Delete an address book association	`DELETE /v1/addressBooks/{addressBookId}/unitAssociations`

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. Optionally, you can provide a Name for the profile, which will appear as a display name for the unit (e.g. room) that the profile belongs to. If a profile for the unit already exists, the API will return 201 and update the profile display name if different from the one previously applied.

Note: A name is required to setup inbound calling experience. If no profile name is specified,“Guest” is used as the default profile display name.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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}"
    },
    "name": "profile display name"
}

Request body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKYQJ4REIHURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave"
}

Request body parameters

Field	Description	Type	Required
`entity`	The entity for which communication profile is being created.	Object	Yes
`entity.type`	The type of ID you are using to create a communication profile. Accepted value: `UNIT`	String	Yes
`entity.id`	The unit ID you are using to create a communications profile, in the format `"amzn1.alexa.unit.did.{UnitId}"`	String	Yes
`name`	Display name for communication profile. This name will appear as display name for the unit (e.g. room) on external contact's address book so they can place an inbound call, and on external contact's Alexa-enabled device or Alexa Companion app when user in the unit (e.g. room) makes an outbound call. The name string must consist of 1 to 50 Unicode (UTF-8) characters and follow the following rules: 1) Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, apostrophes, dashes, or underscores. Other special characters are not permitted. 2) Names must contain at least one number or letter.	String	No

Response header

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.
400	Bad Request	The `profileId` is not valid
400	Bad Request	`name` 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.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

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

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."`

Update a communication profile

Call PUT /v1/communications/profile/{profileId} to update the display name for a communication profile.

Note: When 'name' is updated for a profile, existing reciprocal associations will continue to have the previous display name, while new reciprocal associations will have the new name.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

PUT /v1/communications/profile/ 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 being updated. Generated when you created a communication profile.	String	Yes

Request body format

{
    "name": "<profile display name>"
 }

Request body example

{
    "name": "Dave"
 }

Request body parameters

Field	Description	Type	Required
`name`	Display name for communication profile. This name will appear as display name for the unit (e.g. room) on external contact's address book so they can place an inbound call, and on external contact's Alexa-enabled device or Alexa Companion app when user in the unit (e.g. room) makes an outbound call. The name string must consist of 1 to 50 Unicode (UTF-8) characters and follow the following rules: 1) Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, apostrophes, dashes, or underscores. Other special characters are not permitted. 2) Names must contain at least one number or letter.	String	No

Response header

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

Response body format

None.

Response body example

None.

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.
400	Bad Request	The `profileId` is not valid
400	Bad Request	`name` is not valid
400	Bad Request	`name` is required
401	Unauthorized	The LWA token is expired or invalid.
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 unit ID associated with a communication profile.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

Response body parameters

Field	Description	Type
`entity.type`	The type of id used to create the communication profile. Accepted value: `UNIT`	String
`entity.Id`	The unit ID used to create the communications profile.	String
`name`	Display name for the communication profile.	String
`profileId.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	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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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 query 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

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}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

Response body parameters

Field	Description	Type
`entity.type`	The type of id used to create the communication profile. Accepted value: `UNIT`	String
`entity.id`	The unit ID used to create the communications profile.	String
`name`	Display name for the communication profile.	String
`profileId.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	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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

Response header

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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

Note: Multiple results in the returned array might occur when the sourceProfileId has multiple contacts for the alexaCommunicationProfileId.

{
    "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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	Phone number supported: US, UK, CA Phone number not supported: FR, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

Update a contact

Call PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} to update the metadata for a contact.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	Phone number supported: US, UK, CA Phone number not supported: FR, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

Response header

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

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.

Manage reciprocal associations for Inbound Calling

To allow an external contact to place an inbound call to an Alexa-enabled device associated with a property unit, it is necessary to add the external contact to the address book associated with the property unit and then create a reciprocal association for it.

Create a reciprocal association

Call POST /v1/communications/profile/{profileId}/reciprocalAssociations to create a reciprocal association between profileId of a property unit and contactId of an external contact to provide the external contact the ability to place inbound calls to devices associated with the property unit. This API call creates a communication profile for an entity (unit) as a contact in the addressBook of the external user identified by contactId and sends an Alexa message to the external user’s Alexa Companion app and Echo devices informing them that a reciprocal contact has been created.

As a prerequisite, first, the external contact has to be created and its contactId needs to be retrieved using Manage Contacts endpoint. The external contact must be created in the AddressBook which is associated with the property unit for which the reciprocal association is being created.

Once a reciprocal association has been successfully created for an external contact from a unit, the external contact can view the contact to the unit (e.g. room) in the contacts list on their Alexa-enabled device and Alexa Companion app. The external contact can place calls to the devices in the unit (e.g. room) using voice or on-screen controls on Echo the device screen. The external contact can block the unit (e.g. room) contact if they wish to. Messaging and Drop-In calling are not supported with the Inbound Calling feature.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US	US, UK, FR, CA, IT, DE	None

Request Format

*POST* /v1/communications/profile/{profileId}/reciprocalAssociations 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 for an entity. Generated when you created a communication profile for the first time.	String	Yes

Request Body

{
        "contact": {
            "id": "amzn1.alexa.contact.did.{contactId}"
        }
    }

Request Body Example

{
        "contact": {
            "id": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQD"
        }
    }

Request Body Parameters

Field	Description	Type	Required
`contact.id`	contactId of the external contact for which reciprocal contact will be created against profileId. ContactId has to be retrieved from the response to Create Contact endpoint when the external contact is created in the AddressBook associated to the property unit with profileId. The contact can have a phone number or a profileId. If a contact lists multiple phone numbers, then the reciprocal association will be attempted against all valid phone numbers. ContactId should be in the format `amzn1.alexa.contact.did.{contactId}`.	String	Yes

Response Header

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

{
    "profileId": "amzn1.alexa.communications.profile.did.{profileId}",
    "contactId": "amzn1.alexa.contact.did.{contactId}"
}

Response Body Example

{
    "profileId": "amzn1.alexa.communications.profile.did.AHJ6NDRSRIOBWBCRWDGXTGXTQE",
    "contactId": "amzn1.alexa.contact.did.AHXG6V247SZDZB6LXU6BYXYMJS3XI5"
}

Response Body Parameters

Field	Description	Type
`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
`contactId`	ContactId for which reciprocal contact will be created against profileId. ContactId is returned by Create Contact endpoint.	String

Error Response Body Format

{
    "message": "{errorMessage}"
}

Error Response Body Example

{
    "message": "Communication profileId is not valid"
}

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.

Note: If an AddressBook is associated to a unit and a reciprocal association is attempted immediately after it, you may see a 400 - Bad Request with the Reason (The AddressBook, in which contact is created, is not associated with entity for profileId). This is because AddressBook association propagation to unit happens asynchronously and can take several seconds. In such cases, retry the reciprocal association.

Note: If an external contact has multiple phone numbers listed in it, the API call will attempt to create reciprocal association with each valid phone number. API call will succeed if a reciprocal association is created for at least one phone number listed in the contact. Otherwise, it will fail. For phone numbers that already have a reciprocal association, a duplicate contact will not be created and a message will not be sent to external contact.

Get reciprocal association status

Call GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} to get reciprocal association status between profileId and contactId.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US	US, UK, FR, CA, IT, DE	None

Request Format

*GET */v1/communications/profile/{ownerProfileId}/reciprocalAssociations?contactId={contactId} 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 for an entity. Generated when you created a communication profile for the first time.	String	Yes

Request Query parameters

Field	Description	Type	Required
`contactId`	ContactId for which reciprocal association status against profileId will be retrieved. ContactId is returned by Create Contact endpoint.	String	Yes

Request Body

None.

Request Body Example

None.

Request Body Parameters

None.

Response Header

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

{
  "results": [
    {
      "contact": {
        "contactId": "amzn1.alexa.contact.{contactId}"
      },
      "status": "ENABLED|DISABLED"
    }
  ],
  "paginationContext": {
    "nextToken": "string"
  }
}

Response Body Example

{
  "results": [
    {
      "contact": {
        "contactId": "amzn1.alexa.contact.9ef21be8-ae5b-46ef-965e-4f8427fb308d"
      },
      "status": "ENABLED"
    }
  ],
  "paginationContext": {
    "nextToken": "null"
  }
}

Response Body Parameters

Field	Description	Type
`contactId`	ContactId for which reciprocal association status against profileId will be retrieved. ContactId is returned by Create Contact endpoint.	String
`status`	ENABLED if reciprocal relation exists between contactId and profileId else DISABLED. If an external contact has multiple phone numbers, API response will return ENABLED if any of the phone numbers listed in the contact have a reciprocal contact created for the unit, otherwise it will return DISABLED.	String
`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.

Error Response Body Format

{
    "message": "{errorMessage}"
}

Error Response Body Example

{
    "message": "Communication profileId is not valid"
}

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.
400	Bad Request	The `contactId` is not valid.
400	Bad Request	The contactId does not have any Amazon comms provisioned customers.
400	Bad Request	The AddressBook, in which contact is created, is not associated with entity for profileId.
401	Unauthorized	The LWA token is expired or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
403	Forbidden	The provided customer does not have access to this feature.
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 reciprocal association status

Call DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} to delete the reciprocal association between profileId and contactId. This API will remove entity (UNIT) as contact from contactId’s customer’s addressBook and will send an Alexa message to external user’s Alexa companion app and Echo devices informing them that the association has been deleted. The deletion of reciprocal association disables Inbound Calling for that external contact to that unit.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
None	None	US	US, UK, FR, CA, IT, DE	None

Request Format

*DELETE* /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} 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 for an entity. Generated when you created a communication profile for the first time.	String	Yes

Request Query parameters

Field	Description	Type	Required
`contactId`	ContactId for which reciprocal association status against profileId will be retrieved. ContactId is returned by Create Contact endpoint.	String	Yes

Request Body

None.

Request Body Example

None.

Request Body Parameters

None.

Response Header

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

Response Body

None.

Response Body Example

None.

Response Body Parameters

None.

Error Response Body Format

{
    "message": "{errorMessage}"
}

Error Response Body Example

{
    "message": "Communication profileId is not valid"
}

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.
400	Bad Request	The `contactId` is not valid.
400	Bad Request	The contactId does not have any Amazon comms provisioned customers.
400	Bad Request	The AddressBook, in which contact is created, is not associated with entity for profileId.
401	Unauthorized	The LWA token is expired or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
403	Forbidden	The provided customer does not have access to this feature.
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.

Note: When a contact is deleted, when an address book is disassociated from a unit (e.g. room), or when communication profile for a unit is deleted, all reciprocal associations created for associated units will be deleted automatically. In each of these cases, no message will be sent to external contact informing them. It is recommended to delete reciprocal associations for a given contact first before performing any of these actions.

Note: In cases where a contact has multiple phones numbers listed in it, deleting the reciprocal association will delete the reciprocal association for all valid phone numbers listed in the contact that have a reciprocal association. API will succeed if all such associations are deleted, else it will fail.

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"
Max number of phone numbers that can be associated with a unit	10	"You have reached the maximum number of phone numbers 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	35000	"You have reached maximum number of address books that you can create per organization: 35000"

Last updated: Mar 21, 2023