Account Association REST API Reference

Use the Account Association REST API to manage account associations between your service provider for Web Real-Time Communication (WebRTC) calling and endpoints on your Alexa Smart Properties (ASP) network.

To use this API, you must enable the WebRTC add-on subscription. For more details, see WebRTC Calling in Alexa Smart Properties.

API endpoint

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

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Access the Alexa Smart Properties REST APIs.

Access to consent information is based on the permission scopes enabled for your skill and granted by the customer. Include the following additional permission scope when you request an access token.

Permission scope Description

amazon_communication::service_provider

Allows your skill to access WebRTC calling.

Operations

The Account Association API supports the following operations.

Operation HTTP method and URI

Create account association

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

Delete account association

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

Query account association

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

Update account association

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

Create account association

Create an association between a specific Alexa communication profile and an endpoint on your network. You can create your communication profile by using the Create a communication profile operation.

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, you make a POST request to the /v1/communications/serviceProviders/{serviceProviderId}/externalUsers resource.

Request path and header example

Copied to clipboard.

POST /v1/communications/serviceProviders/{serviceProviderId}/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

Internal ID of the service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

{
  "externalUserId": "7201",
  "amazonId": "amzn1.alexa.communications.profile.did.1234",
  "amazonIdType": "communication-profile"
}

Request body properties

Property Description Type Required

externalUserId

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

  • Valid values: numbers, alphanumeric characters, or email.
  • Maximum length: 128 characters.
  • Don't use the following characters: ampersand (&), equal sign (=), question mark (?), comma (,), bracket (<>).

String

Yes

amazonId

Unique Amazon communication profile ID to attach to the association.
For details, see Create a communication profile.

String

Yes

amazonIdType

Describes the type of amazonId to use to establish the association.
Valid value: communication-profile.

String

Yes

Response

A successful response returns HTTP 201 Created. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

201 Created

Association created successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

409 Conflict

Requested AmazonId already exists and mapped to a different externalUserId.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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, you make a DELETE request to the /v1/communications/serviceProviders/{serviceProviderId}/externalUsers resource.

Request path and header example

Copied to clipboard.

DELETE /v1/communications/serviceProviders/{serviceProviderId}/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

Internal ID of the service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

{
  "externalUserId": "7201"
}

Request body properties

Property Description Type Required

externalUserId

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

  • Valid values: numbers, alphanumeric characters, or email.
  • Maximum length: 128 characters.
  • Don't use the following characters: ampersand (&), equal sign (=), question mark (?), comma (,), bracket (<>).

String

Yes

Response

A successful response returns HTTP 200 OK. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

Association deleted successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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, you make a POST request to the /v1/communications/serviceProviders/{serviceProviderId}/externalUsers/query resource.

Request path and header example

Copied to clipboard.

POST /v1/communications/serviceProviders/{serviceProviderId}/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

Internal ID of the service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

{
  "filters": {
        "externalUserIds": ["TestUserId@test.com"]
   }
}

Request body properties

Property Description Type Required

filters

Query filter to use to get account association details.

Object

Yes

externalUserIds

List of unique identifiers that represent endpoints in your network that can make or receive WebRTC calls. You can specified 1–30 IDs.

  • Valid values: numbers, alphanumeric characters, or email.
  • Maximum length: 128 characters.
  • Don't use the following characters: ampersand (&), equal sign (=), question mark (?), comma (,), bracket (<>).

Array of strings

No

paginationContext

Information about pagination.

Object

No

paginationContext.nextToken

Token from the previous response.
Include if iterating over a paginated response. If you don't provide this property, the response contains the first page of results.

String

No

paginationContext.maxResults

Maximum number of results to return in the response.
Valid values: 1–30. Default: 10.

Integer

No

Response

A successful response returns 200 OK, along with the list of account associations. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

{
  "paginationContext": {
    "totalCount": 1,
    "nextPageToken": "0"
  },
  "accountAssociations": [
    {
      "externalUserId": "TestUserId@test.com",
      "amazonId": "amzn1.alexa.communications.profile.did.1234",
      "amazonIdType": "communication-profile"
    }
  ]
}

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

Use this value in a subsequent request to get the next page of results.

String

accountAssociations

List of account associations.

Array of objects

accountAssociations[].externalUserId

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

String

accountAssociations[].amazonId

Amazon communication profile ID.

String

accountAssociations[].amazonIdType

Describes the type of amazonId to use to establish the association.
Valid value: communication-profile.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of associations based on the filter criteria in the request.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

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 association, you make a PUT request to the /v1/communications/serviceProviders/{serviceProviderId}/externalUsers resource.

Request path and header example

Copied to clipboard.

PUT /v1/communications/serviceProviders/{serviceProviderId}/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

Internal ID of the service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

Yes

access token

Header

Access token for the customer.
Set to an LWA token.

String

Yes

Request body example

{
  "externalUserId": "7201",
  "amazonId": "amzn1.alexa.communications.profile.did.ABC9876",
  "amazonIdType": "communication-profile"
}

Request body properties

Property Description Type Required

externalUserId

List of unique identifiers that represent endpoints in your network that can make or receive WebRTC calls.

  • Valid values: numbers, alphanumeric characters, or email.
  • Maximum length: 128 characters.
  • Don't use the following characters: ampersand (&), equal sign (=), question mark (?), comma (,), bracket (<>).

String

Yes

amazonId

Unique Amazon communication profile ID to attach to the association.
For details, see Create a communication profile.

String

Yes

amazonIdType

Describes the type of amazonId to use to establish the association.
Valid value: communication-profile.

String

Yes

Response

A successful response returns HTTP 200 OK. On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

200 OK

Update completed successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. You can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Object definitions

The Account Association API defines the following object definitions.

Error object

The Error object defines the error type and message included in the response when an error occurs.

The following example shows the response body.

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
Property Description Type

type

Type of error that occurred.
For specific error types, see the HTTP status code table for each operation.

String

message

Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.

String

Was this page helpful?

Last updated: Oct 31, 2024