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 for residential partners. See Get Started with Alexa Smart Properties for Residential APIs.

Use the Skill Management API to manage your smart home skills for Alexa Smart Properties for residential homes.

About skill enablement for homes

For an introduction to Alexa skills, see What is the Alexa Skills Kit?.

An Alexa Smart Properties for residential home can be in the vacant, occupied or linked state. When a home is created, it's in the vacant state. When a resident moves in, you change the home's occupancy state from vacant to occupied. When the resident links their personal Amazon account with the home, the home's state changes to linked. See About home occupancy states.

Definitions

Your skill — A skill that you develop and operate as an Alexa Smart Properties for residential developer, for example, a smart home skill.
Home's skill account — A user account in your skill's account system that corresponds to a home unit, for example, Unit 101 Account.
Resident's skill account — A user account in your skill's account system that corresponds to a resident, for example, Jenny Smith's account with username jennysmith@email.com.
Home unit — An object in the Alexa Smart Properties for residential system that corresponds to a home in the home community, for example, unit 101.
Amazon account — A resident's personal Amazon account, for example, Jenny Smith's Amazon account with username jennysmith@example.com.
Linking — Linking your skill with a resident's Amazon customer account or with a (vacant or occupied) home unit.

Skill enablement for homes in the vacant state

For each home unit, you must create a home account and enable and link it with the home unit. This provides isolation for the home account to manage resources (such as smart home devices) that are associated only with that home.

Skill enablement for homes in the occupied state

When a home is in the occupied state, the resident might already have a skill account with your skill's service, but the resident's Amazon account is unknown. Your skill is enabled and linked to the home unit through the home account.

Skill enablement for homes in the linked state

When a resident links their personal Amazon account with the home, your skill is enabled on — and linked to — the resident's Amazon account. The home account's skill enablement and account linking are unchanged.

API endpoint

The endpoint of the Skill Management 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).

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}`
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 enablement for multiple units	`POST /v1/skills/enablements/batchGet`

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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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

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

Success response header

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 example

{
   "skill": {
      "stage": "stage",
      "id": "amzn1.ask.skill.skillId"
   },
   "unit": {
      "id": "amzn1.alexa.unit.unitId"
   },
   "accountLink": {
      "status": "LINKED"
  },
   "status": "ENABLED",
}

Response body parameters

Field	Description	Type
`skill.stage`	Skill stage: `development`, `certification`, 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

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 user doesn't have 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.

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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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

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

Success response header

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 example

{
  "paginationContext": {
    "nextToken": "amzn1.ask.skill.tokenUUID"
  },
  "items": [
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId1"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED"
    },
    {
      "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.skillId2"
      },
      "unit": {
        "id": "amzn1.alexa.unit.unitId"
      },
      "accountLink": {
        "status": "NOT_LINKED"
      },
      "status": "ENABLED",
    }
  ]
}

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`, `certification`, 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

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 user doesn't have 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.
503	Service Unavailable	The server is temporarily unavailable.

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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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 example

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

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, "Home-101" and "Home101, Home202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Home101, ,Home202" (not properly comma-separated), "Home 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 support account linking

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

Success response header

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"
  },
  "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

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 user doesn't have 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 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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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`, `certification`, or `live`. If present, the stage must be enabled.	Enum	No

Success response header

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 user doesn't have 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.

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	Residential	Senior Living	Core
US	US, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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 example

The following example shows the body for a request to enable a skill for two units. The body contains two items, one for each unit.

{
    "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
        }
    ]
}

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`, `certification`, 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, "Home101" and "Home101, Home202" are valid values for this parameter. The following are not valid values: "" (empty list), "Home101, ,Home202" (not properly comma-separated), "Home 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 support account linking

Success response

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 user doesn't have 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.
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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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`, `certification`, or `live`. If present, the specified skill stage will be disabled.	Enum	No

Success response

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 user doesn't have 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.

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	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

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

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.

{
  "paginationContext": {
      "maxResults" : 5,
      "nextToken": "paginationTokenString"
  },
  "items": [
    {
      "itemId": 0,
      "unitId": "amzn1.alexa.unit.unitId1"
    },
    {
      "itemId": 1,
      "unitId": "amzn1.alexa.unit.unitId2"
    },
    {
      "itemId": 2,
      "unitId": "amzn1.alexa.unit.unitId3"
    },
    {
      "itemId": 3,
      "unitId": "amzn1.alexa.unit.unitId4"
    },
  ]
}

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

Success response

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

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 user doesn't have 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.
503	SERVICE_UNAVAILABLE	The server is temporarily unavailable.

Last updated: Mar 30, 2022