Self-Service Onboarding REST API Reference

Use the Self-Service Onboarding REST API to onboard and manage a communication provider for Alexa Smart Properties (ASP) Web Real-Time Communication (WebRTC) calling.

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 Self-Service Onboarding 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 Self-Service Onboarding API supports the following operations:

Operation HTTP method and URI

Create service provider

POST /v1/communications/serviceProviders

Delete service provider

DELETE /v1/communications/serviceProviders/{serviceProviderId}

Get service provider information

GET /v1/communications/serviceProviders/{serviceProviderId}

Update service provider

PUT /v1/communications/serviceProviders/{serviceProviderId}

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

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

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

String

Yes

Request body example

Copied to clipboard.

{
    "serviceProviderLogicalId" : "service.provider.logical.id.1",
    "displayName": [
       {
          "locale": "en-US",
          "value": "Example Service Provider"
       }
    ]
}

Request body properties

Property Description Type Required

serviceProviderLogicalId

Externally unique ID for the new service provider.
After you create the service provider, you can't modify this value.

String

Yes

displayName

Customer-facing name for the service provider.
At this time, the name is used for internal analytics.

Array of objects

No

displayname[].locale

Locale of the name.
Valid value: en

String

No

displayname[].value

Service provider name in the locale.

String

No

Response

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

Response body example

{
  "serviceProviderId": "amzn1.comms.csp.id.1",
  "serviceProviderLogicalId" : "service.provider.logical.id.1",
  "displayName": [
       {
          "locale": "en-US",
          "value": "Example Service Provider"
       }
    ]
}

Response body properties

Property Description Type

serviceProviderId

Internally generated unique identifier for the new service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

serviceProviderLogicalId

Externally unique identifier of the service provider.

String

displayName

Customer-facing name for the service provider.
At this time, the name is used for internal analytics.

Array of objects

displayname[].locale

Locale of the name.
Valid value: en

String

displayname[].value

Service provider name in the locale.

String

HTTP status codes

Status Description

201 Created

Service provider 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 serviceProviderLogicalID already exists.

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 service provider

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

Request path and header example

Copied to clipboard.

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

The request has no body.

Request body properties

The request has no body.

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

Service provider 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.

Get service provider information

Get detailed information about the specified 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 get service provider details, you make a GET request to the /v1/communications/serviceProviders/{serviceProviderId} resource.

Request path and header example

Copied to clipboard.

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

The request has no body.

Request body properties

The request has no body.

Response

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

Response body example

{

    "serviceProviderId": "amzn1.comms.csp.id.2",
    "serviceProviderLogicalId" : "service.provider.logical.id.1",
    "displayName": [
       {
          "locale": "en-US",
          "value": "Example Service Provider"
       }
    ]
}

Response body properties

Property Description Type

serviceProviderId

Internally generated unique identifier for the service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

serviceProviderLogicalId

Externally unique identifier of the service provider.

String

displayName

Customer-facing name for the service provider.

Array of objects

displayname[].locale

Locale of the name.
Valid value: en

String

displayname[].value

Service provider name in the locale.

String

HTTP status codes

Status Description

200 OK

Response body contains the service provider information.

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 service provider

Modify properties for an existing service provider, such as the display name. You can't modify the serviceProviderLogicalId.

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

Request path and header example

Copied to clipboard.

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

Copied to clipboard.

{
    "serviceProviderLogicalId" : "service.provider.logical.id.1",
    "displayName": [
       {
          "locale": "en-US",
          "value": "New service provider name"
       }
    ]
}

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

Locale of the name. This release supports en-US only.

String

No

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

Response body example

{
  "serviceProviderId": "amzn1.comms.csp.id.2",
  "serviceProviderLogicalId" : "service.provider.logical.id.1",
  "displayName": [
       {
          "locale": "en-US",
          "value": "New Service Provider Name"
       }
    ]
}

Response body properties

Property Description Type

serviceProviderId

Internally generated ID as a unique identifier for the created service provider.
Formatted as an Amazon Common Identifier (ACI), amzn1.comms.csp.id.{id}.

String

serviceProviderLogicalId

Externally unique identifier of the created service provider.

String

displayName

Customer-facing name for the service provider.

Array of objects

displayname[].locale

Locale of the name.
Valid value: en

String

displayname[].value

Service provider name in the locale.

String

HTTP status codes

Status Description

200 OK

The request succeeded.

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 Self-Service Onboarding 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