Self Service Onboarding API Reference for Alexa Smart Properties

Use the Self Service Onboarding API to onboard and manage a communication provider to the Alexa service for Alexa Smart Properties.

API endpoint

The endpoint of the Self Service Onboarding API is https://api.amazonalexa.com/v1/communications/serviceProviders.

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 on getting the access token, see Get an access token.

Operations

The API supports the following operations:

Operation HTTP method and URI

Create a service provider

POST /v1/communications/serviceProviders

Get the service provider information

GET /v1/communications/serviceProviders/{serviceProviderId}

Update a service provider

PUT /v1/communications/serviceProviders/{serviceProviderId}

Delete a service provider

DELETE /v1/communications/serviceProviders/{serviceProviderId}

Create a service provider

Create a new service provider.

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 a service provider, make a POST request to /v1/communications/serviceProviders.

Request path and header example

Copied to clipboard.

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

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

serviceProviderLogicalId

Unique ID for each service provider.

String

Yes

displayName

Customer facing name for the service provider. At this moment, it is used for internal analytics.

Array of objects

No

displayname[].locale

Accepted locale.This release supports en only.

String

No. The default is en.

displayname[].value

Customer facing name.

String

No

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

Property Description Type

serviceProviderId

Internally generated ID as a unique identifier for the created service provider.

String

serviceProviderLogicalId

Unique identifier of the created service provider.

String

displayname[].locale

Locale for the display name.

String

displayname[].value

Customer facing name.

String

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.

403 Forbidden

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

409 Conflict

The requested serviceProviderLogicalID already exists.

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.

503 Service Unavailable

The server is temporarily unavailable.

Get the service provider information

Get detailed service provider information for a specific service provider ID.

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 get details of a specific service provider ID, make a GET request to /v1/communications/serviceProviders/{serviceProviderId}.

Request path and header example

Copied to clipboard.

GET /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501 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

The unique service provider ID.

String

Yes

{access token}

Header

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

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

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

Property Description Type

serviceProviderId

Internally generated ID as a unique identifier for the created service provider.

String

serviceProviderLogicalId

Unique identifier of the created service provider.

String

displayname[].locale

Locale for the display name.

String

displayname[].value

Customer facing name.

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.

404 Not Found

The specified serviceProviderId 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.

503 Service Unavailable

The server is temporarily unavailable.

Update a service provider

Modify an existing service provider's properties, such as the display name. You can't modify the serviceProviderLogicalId after its creation.

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 a service provider's properties, make a PUT request to /v1/communications/serviceProviders/{serviceProviderId}.

Request path and header example

Copied to clipboard.

PUT /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501 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

serviceProviderLogicalId

Unique ID for each service provider. You can't modify this ID after its creation. This property is optional when updating a service provider but it is required when creating a service provider.

String

No

displayName

Customer facing name.

Array of objects

No

displayname[].locale

Accepted locale. This release supports en-US only.

String

No. The default is en.

displayname[].value

Customer facing name.

String

No

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

Property Description Type

serviceProviderId

Internally generated ID as a unique identifier for the created service provider.

String

displayname[].locale

Locale for the display name.

String

displayname[].value

Customer facing name.

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.

404 Not Found

The specified serviceProviderId 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.

503 Service Unavailable

The server is temporarily unavailable.

Delete a service provider

Delete a service provider ID.

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 a service provider ID, make a DELETE request to /v1/communications/serviceProviders/{serviceProviderId}.

Request path and header example

Copied to clipboard.

DELETE /v1/communications/serviceProviders/amzn1.comms.csp.id.eb56ddf4-a5bd-119c-be09-0242ac127501 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 for deletion.

String

Yes

access token

Header

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

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

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

503 Service Unavailable

The server is temporarily unavailable.

Was this page helpful?

Last updated: Nov 28, 2023