Skill Management API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. See Get Started with Alexa Smart Properties APIs.

Use the Skill Management API to manage skills for Alexa Smart Properties units such as rooms.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country	Endpoint
CA, US	`https://api.amazonalexa.com`
DE, ES, FR, IT, UK	`https://api.eu.amazonalexa.com`
JP	`https://api.fe.amazonalexa.com`

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Skill Management API includes the following operations.

Description	HTTP method and path
Get a skill enablement record for a unit	`GET /v1/skills/{skillId}/enablements?unitId={unitId}`
List skill enablements for a unit	`GET /v1/skills/enablements?unitId={unitId}`
Get skill enablement for multiple units	`POST /v1/skills/enablements/batchGet`
Enable a skill for a unit	`POST /v1/skills/{skillId}/enablements`
Disable a skill for a unit	`DELETE /v1/skills/{skillId}/enablements?unitId={unitId}`
Enable a skill for multiple units	`POST /v1/skills/{skillId}/enablements/batch`
Disable a skill for multiple units	`POST /v1/skills/{skillId}/enablements/batchDelete`

Get skill enablements

The following operations allow you to get information about a skills enabled on a unit or multiple units.

Get a skill enablement record for a unit

Call GET /v1/skills/{skillId}/enablements?unitId={unitId} to get the skill enablement record for a specific skill for a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format examples

List skill enablement and account linking details only

The following example lists the skill enablement record for the unit. By default, the results aren't expanded with name-free interaction details.

This call only returns the enablement record for a given skill. To get all skill enablements for a unit, see List skill enablements for a unit.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Include name-free interaction details

This example shows how to include the name-free interaction details for the enablement, use the expand=nameFreeInvocation parameter.

Note: This functionality is only available for Alexa Smart Properties property skills. See Add Name-Free Interaction to Alexa Smart Properties Skills.

GET /v1/skills/{skillId}/enablements?unitId={unitId}&expand=nameFreeInvocation HTTP/1.1

Request body

None.

Request path parameters

Field	Description	Type	Required
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request query parameters

Field	Description	Type	Required
`unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `nameFreeInvocation`	String	No

Success response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Response body parameters

Field	Description	Type
`skill.stage`	Skill stage: `development` or `live`.	Enum
`skill.id`	Unique identifier for a skill.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	Current account linking status between the user's Amazon account and their account in your service: `LINKED` or `NOT_LINKED`. For skills that don't support account linking, `NOT_LINKED` is returned.	String
`status`	Skill enablement status: `ENABLING` or `ENABLED`.	Enum
`nameFreeInvocation.status`	Name-free interaction enablement status: `DISABLED` or `ENABLED`. For skills that don't support name-free interaction, `DISABLED` is returned.	Enum
`nameFreeInvocation.locales`	Available locales for name-free interaction on the unit: `en-US`, `es-US`, `en-CA`, `fr-CA`, `en-GB`, `fr-FR`, `es-ES`, `it-IT`, `de-DE`. This value is only returned if `nameFreeInvocation.status` is `ENABLED`. Limit of 5 locales.	Array

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type
`type`	Error type.	String
`message`	Error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The operator doesn't have the right permission to perform the operation.
404	Not found	The requested skill ID or unit ID can't be found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
500	Internal Server Error	The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.
503	Service Unavailable	The server is temporarily unavailable.
503	Service Unavailable	The server is temporarily unavailable for fetching NameFreeInvocation.

List skill enablements for a unit

Call GET /v1/skills/enablements?unitId={unitId} to get a list of all skill enablements for a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format examples

List skill enablement and account linking details only

The following example lists all skill enablement records for a unit. By default, the results aren't expanded with name-free interaction details.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Include name-free interaction details

This example shows how to include the name-free interaction details for each skill enablement record, use the expand=nameFreeInvocation parameter.

Note: This functionality is only available for Alexa Smart Properties property skills. See Add Name-Free Interaction to Alexa Smart Properties Skills.

/v1/skills/enablements?unitId={unitId}&maxResults={maxResults}&expand=nameFreeInvocation&nextToken={nextToken} HTTP/1.1

Request body

None.

Request query parameters

Field	Description	Type	Required
`unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`nextToken`	Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results.	String	No
`maxResults`	Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10.	Integer	No
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `nameFreeInvocation`	String	No

Success response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Response body parameters

Field	Description	Type
`paginationContext`	Context that contains all data needed to control pagination.	Object
`paginationContext.nextToken`	Token used to retrieve subsequent data. This token doesn't exist if there are no extra records.	String
`items`	List of skill enablements.	List (Set)
`skill.stage`	Skill stage: `development` or `live`.	Enum
`skill.id`	Unique identifier for a skill.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	Current account linking status between the user's Amazon account and their account in your service: `LINKED` or `NOT_LINKED`. For skills that don't support account linking, `NOT_LINKED` is returned.	String
`status`	Skill enablement status: `ENABLING` or `ENABLED`.	Enum
`nameFreeInvocation.status`	Name-free interaction enablement status: `DISABLED` or `ENABLED`. For skills that don't support name-free interaction, `DISABLED` is returned.	Enum
`nameFreeInvocation.locales`	Available locales for name-free interaction on the unit: `en-US`, `es-US`, `en-CA`, `fr-CA`, `en-GB`, `fr-FR`, `es-ES`, `it-IT`, `de-DE`. This value is only returned if `nameFreeInvocation.status` is `ENABLED`. Limit of 5 locales.	Array

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type
`type`	Error type.	String
`message`	Error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The operator doesn't have the right permission to perform the operation.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
500	Internal Server Error	The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.
503	Service Unavailable	The server is temporarily unavailable.
503	Service Unavailable	The server is temporarily unavailable for fetching NameFreeInvocation.

Get skill enablement for multiple units

Call POST /v1/skills/enablements/batchGet to get the skill enablement for multiple units in a single request.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format examples

List skill enablement and account linking details only

The following example lists all skill enablement records for a single skill across multiple units. By default, the results aren't expanded with name-free interaction details.

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/enablements/batchGet HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

{
    "paginationContext": {
           "nextToken": "paginationTokenString"
     },
    "results": [
        {
            "itemId": 0,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLED"
                },
                {
                    "skill": {
                        "stage": "development",
                        "id": "amzn1.ask.skill.skillId2"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 1,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLING"
                },
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId2"
                    },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 3,
            "enablements": [
            ]
        }
    ],
    "errors": [  
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]    
}

Include name-free interaction details

This example shows how to include the name-free interaction details for each skill enablement record, use the expand=nameFreeInvocation parameter.

Note: This functionality is only available for Alexa Smart Properties property skills. See Add Name-Free Interaction to Alexa Smart Properties Skills.

{
    "paginationContext": {
           "nextToken": "paginationTokenString"
     },
    "results": [
        {
            "itemId": 0,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLED",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["en-US"]
                    }
                },
                {
                    "skill": {
                        "stage": "development",
                        "id": "amzn1.ask.skill.skillId2"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["en-US"]
                    }
                }
            ]
        },
        {
            "itemId": 1,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLING",
                    "nameFreeInvocation": {
                        "status": "DISABLED"
                    }
                },
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId2"
                    },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED",
                    "nameFreeInvocation": {
                        "status": "ENABLED",
                        "locales": ["en-US"]
                    }
                }
            ]
        },
        {
            "itemId": 3,
            "enablements": [
            ]
        }
    ],
    "errors": [  
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]    
}

Request path parameters

The request path has no parameters.

Request body example

The following example shows the body of a request to get the skill enablement for four units.

Request body parameters

Field	Description	Type	Required
`paginationContext`	Context that contains all data needed to control pagination.	Object	No
`paginationContext.maxResults`	Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10.	Integer	No
`paginationContext.nextToken`	Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results.	String	No
`items`	List of request items. Each item represents a single unit.	Array	Yes
`items[*].itemId`	Unique identifier for the request item. Must be unique within the request.	Integer	Yes
`items[*].unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`expand`	An attribute (or set of attributes) to include in the response. Current values supported: `nameFreeInvocation`	Array	Yes

Success response

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Response body example

{
    "paginationContext": {
           "nextToken": "paginationTokenString"
     },
    "results": [
        {
            "itemId": 0,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLED"
                },
                {
                    "skill": {
                        "stage": "development",
                        "id": "amzn1.ask.skill.skillId2"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 1,
            "enablements": [
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId1"
                     },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "NOT_LINKED"
                    },
                    "status": "ENABLING"
                },
                {
                    "skill": {
                        "stage": "live",
                        "id": "amzn1.ask.skill.skillId2"
                    },
                    "unit": {
                        "id": "amzn1.alexa.unit.unitId2"
                    },
                    "accountLink": {
                        "status": "LINKED"
                    },
                    "status": "ENABLED"
                }
            ]
        },
        {
            "itemId": 3,
            "enablements": [
            ]
        }
    ],
    "errors": [  
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]    
}

Response body parameters

Field	Description	Type
`paginationContext`	Context that contains all data needed to control pagination.	Object
`paginationContext.nextToken`	Token used to retrieve subsequent data. This token doesn't exist if there are no extra records.	String
`results`	List of skill enablements.	List (Set)
`results[*].itemId`	A unique identifier for the request item. You specified this value in the request.	Integer
`results[*].enablements`	List of enablements for the skill.	List (Set)
`results[].enablements[].skill`	Skill stage and ID.	Object
`results[].enablements[].skill.stage`	Skill stage: `development`, `certification`, or `live`.	Enum
`results[].enablements[].skill.id`	Unique identifier for a skill.	String
`results[].enablements[].unit`	Unique identifier for the unit.	String
`results[].enablements[].unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`results[].enablements[].accountLink`	Current account linking status between the user's Amazon account and their account in your service.	Object
`results[].enablements[].accountLink.status`	Account linking status: `LINKED` or `NOT_LINKED`. For skills that don't support account linking, `NOT_LINKED` is returned.	String
`results[].enablements[].status`	Skill enablement status: `ENABLING` or `ENABLED`.	Enum
`results[].enablements[].nameFreeInvocation.status`	Name-free interaction enablement status: `DISABLED` or `ENABLED`. For skills that don't support name-free interaction, `DISABLED` is returned.	Enum
`results[].enablements[].nameFreeInvocation.locales`	Available locales for name-free interaction on the unit: `en-US`, `es-US`, `en-CA`, `fr-CA`, `en-GB`, `fr-FR`, `es-ES`, `it-IT`, `de-DE`. This value is only returned if `nameFreeInvocation.status` is `ENABLED`. Limit of 5 locales.	Array

Error response header

HTTP/1.1 {ErrorCode}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response body example

The following example shows an error response body.

{
    "errors": [
        {
            "itemId": 0,
            "status": 401,
            "errorCode": "UNAUTHENTICATED",
            "errorDescription": "The access token is invalid."
        }
    ]
}

Error response parameters

Field	Description	Type
`errors`	A list of error responses, one for each request item.	Array
`errors[*].itemId`	The identifier for the request item. Optional if the error response is for the entire request and not for individual items.	String
`errors[*].status`	The response status code per request or request item.	Integer
`errors[*].errorCode`	The error code for the error.	Enum
`errors[*].errorDescription`	A description of the error.	String

HTTP response codes

Status Code	Name	Description
200	Accepted	The request was accepted. If a request is successful (even if only partially), the API returns a 200 status code with a response body that lists the enablements for each unit. If a unit doesn't have any enablements, the response contains an empty array for the associated `itemId`.
400	INVALID_PARAM	The request has a missing or invalid parameter.
400	BAD_REQUEST	The number of request items exceeds the limit.
401	UNAUTHENTICATED	The access token is missing, expired, or invalid.
403	FORBIDDEN	The operator doesn't have the right permission to perform the operation.
429	TOO_MANY_REQUESTS	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
500	Internal Server Error	The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.
503	Service Unavailable	The server is temporarily unavailable.
503	Service Unavailable	The server is temporarily unavailable for fetching NameFreeInvocation.

Enable skills

The following operations allow you to enable a skill on one or multiple units.

Enable a skill for a unit

Call POST /v1/skills/{skillId}/enablements to enable a skill for a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/{skillId}/enablements HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request body examples

Enable skill without account linking or name-free interaction

The following example shows a basic skill enablement on a unit without additional details such as account linking or name-free interaction.

Request body example

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live"
}

Enable skill with account linking

The following example shows a skill enablement on a unit with account linking using partitions.

Request body example

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "partitionName": "Room101-Kitchenette",
  "accountLinkRequest": {
    "redirectUri": "https://example.com",
    "authCode": "3pauthcode",
    "type": "AUTH_CODE"
  }
}

Enable skill with name-free interaction

The following example shows a skill enablement on a unit with name-free interaction.

Note: This functionality is only available for Alexa Smart Properties property skills. See Add Name-Free Interaction to Alexa Smart Properties Skills.

Request body example

{
  "unitId": "amzn1.alexa.unit.unitId",
  "stage": "live",
  "nameFreeInvocationRequest": {
      "locales" : ["en-US"]
  }
}

Request body parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`stage`	Skill stage: `development` or `live`.	Enum	Yes
`partitionName`	A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names. A partition name is a single nonempty string that can contain alphanumeric characters and hyphens but not whitespace. For example, "Room-101" and "Room101, Room202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace). Note: If there is an existing enablement for a given `skillId` and `unitId`, a `POST` enablement request for the same `skillId` and `unitId` with a different `partitionName` value (new, updated, or none) updates the existing enablement with the latest `partitionName` value. Note: If you provide both `accountLinkRequest` and `partitionName` in a `POST` enablement request for an existing enablement, the API call updates the existing account linking and the partition name.	String	No
`accountLinkRequest`	Account linking request information, as an AccountLinkRequest object.	Object	Yes, for skills that require account linking
`nameFreeInvocationRequest`	Name-free interaction request information, as an NameFreeInvocationRequest object.	Object	No. Only available for skills that support name-free interaction

AccountLinkRequest object schema

Field	Description	Type	Required
`redirectUri`	The `redirect_uri` parameter that was included in the authorization request to your OAuth 2.0 server to obtain the user's authorization code. This enables Amazon to retrieve access tokens from your token server. This URL must be opaque to Amazon.	String	Yes
`authCode`	An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow.	String	Yes
`type`	The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Currently the only supported value is `AUTH_CODE`.	String	Yes

NameFreeInvocationRequest object schema

Field	Description	Type	Required
`locales`	The locales that for the unit that should be enabled for name-free interaction. The skill must have an interaction model that supports the locale. Supported values: `en-US`, `es-US`,`en-CA`,`fr-CA`,`en-GB`,`fr-FR`,`it-IT`,`de-DE`,`es-ES`. Limit of 5 locales.	String	Yes

Success response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Response body example

{
  "skill": {
    "stage": "stage",
    "id": "{skillId}"
  },
  "unit": {
    "id": "{unitId}"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "nameFreeInvocation": {
    "status": "ENABLED",
    "locales": ["en-US"]
  },
  "status": "ENABLING",
}

Response body parameters

Field	Description	Type
`skill.stage`	Skill stage: `development` or `live`.	Enum
`skill.id`	Unique identifier for a skill, in the format `"amzn1.ask.skill.{id}"`.	String
`unit.id`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String
`accountLink.status`	Current account linking status between the user's Amazon account and their account in your service: `LINKED` or `NOT_LINKED`. The `accountLink` object is present only for skills that support account linking.	String
`status`	Skill enablement status: `ENABLING` or `ENABLED`.	Enum
`nameFreeInvocation.status`	Name-free interaction enablement status: `DISABLED` or `ENABLED`. For skills that don't support name-free interaction, `DISABLED` is returned.	Enum
`nameFreeInvocation.locales`	Available locales for name-free interaction on the unit: `en-US`, `es-US`, `en-CA`, `fr-CA`, `en-GB`, `fr-FR`, `es-ES`, `it-IT`, `de-DE`. This value is only returned if `nameFreeInvocation.status` is `ENABLED`. Limit of 5 locales.	Array

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type
`type`	Error type.	String
`message`	Error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

HTTP response codes

Status Code	Name	Description
201	Created	The skill enablement was successfully created.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The operator doesn't have the right permission to perform the operation.
404	Not found	The requested skill ID or unit ID can't be found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
500	Internal Server Error	The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.
503	Service Unavailable	The server is temporarily unavailable.
503	Service Unavailable	The server is temporarily unavailable for fetching NameFreeInvocation.

Enable a skill for multiple units

Call POST /v1/skills/{skillId}/enablements/batch to enable a skill for multiple units in a single request.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/{skillId}/enablements/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request body examples

Enable skill without account linking or name-free interaction

The following example shows a basic skill enablement on multiple units without additional details such as account linking or name-free interaction.

Request body example

{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live"
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live"
        }
    ]
}

Enable skill with account linking

The following example shows a skill enablement on multiple units with account linking using partitions.

Request body example

{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live",
            "partitionName": "10-101", // Optional
            "accountLinkRequest": { // Optional, only for skills that support account linking
                "redirectUri": "https://redirecturi.com",
                "authCode": "3pauthcode1",
                "type": "AUTH_CODE"
            }
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live",
            "partitionName": "11-101,11-102,11-103" // Optional
        }
    ]
}

Enable skill with name-free interaction

The following example shows a skill enablement on multiple units with name-free interaction.

Note: This functionality is only available for Alexa Smart Properties property skills. See Add Name-Free Interaction to Alexa Smart Properties Skills.

Request body example

{
    "items": [
        {
            "itemId": 0,
            "unitId": "amzn1.alexa.unit.unitId1",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA"]
            }
        },
        {
            "itemId": 1,
            "unitId": "amzn1.alexa.unit.unitId2",
            "stage": "live",
            "nameFreeInvocationRequest": {
                "locales" : ["en-CA","fr-CA"]
            }
        }
    ]
}

Request body parameters

Field	Description	Type	Required
`items`	A list of request items. Each item represents an enablement request for a single unit.	Array	Yes
`itemId`	A unique identifier for the request item. Must be unique within the request.	Integer	Yes
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`stage`	Skill stage: `development` or `live`.	Enum	Yes
`partitionName`	A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names. For example, "Room-101" and "Room101, Room202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Room101, ,Room202" (not properly comma-separated), "Room 101" (contains whitespace). Note: If there is an existing enablement for a given `skillId` and `unitId`, the next `POST` enablement request for the same `skillId` and `unitId` with a different `partitionName` value (new, updated or none) updates the existing enablement with the latest `partitionName` value.	String	No
`accountLinkRequest`	Account linking request information, as an AccountLinkRequest object.	Object	Yes, for skills that require account linking
`nameFreeInvocationRequest`	Name-free interaction request information, as an NameFreeInvocationRequest object.	Object	No. Only available for skills that support name-free interaction

Success response

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Success response parameters

None.

Error response header

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response body examples

The following example shows an error response body for an entire request, not for individual items.

{
    "errors": [
        {
            "status": 401,
            "erorrCode": "INVALID_LWA_TOKEN",
            "errorDescription": "The access token is invalid."
        }
    ]
}

The following example shows an error response body for individual items.

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "unitId is missing or invalid"
        },
        {
            "itemId": 20,
            "status": 403,
            "errorCode": "FORBIDDEN",
            "errorDescription": "The operator doesn't have the right permission to perform the operation."
        }
    ]
}

Error response parameters

Field	Description	Type	Required
`errors`	A list of error responses, one for each request item.	Array	Yes
`itemId`	The identifier for the request item. Optional if the error response is for the entire request and not for individual items.	String	No
`status`	The response status code per request or request item.	Integer	Yes
`errorCode`	The error code for the error.	Enum	Yes
`errorDescription`	A description of the error.	String	Yes

HTTP response codes

Status Code	Name	Description
202	Accepted	The request was accepted.
400	Bad Request	The request is malformed or is missing one or more required parameters. Example reasons: • The `skillId` is missing or invalid. • The `unitId` is missing or invalid. • The requested `skillId` and `stage` combination couldn't be found. • The number of request items exceeds the limit.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The operator doesn't have the right permission to perform the operation.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
500	Internal Server Error	The request couldn't be handled because of an internal service error when retrieving NameFreeInvocation.
503	Service Unavailable	The server is temporarily unavailable.
503	Service Unavailable	The server is temporarily unavailable for fetching NameFreeInvocation.

Disable skills

The following operations allow you to disable a skill on one or multiple units.

Disable a skill for a unit

Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId} to disable a skill for a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

DELETE /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request parameters

Field	Description	Type	Required
`unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes
`stage`	Skill stage: `development` or `live`. If present, the stage must be enabled.	Enum	No

Success response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Success response parameters

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type
`type`	Error type.	String
`message`	Error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String

HTTP response codes

Status Code	Name	Description
204	No content	The skill enablement was successfully deleted.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The operator doesn't have the right permission to perform the operation.
404	Not found	The requested skill ID or unit ID can't be found.
429	Too many requests	The request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	The server is temporarily unavailable.

Disable a skill for multiple units

Call POST /v1/skills/{skillId}/enablements/batchDelete to disable a skill for multiple units in a single request.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/skills/{skillId}/enablements/batchDelete HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`skillId`	Skill ID, in the format `"amzn1.alexa.skill.{id}"`.	String	Yes

Request body example

The following example shows the body of a request to disable a skill for three units.

{
  "items": [
    {
        "itemId": 0,
        "unitId": "amzn1.alexa.unit.unitId1",
        "stage": "live"
    },
    {
        "itemId": 1
        "unitId": "amzn1.alexa.unit.unitId2",
        "stage": "development"
    },
    {
        "itemId": 2
        "unitId": "amzn1.alexa.unit.unitId3"
    }
  ]
}

Request body parameters

Field	Description	Type	Required
`items`	List of request items. Each item represents an disablement request for a single unit.	Array	Yes
`items[*].itemId`	Unique identifier for the request item. Must be unique within the request.	Integer	Yes
`items[*].unitId`	Unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes
`stage`	Skill stage: `development` or `live`. If present, the specified skill stage will be disabled.	Enum	No

Success response

Note: In the response header, the returned Host value is the same as the Host value in the request.

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String

Success response parameters

None.

Error response header

HTTP/1.1 {ErrorCode}
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response body example

The following example shows an error response body.

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Unit ID is missing or invalid"
        }
    ]
}

Error response parameters

Field	Description	Type
`errors`	A list of error responses, one for each request item.	Array
`errors[*].itemId`	The identifier for the request item. Optional if the error response is for the entire request and not for individual items.	String
`errors[*].status`	The response status code per request or request item.	Integer
`errors[*].errorCode`	The error code for the error.	Enum
`errors[*].errorDescription`	A description of the error.	String

HTTP response codes

Status Code	Name	Description
202	Accepted	The request was accepted.
400	INVALID_PARAM	The request has a missing or invalid parameter.
400	BAD_REQUEST	The number of request items exceeds the limit.
401	UNAUTHENTICATED	The access token is missing, expired, or invalid.
403	FORBIDDEN	The operator doesn't have the right permission to perform the operation.
404	ENABLEMENT_NOT_FOUND	The requested enablement couldn't be found.
404	SKILL_STAGE_NOT_FOUND	The requested skill ID and stage combination couldn't be found.
429	TOO_MANY_REQUESTS	The request is throttled.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
503	SERVICE_UNAVAILABLE	The server is temporarily unavailable.

Was this page helpful?

Provide feedback

Last updated: Sep 10, 2024