Account Association API Reference for Alexa Smart Properties

Use the Account Association API to create, update, delete, or query account associations between Alexa and endpoints on your network for Alexa Smart Properties.

API endpoint

The endpoint of the Account Association API is https://api.amazonalexa.com/v1/communications/serviceProviders/{serviceProviderId}/externalUsers.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). The LWA scope to use here is amazon_communication::service_provider. For details about getting the access token, see Get an access token.

Operations

The API supports the following operations.

Operation HTTP method and URI

Create account association

POST /v1/communications/serviceProviders/{serviceProviderId}/externalUsers

Update account association

PUT /v1/communications/serviceProviders/{serviceProviderId}/externalUsers

Delete account association

DELETE /v1/communications/serviceProviders/{serviceProviderId}/externalUsers

Query account association

POST /v1/communications/serviceProviders/{serviceProviderId}/externalUsers/query

Create account association

Before you create any account association, you must first enable the Web Real-Time Communication (WebRTC) add-on subscription skill. For details, see Step 6: enable WebRTC subscription on unit.

Create an association between a specific Alexa communication profile and an endpoint on your network.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, IT, DE, ES

US, UK, FR, IT, DE, ES

US

Request

To create an account association, make a POST request to /v1/communications/serviceProviders/{serviceProviderId}/externalUsers.

Request path and header example

Copied to clipboard.

POST /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501/externalUsers HTTP/1.1
Host: api.amazonalexa.com
Content-type: application/json  
Authorization:  Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

serviceProviderId

Path

Unique ID for a service provider.

String

Yes

access token

Header

Login with Amazon (LWA) token. For details, see Get an Access Token for SMAPI.

String

Yes

Request body example

Request body properties

Property Description Type Required

externalUserId

Unique identifier representing an endpoint in your WebRTC system that can make or receive calls. It can be numbers, alphanumeric characters, or email. It must be no more than 128 characters. It doesn't accept ampersands(&), equal signs(=), question marks(?), commas(,), or brackets(<>).

String

Yes

amazonId

Unique Amazon communication profile ID to attach the association with when amazonIdType=communication-profile. You can create your communication profile by using the Create a communication profile operation.

String

Yes

amazonIdType

Type of amazonID for establishing association between an Alexa identifier and an endpoint on your network. Acceptable value: communication-profile.

String

Yes

Response

A successful response returns HTTP 201 Created, along with the status of the target. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. For details, see HTTP status codes.

Response body example

Response body properties

The response has no body.

HTTP status codes

Status Description

201 Created

The request succeeded.

400 Bad Request

A required parameter isn't present or is incorrectly formatted.

401 Unauthorized

The access token is missing or expired.

409 Conflict

The specified AmazonId is already mapped to a different externalUserId.

403 Forbidden

You don't have permission to perform the operation or the authentication token is invalid.

429 Too Many Requests

You made more API calls than the allowed limit.

500 Internal Server Error

An internal service error caused the request failure.

Update account association

Update an existing endpoint with a new Alexa communication profile.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, IT, DE, ES

US, UK, FR, IT, DE, ES

US

Request

To update an existing user with a new profile, make a PUT request to /v1/communications/serviceProviders/{serviceProviderId}/externalUsers.

Request path and header example

Copied to clipboard.

PUT /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501/externalUsers HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization:  Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

serviceProviderId

Path

Unique ID for a service provider.

String

Yes

access token

Header

Login with Amazon (LWA) token. For details, see Get an Access Token for SMAPI.

String

Yes

Request body example

Request body properties

Property Description Type Required

externalUserId

Unique identifier representing an endpoint in your WebRTC system that can make or receive calls. It can be numbers, alphanumeric characters, or email. It must be no more than 128 characters. It doesn't accept ampersands(&), equal signs(=), question marks(?), commas(,), or brackets(<>).

String

Yes

amazonId

Unique Amazon communication profile ID to attach the association with when amazonIdType=communication-profile. You can create your communication profile by using the Create a communication profile operation.

String

Yes

amazonIdType

Type of acceptable amazonID. Acceptable value: communication-profile.

String

Yes

Response

A successful response returns HTTP 200 OK, along with the status of the target. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. For details, see HTTP status codes.

Response body example

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

The request succeeded.

400 Bad Request

A required parameter isn't present or is incorrectly formatted.

401 Unauthorized

The access token is missing or expired.

403 Forbidden

You don't have permission to perform the operation or the authentication token is invalid.

404 Not Found

The specified account association isn't found.

429 Too Many Requests

You made more API calls than the allowed limit.

500 Internal Server Error

An internal service error caused the request failure.

Delete account association

Delete the association between an Alexa communication profile and an endpoint on your network.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, IT, DE, ES

US, UK, FR, IT, DE, ES

US

Request

To delete an association between an existing linked account and serviceProviderId, make a DELETE request to /v1/communications/serviceProviders/{serviceProviderId}/externalUsers.

Request path and header example

Copied to clipboard.

DELETE /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501/externalUsers HTTP/1.1
Host: api.amazonalexa.com
Content-type: application/json  
Authorization:  Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

serviceProviderId

Path

Unique identifier of the service provider.

String

Yes

access token

Header

Login with Amazon (LWA) token. For details, see Get an Access Token for SMAPI.

String

Yes

Request body example

Request body properties

Property Description Type Required

externalUserId

Unique identifier representing an endpoint in your WebRTC system that can make or receive calls. It can be numbers, alphanumeric characters, or email. It must be no more than 128 characters. It doesn't accept ampersands(&), equal signs(=), question marks(?), commas(,), or brackets(<>).

String

Yes

Response

A successful response returns HTTP 200 OK, along with the status of the target. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. For details, see HTTP status codes.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

The request succeeded.

400 Bad Request

A required parameter isn't present or is incorrectly formatted.

401 Unauthorized

The access token is missing or expired.

403 Forbidden

You don't have permission to perform the operation or the authentication token is invalid.

404 Not Found

The specified account association isn't found.

429 Too Many Requests

You made more API calls than the allowed limit.

500 Internal Server Error

An internal service error caused the request failure.

Query account association

Return association details for the specified query filter.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, IT, DE, ES

US, UK, FR, IT, DE, ES

US

Request

To query account association, make a POST request to /v1/communications/serviceProviders/{serviceProviderId}/externalUsers/query.

Request path and header example

Copied to clipboard.

POST /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501/externalUsers/query HTTP/1.1
Host: api.amazonalexa.com
Content-type: application/json  
Authorization:  Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

serviceProviderId

Path

Unique identifier of the service provider.

String

Yes

access token

Header

Login with Amazon (LWA) token. For details, see Get an Access Token for SMAPI.

String

Yes

Request body example

Request body properties

Property Description Type Required

filters

Query filter to retrieve account association details.

Object

Yes

externalUserIds

List of unique identifiers representing endpoints in your WebRTC system that can make or receive calls.

Array of strings

No

paginationContext

Information about pagination.

Object

No

paginationContext.nextToken

You provide this token when requesting the next page for the previous result. If you don't provide this property, then the system considers your request is the first one.

String

No

paginationContext.maxResults

Maximum number of items to be returned. The maximum value is 30.

Number

No (Default to 10)

Response

A successful response returns 200 OK, along with the status of the target. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. For details, see HTTP status codes.

Response body example

Response body properties

Property Description Type

paginationContext

Information about pagination.

Object

paginationContext.totalCount

Total number of user IDs associated with the account.

Number

paginationContext.nextPageToken

Starting pointer of the current query. You can use this string for future associations to a customized pagination.

String

accountAssociations[]

List of account association details.

Array of objects

accountAssociations[].externalUserId

Unique identifier representing an endpoint in your WebRTC system that can make or receive calls.

String

accountAssociations[].amazonId

Amazon communication profile ID.

String

accountAssociations[].amazonIdType

Possible value: communication-profile.

String

HTTP status codes

Status Description

200 OK

The request succeeded.

400 Bad Request

A required parameter isn't present or is incorrectly formatted.

401 Unauthorized

The access token is missing or expired.

403 Forbidden

You don't have permission to perform the operation or the authentication token is invalid.

429 Too Many Requests

You made more API calls than the allowed limit.

500 Internal Server Error

An internal service error caused the request failure.

Was this page helpful?

Last updated: Nov 28, 2023