Service Provider Network Mapping API Reference for Alexa Smart Properties

Use the Service Provider Network Mapping API to add, modify, update, or delete service provider network entity mapping for Alexa Smart Properties.

API endpoint

The endpoint of the Service Provider Network Mapping API is https://api.amazonalexa.com/v1/communications/serviceProviders/{serviceProviderId}/network.

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 how to get the access token, see Get an access token.

Operations

The API supports the following operations.

Operation HTTP method and URI

Create network mapping

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

Get network mapping

GET /v1/communications/serviceProviders/{serviceProviderId}/network

Update network mapping

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

Delete network mapping

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

Create network mapping

After you create a service provider by using the Self Service Onboarding API, you can create network elements mapping. For skill-based WebRTC calling, you map the skillID with the serviceProviderId.

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 network mapping, make a POST request to /v1/communications/serviceProviders/{serviceProviderId}/network.

Request path and header example

Copied to clipboard.

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

Request body properties

Property Description Type Required

networkType

For WebRTC skill-based calling, set the value to SKILL.

String

Yes

skillConfiguration

Skill configuration details

Object

Yes

skillConfiguration.skillId

Skill Id that you want to map your service provider ID with.

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

Property Description Type

status

Request status. Possible value:
  • ACTIVE: The skill is linked with the service provider ID.

Enum

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 network mapping was already created earlier.

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 network mapping

Get all the details of the service provider network entity mapping 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 about a specific service provider ID, make a GET request to /v1/communications/serviceProviders/{serviceProviderId}/network.

Request path and header example

Copied to clipboard.

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

networkType

SKILL means that this is a skill-based network mapping with a service provider ID.

String

skillConfiguration.skillId

Skill ID mapped with the specified service provider ID.

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 network mapping 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 network mapping

Modify an existing service provider ID mapping.

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}/network.

Request path and header example

Copied to clipboard.

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

networkType

For WebRTC skill-based calling, set the value to SKILL.

String

Yes

skillConfiguration

Skill configuration details.

Object

Yes

skillConfiguration.skillId

New skill ID that you want to map your service provider ID with.

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

Property Description Type

networkType

SKILL means that this is a skill-based network mapping with a service provider ID.

String

status

Request status. Possible value:
  • ACTIVE: The skill is linked with the service provider ID.

Enum

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 network mapping isn't found.

409 Conflict

After creation, you can't change the networkType.If you attempt to change the networkType after its creation, you get the 409 Conflict error.

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 network mapping

Delete an existing mapping between a service provider ID and a skill 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}/network.

Request path and header example

Copied to clipboard.

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