Communications API


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

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.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

Set drop-in preference

PUT /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}

Get drop-in preference

GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}

Create blocking rule

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId}

Get blocking rule

GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}

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.

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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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": "Example Name"
}

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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": "Example name 1"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
            },
            "name": "Example name 2"
        }
    ]
}

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 coexist 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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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": "Example Name"
 }

Request body parameters

Field Description Type Required
name Display name for communication profile. For reciprocal contacts, 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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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": "Example Name",
    "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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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": "Example Name",
    "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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Property Name"
}

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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 Name"
        }

    ],
    "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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Property Name"
}

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Name"
}

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 can be an address book entry that represents a callable Alexa device or PSTN number. A contact can also be a WebRTC endpoint. You can create a contact with a phone number, or with a communication profile, or with a provider contact ID for WebRTC implementation.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Contact Name",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    }
}

Request body example with multiple phone numbers

{
    "contact": {
        "name": "Example Contact Name",
        "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 Contact Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

Request body format with a provider contact ID

To support skill-based WebRTC calling, you can create a contact by using a provider contact ID.


{
    "contact": {
        "name": "{contactName}",
        "providerContact": 
            {
                "id": "{providerID}"
            }
    }
}

Request body example with a provider contact ID


{
    "contact": {
        "name": "Example Contact Name",
        "providerContact": 
            {
                "id": "123f4567-f89b-14e3-a456-426614174322"
            }
    }
}

Request body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: Phone number isn't supported in France (fr-FR). String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes
providerContact.id The unique network address id that you create and own. 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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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": "Example Name 1",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
              "name": "Example Name 1",
              "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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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

{
    "results": [
        {
            "contactName": "Example Contact Name 1",
            "contactId": "amzn1.alexa.contact.did.AGNA6I63RJBIV7EFEL73AJEIUZ7XGKDCB7VYRO6JTLMHX72F2P4YX4ZVZNCWB3SZR5ZS5ETPJTCCHCTV2NV2XU66GCKSNGF54PZCBCUE"
        },
        {
            "contactName": "Example Contact Name 2",
            "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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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 Senior Living Core

US

Phone number supported: US, UK, CA, JP

Phone number not supported: FR, IT, DE, ES

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Contact Name",
        "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 Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

Response body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be in E.164 format. Up to three phone numbers can be added. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: The phoneNumbers object isn't returned in requests for France (fr-FR) accounts. String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or contact ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Update a contact

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

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

Phone number supported: US, UK, CA, JP

Phone number not supported: FR, IT, DE, ES

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Contact Name",
        "phoneNumbers": [
            {
                "number": "+16055554412"
            }
        ]
    }
}

Request body format with communication profile

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    }
}

Request body example with communication profile

{
    "contact": {
        "name": "Example Contact Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

Request body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: Phone number isn't supported in France (fr-FR). String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes

Response header

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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.<div markdown="span" class="alert alert-info" role="alert"> Note: In the response header, the returned Host value is the same as the Host value in the request.</div> 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.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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 Senior Living Core

None

JP

US, UK, FR, CA, IT, DE, ES, JP

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.
400 Bad Request The contact has not enabled Communications in their Alexa app. You can add only the contacts that are enabled with Alexa Communications.
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.

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 Senior Living Core

None

JP

US, UK, FR, CA, IT, DE, ES, JP

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 Senior Living Core

None

JP

US, UK, FR, CA, IT, DE, ES, JP

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.

Drop In

Use the Alexa Comms Preference APIs to manage drop-in preference for units such as rooms in Alexa Smart Properties. This preference is set using Alexa Communications Profiles rather than directly between Unit Ids.

Set Drop-in preference

To enable or disable drop-in from one Alexa Unit to another, the preference must be set. Enabling drop-in preference allows Alexa Unit linked with alexaCommunicationProfileId to drop in on Alexa Unit linked with SourceProfileId.

Call PUT /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId} to set drop-in preference.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

None

None

None

Request Format

PUT /v1/communications/profile/{SourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}  
HTTP/1.1 Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request Path Parameters

Field Description Type Required
sourceProfileId This indicates the profileId of the unit, on which the permission is being set for allowing/ disallowing the drop-in from target. The SourceProfileId will be in the format amzn1.alexa.communications.profile.did.{profileId} String Yes

Request query parameters

Field Description Type Required
alexaCommunicationProfileId This indicates the profileId of the target unit, which is being allowed/disallowed to drop in on source. The alexaCommunicationProfileId will be in the format amzn1.alexa.communications.profile.did.{profileId}. String Yes

Request Body

{    
    "value": "<Setting>"
}

Request Body Example

{
    "value": "ENABLED"
}

Request Body Parameters

Field Description Type Required
value Drop-in enablement status. Accepted Values: ENABLED/DISABLED String Yes

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
204 No Content Successful Request
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request profileId is not valid
400 Bad Request Allowed Values for DropIn SettingKey : [ENABLED, DISABLED]
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found Contact doesn't exist for given profileId.
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 Drop-in preference

To get the current state of drop-in permission from Alexa Unit to another. The preference API indicates who (source profile Id) allows permission for whom (target profile Id) to drop in.

Call GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId} to get all drop-in preferences that are set on a sourceProfileId.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

None

None

None

Request Format

GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}  
HTTP/1.1 Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request Path Parameters

Field Description Type Required
sourceProfileId This indicates the profileId of the unit, on which the permission is being set for allowing/ disallowing the drop-in from target. The SourceProfileId will be in the format amzn1.alexa.communications.profile.did.{profileId} String Yes

Request query parameters

Field Description Type Required
alexaCommunicationProfileId This indicates the profileId of the target unit, which is being allowed/disallowed to drop in on source. The alexaCommunicationProfileId will be in the format amzn1.alexa.communications.profile.did.{profileId}.
If this parameter is not provided, the API returns list of all the targets to whom drop-in permission has been allowed/disallowed from the sourceProfileId.
String No

Request Body

None.

Request Body Example

None.

Request Body Parameters

Field Description Type Required
value Drop-in enablement status. Accepted Values: ENABLED/DISABLED 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

{    
"results":
	[        
		{            
		"setting": "DropIn",            
		"contactId": "amzn1.alexa.contact.did.{ContactId}",
		"alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.{alexaCommunicationProfileId}",
		"value": "DISABLED"        
		}    
	],    
	"paginationContext": {
        "nextToken": "ABC1234"    }
}

Response Body Example

{    
	"results": [        
	{            
		"setting": "DropIn",            
		"contactId": "amzn1.alexa.contact.did.AFVHJW5XQ7ZC4ASMKV4G3L24RD62VCTFTVQB5EGQ",        "alexaCommunicationProfileId": 	"amzn1.alexa.communications.profile.did.AFXVPXWQNVIBZSXTI",            		        
        "value": "DISABLED"        
	}    
	],    
	"paginationContext": {
	       "nextToken": null    
	}
}

Response Body Parameters

Field Description Type Required
'setting' Constant Value “DropIn” String Yes
'contactID' The contact that is being allowed/ disallowed to the drop-in String Yes
alexaCommunicationProfileId This is Communications Profile which is being allowed/ disallowed to drop in on source. This will be in the format amzn1.alexa.communications.profile.did.{profileId}. String Yes
value Indicates the current status of Drop-in preference. The value is either ENABLED or DISABLED. String Yes

Error Response Body Format

{
    "message": "{errorMessage}"
}

Error Response Body Example

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

HTTP response codes

Status Code Description Reason
200 OK Success
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request Allowed Values for DropIn SettingKey : [ENABLED, DISABLED]
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 The sourceProfileId does not have the alexaCommunicationProfileId as a contact.
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.

Block

You can create blocking rules to disable calling and messaging between two property units.

Create blocking rule

Creates a blocking rule to disable calling and messaging between two property units.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US

US

US

Request

To create a blocking rule, you make a PUT request to the /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId} resource.

This request blocks the alexaCommunicationProfileId unit from calling the profileId unit. However, the profileId unit can still call the alexaCommunicationProfileId unit.

Request header example

Copied to clipboard.

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request header and path parameters
Parameter Located in Description Type Required

access token

Header

LWA access token.

String

Yes

profileId

Path

Communication profile ID of the unit that will no longer receive calls from the alexaCommunicationProfileId unit.

String

Yes

alexaCommunicationProfileId

Query

Communication profile ID of the unit that you want to block from calling the profileId unit.

String

No

Request body example

Copied to clipboard.

{
   "value" : "ENABLED"
}
Request body parameters
Parameter Description Type Required

value

Block setting value. Allowed values: ENABLED to block communications or DISABLED to enable communications.

String

Yes

Response

A successful response returns HTTP 204.

Response body example

The successful response has no body.

The following example shows the body of a possible error response.

{
    "message": "Source and Target CommunicationProfileId cannot be the same."
}
Response body parameters

The successful response has no body.

The error response contains the following parameters.

Parameter Description Type

message

Description of the error.

String

HTTP status codes
Status Description

204 No content

The request succeeded.

400 Bad Request

The request is missing one or more required parameters, or the parameter values aren't valid. Examples:


  • The specified profileId isn't valid.
  • The specified block value isn't either ENABLED or DISABLED.
  • The source and target communication profile IDs can't be the same. That is, profileId can't be the same as alexaCommunicationProfileId.

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The request couldn't complete because you don't have permission to perform the operation.

404 Not Found

The contact doesn't exist for the given profileId.

429 Too Many Requests

You have exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

A server-side error occurred.

503 Service Unavailable

The service is currently unavailable to handle the request.

Get blocking rule

Gets a blocking rule that enables or disables calling and messaging between two property units.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US

US

US

Request

To get a blocking rule, you make a GET request to the /v1/communications/profile/{profileId}/contacts/settings/Block?value={value} resource.

Request header example

Copied to clipboard.

GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}&alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request header and path parameters
Parameter Located in Description Type Required

access token

Header

LWA access token.

String

Yes

profileId

Path

Communication profile ID of the unit for which to get a blocking rule.

String

Yes

value

Query

Block setting value. Allowed values: ENABLED to block communications or DISABLED to enable communications.

String

No

alexaCommunicationProfileId

Query

Unique identifier for the target communication profile, in the form amzn1.alexa.communications.profile.did.{profileId}. If you provide this parameter, the response contains the settings for only this target.

String

No

nextToken

Query

Token to retrieve a specific page of the paginated results. If this token isn't present, the response contains the first page of results.

String

No

maxResults

Query

Maximum number of results to return in the response body. This value must be greater than zero and less than or equal to 100. The default value is 100. These values might change.

Number

No

Request body example

The request has no body.

Request body parameters

The request has no body.

Response

A successful response returns HTTP 200.

Response body example

The following example shows the body of a successful response.

{
  "results": [
    {
      "setting": "Block",
      "contactId": "{contactId}",
      "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.{profileId}",
      "value": "ENABLED"
    },
    {
      "setting": "Block",
      "contactId": "{contactId}",
      "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.{profileId}",
      "value": "ENABLED"
    }
  ],
  "paginationContext": {
     "nextToken": "String"
  }
}

The following example shows the body of a possible error response.

{
    "message": "Source and Target CommunicationProfileId cannot be the same."
}

Successful response body parameters

Parameter Description Type

results

List of blocking rule objects.

Array of objects

results[*].setting

The setting retrieved. The value is Block.

String

results[*].contactId

Contact ID, in the format amzn1.alexa.contacts.did.{id}.

String

results[*].alexaCommunicationProfileId

Unique identifier for the target communication profile, in the form amzn1.alexa.communications.profile.did.{profileId}.

String

results[*].value

Block setting value. Allowed values: ENABLED to block communications or DISABLED to enable communications.

String

paginationContext

Pagination details.

Object

paginationContext.nextToken

Token to retrieve a specific page of the pagination results.

String

Error response body parameters

Parameter Description Type

message

Description of the error.

String

HTTP status codes
Status Description

200 Success

The request succeeded.

400 Bad Request

The request is missing one or more required parameters, or the parameter values aren't valid. Examples:


  • The source and target communication profile IDs can't be the same. That is, profileId can't be the same as alexaCommunicationProfileId.
  • The alexaCommunicationProfileId must be passed as query parameter.

401 Unauthorized

Authorization token is invalid, expired, or doesn't have access to the resource.

403 Forbidden

The request couldn't complete because you don't have permission to perform the operation or permission to access this feature.

404 Not Found

The profileId doesn't have the alexaCommunicationProfileId as a contact.

429 Too Many Requests

You have exceeded the permitted rate limit (specified number of requests per unit of time).

500 Internal Server Error

A server-side error occurred.

503 Service Unavailable

The service is currently unavailable to handle the request.

Resource limits

Resource Default Error message on exceeding the limit

Maximum number of contacts allowed in an address book

2000

"You have reached the maximum number of contacts that can be created per address book: 2000"

Maximum number of address books that can be associated with a unit

10

"You have reached the maximum number of address books that can be associated with a unit: 10"

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"


Was this page helpful?

Last updated: Feb 13, 2024