Skill Development Notifications REST API Reference

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

Use the Skill Development Notifications Service (SDNS) REST API to create and manage subscribers and subscriptions for skill development notifications. SDNS is a message delivery system for Alexa skill development events.

If you develop Alexa skills by using the Alexa Skill Management API (SMAPI) or the Alexa Skills Kit Command-Line Interface (ASK CLI), you can use the SDNS to notify you about Alexa skill development events. Before you use the SDNS REST API, you must create an Amazon Simple Notification Service (SNS) topic to receive notifications.

For an overview of SDNS and the steps to set up notifications, see Use the Alexa Skill Development Notifications. For more details about the skill development events, see Alexa Skill Development Event Schemas.

API endpoint

The endpoint of the SDNS 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 SDNS Prerequisites.

Operations

The SDNS API includes the following operations.

Operation	HTTP method and URI
Create subscriber	`POST /v0/developmentEvents/subscribers`
Create subscription	`POST /v0/developmentEvents/subscriptions`
Delete subscriber	`DELETE /v0/developmentEvents/subscribers/{subscriberId}`
Delete subscription	`DELETE /v0/developmentEvents/subscriptions/{subscriptionId}`
Get subscriber	`GET /v0/developmentEvents/subscribers/{subscriberId}`
Get subscription	` GET /v0/developmentEvents/subscriptions/{subscriptionId}`
List subscribers	`GET /v0/developmentEvents/subscribers?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}`
List subscriptions	`GET /v0/developmentEvents/subscriptions?vendorId={vendorId}&subscriberId={subscriberId}&maxResults={maxResults}&nextToken={nextToken}`
Update subscriber	`PUT /v0/developmentEvents/subscribers/{subscriberId}`
Update subscriptions	`PUT /v0/developmentEvents/subscriptions/{subscriptionId}`

Create subscriber

Create a subscriber to the specified the Amazon SNS topic. You use the subscriber to create a subscription to skill development events.

When you create a subscriber, SDNS sends an empty JSON object to the endpoint that you define in the request. This empty notification enables you to verify that you set up the subscriber correctly. If you set up any form of Amazon SNS topic notification, such as email, mobile SMS, or another channel, you receive this empty object through that channel.

Request

To create a subscriber, you make a POST request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

POST /v0/developmentEvents/subscribers
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	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "vendorId": "your.vendor.id.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property	Description	Type	Required
`vendorId`	Identifies the vendor to which the SNS topic belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`name`	Name for the subscriber.	String	Yes
`endpoint`	Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.	Object	Yes
`endpoint.uri`	URI of the endpoint that receives the notifications.	String	Yes
`endpoint.authorization`	Describes the authorization required to publish a notification to the endpoint.	Object	Yes
`endpoint.authorization.type`	Specifies the type of authorization. Valid values: `AWS_IAM`	String	Yes
`endpoint.authorization.arn`	Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role to use for authentication.	String	Yes

Response

A successful response returns HTTP 201 Created, along with a Location parameter in the response header that contains the subscriberId URL to retrieve the subscriber. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`201 Created`	Subscriber created successfully. The response header contains a `Location` parameter that includes the `subscriberId`. For example: `HTTP 201 Created Content-Type: application/json Location: /v0/developmentEvents/subscribers/amzn1.ask-subscriber.1`
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Create subscription

Create a new subscription for the specified subscriber. The subscription defines the events that trigger a notification to the subscriber.

Request

To create a subscription, you make a POST request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

POST /v0/developmentEvents/subscriptions
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	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "vendorId": "your.vendor.id.1",
    "subscriberId": "amzn1.ask-subscriber.1",
    "name": "your.subscription.name",
    "events": [
        "AlexaDevelopmentEvent.SkillPublish", 
        "AlexaDevelopmentEvent.SkillCertification"
    ]
}

Request body properties

Property	Description	Type	Required
`vendorId`	Identifies the vendor to which the subscription belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`subscriberId`	Identifies the subscriber to receive the notifications. Formatted in the Amazon Common Identifier (ACI) format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String	Yes
`name`	Name for the subscription.	String	Yes
`events`	List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas. Valid values: `AlexaDevelopmentEvent.ManifestUpdate`, `AlexaDevelopmentEvent.SkillPublish`, `AlexaDevelopmentEvent.SkillCertification`, `AlexaDevelopmentEvent.InteractionModelUpdate`, `AlexaDevelopmentEvent.All`, `AlexaCustomerFeedbackEvent.SkillReviewPublish`.	Array of strings	Yes

Response

A successful response returns HTTP 201 Created, along with a Location parameter in the response header that contains the subscriptionId URL to retrieve the subscription. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`201 Created`	Subscription created successfully. The response header contains a `Location` parameter that includes the `subscriptionId`. For example: `HTTP 201 Created Content-Type: application/json Location: /v0/developmentEvents/subscribers/amzn1.ask-subscription.1`
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscriber

Deletes the subscriber with the specified subscriberId from the topic. To delete a subscriber, you must delete the associated subscriptions first.

Request

To remove a subscriber, you make a DELETE request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

DELETE /v0/developmentEvents/subscribers/{subscriberId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriberId`	Path	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	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 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscriber deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscription

Delete the specified subscription. The vendor who created the subscriber and the vendor that published the event can delete a subscription.

Request

To delete a subscription, you make a DELETE request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

DELETE /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriptionId`	Path	Identifies the subscription. Formatted in the ACI format, `amzn1.alexa.subscription.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	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 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscription deleted successfully
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscriber

Get the details for the specified subscriber.

Request

To get a subscriber, you make a GET request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscribers/{subscriberId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriberId`	Path	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	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 subscriber information. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscriberId": "amzn1.ask-subscriber.1",
    "name": "subscriber.name.1",
    "vendorId": "your.vendor.id.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Response body properties

Property	Description	Type
`subscriberId`	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String
`name`	Name for the subscriber.	String
`vendorId`	Identifies the vendor to which the SNS topic belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String
`endpoint`	Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.	Object
`endpoint.uri`	URI of the endpoint that receives the notifications.	String
`endpoint.authorization`	Describes the authorization required to publish a notification to the endpoint.	Object
`endpoint.authorization.type`	Specifies the type of authorization. Valid values: `AWS_IAM`	String
`endpoint.authorization.arn`	Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role to use for authentication.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the subscriber information.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscription

Get the details for the specified subscription.

Request

To get a subscription, you make a GET request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriptionId`	Path	Identifies the subscription. Formatted in the ACI format, `amzn1.alexa.subscription.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	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 subscription information. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "vendorId": "your.vendor.id.1",
    "subscriberId": "amzn1.ask-subscriber.1",
    "subscriptionId": "amzn1.ask-subscription.1",
    "name": "your.subscription.name",
    "events": [
        "AlexaDevelopmentEvent.SkillPublish", 
        "AlexaDevelopmentEvent.SkillCertification"
    ]
}

Response body properties

Property	Description	Type
`vendorId`	Identifies the vendor to which the subscription belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String
`subscriberId`	Identifies the subscriber to receive the notifications. Formatted in the Amazon Common Identifier (ACI) format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String
`subscriptionId`	Identifies the subscription. Formatted in the Amazon Common Identifier (ACI) format, `amzn1.alexa.subscriptionId.{id}`. Valid values: 1 – 255 characters.	String
`name`	Name for the subscription.	String
`events`	List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas. Valid values: `AlexaDevelopmentEvent.ManifestUpdate`, `AlexaDevelopmentEvent.SkillPublish`, `AlexaDevelopmentEvent.SkillCertification`, `AlexaDevelopmentEvent.InteractionModelUpdate`, `AlexaDevelopmentEvent.All`, `AlexaCustomerFeedbackEvent.SkillReviewPublish`.	Array of strings

HTTP status codes

Status	Description
`200 OK`	Response body contains the subscription information.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

List subscribers

List the subscribers for the specified vendor.

Request

To list subscribers, you make a GET request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscribers?vendorId={vendorId}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`vendorId`	Query	Identifies the vendor to which the SNS topic belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	String	No
`access token`	Header	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 a list of subscribers for the specified vendor. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscribers": [{
            "subscriberId": "amzn1.ask-subscriber.1",
            "name": "subscriber.name.1",
            "clientId": "your.client.id.1",
            "status": "ACTIVE",
            "endpoint": {
                "uri": "https://sns.amazonaws.com/example.topic",
                "authorization": {
                    "type": "AWS_IAM",
                    "arn": "arn:aws:iam::us-east-1:1"
                }
            }
        },
        {
            "subscriberId": "amzn1.ask-subscriber.2",
            "name": "subscriber.name.2",
            "clientId": "your.client.id.1",
            "status": "ACTIVE",
            "endpoint": {
                "uri": "https://sns.amazonaws.com/example.topic",
                "authorization": {
                    "type": "AWS_IAM",
                    "arn": "arn:aws:iam::us-east-1:1"
                }
            }
        }
    ],
    "nextToken": "string",
    "_links": {
        "self": {
            "href": "string"
        },
        "next": {
            "href": "string"
        }
    }
}

Response body properties

Property	Description	Type
`subscribers`	List of subscribers for the specified vendor.	Array of objects
`subscribers[].subscriberId`	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String
`subscribers[].name`	Name for the subscriber.	String
`subscribers[].status`	Indicates the current status of the subscriber. Valid values: `ACTIVE`, `INACTIVE`.	String
`subscribers[].clientId`	Unique identifier for the subscriber.	String
`subscribers[].endpoint`	Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.	Object
`subscribers[].endpoint.uri`	URI of the endpoint that receives the notifications.	String
`subscribers[].endpoint.authorization`	Describes the authorization required to publish a notification to the endpoint.	Object
`subscribers[].endpoint.authorization.type`	Specifies the type of authorization. Valid values: `AWS_IAM`	String
`subscribers[].endpoint.authorization.arn`	Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role to use for authentication.	String
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of subscribers defined for the specified vendor.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

List subscriptions

List the subscriptions for the specified vendor, specified subscriber or both.

Request

To list subscriptions, you make a GET request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

GET /v0/developmentEvents/subscriptions?vendorId={vendorId}&subscriberId={subscriberId}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter	Located in	Description	Type	Required
`vendorId`	Query	Identifies the vendor to which the subscription belongs. For details about how to get your vendor ID, see Locate your customer ID and vendor ID. Include at least one of `vendorId` or `subscriberId` or both.	String	No
`subscriberId`	Path	Identifies the subscriber to an SNS topic. Include at least one of `vendorId` or `subscriberId` or both. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–250. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. If not included, the Alexa service returns the first page of results. Include if iterating over a paginated response.	String	No
`access token`	Header	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 a list of subscriptions. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "subscriptions": [{
            "subscriptionId": "amzn1.ask-subscription.1",
            "name": "subscription.name.1",
            "subscriberId": "amzn1.ask-subscriber.1",
            "vendorId": "your.vendor.id.1",
            "events": [
                "AlexaDevelopmentEvent.SkillPublish",
                "AlexaDevelopmentEvent.SkillCertification"
            ]
        },
        {
            "subscriptionId": "amzn1.ask-subscription.2",
            "name": "subscription.name.2",
            "subscriberId": "amzn1.ask-subscriber.1",
            "vendorId": "your.vendor.id.1",
            "events": [
                "AlexaDevelopmentEvent.ManifestUpdate"
            ]
        }
    ],
    "nextToken": "string",
    "_links": {
        "self": {
            "href": "string"
        },
        "next": {
            "href": "string"
        }
    }
}

Response body properties

Property	Description	Type
`subscriptions`	List of subscribers for the specified vendor.	Array of objects
`subscriptions[]subscriptionId`	Identifies the subscription. Formatted in the Amazon Common Identifier (ACI) format, `amzn1.alexa.subscriptionId.{id}`. Valid values: 1 – 255 characters.	String
`subscriptions[].name`	Name of the subscription.	String
`subscriptions[].subscriberId`	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String
`subscriptions[].events`	List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas. Valid values: `AlexaDevelopmentEvent.ManifestUpdate`, `AlexaDevelopmentEvent.SkillPublish`, `AlexaDevelopmentEvent.SkillCertification`, `AlexaDevelopmentEvent.InteractionModelUpdate`, `AlexaDevelopmentEvent.All`, `AlexaCustomerFeedbackEvent.SkillReviewPublish`.	Array of strings
`nextToken`	(Optional) Included when there are more results to return. Use this value in a subsequent request.	String
`_links`	Links for item navigation. Defined in JSON Hypertext Application Language specification.	_links object

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of subscriptions for the specified filter.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscriber

Update the properties of the specified subscriber. You can update the subscriber if your developer account is part of the same vendor ID as the subscriber. This operation overwrites the existing subscriber values. You can't update the subscriberId.

Important: If SDNS fails to deliver a notification to a subscriber due to a nonexistent endpoint or invalid publishing permissions, SDNS marks the subscriber as inactive and doesn't deliver future notifications to that subscriber. After you correct the problem, you must call the Update Subscriber API to reactivate the subscriber, even if the credentials haven't changed.

Request

To update a subscriber, you make a PUT request to the developmentEvents/subscribers resource.

Request path and header example

Copied to clipboard.

PUT /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriberId`	Path	Identifies the subscriber to an SNS topic. Formatted in the ACI format, `amzn1.alexa.subscriber.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property	Description	Type	Required
`name`	Name for the subscriber.	String	Yes
`endpoint`	Defines the SNS endpoint to receive the notifications, as well as the authorization required to publish to that endpoint.	Object	Yes
`endpoint.uri`	URI of the endpoint that receives the notifications.	String	Yes
`endpoint.authorization`	Describes the authorization required to publish a notification to the endpoint.	Object	Yes
`endpoint.authorization.type`	Specifies the type of authorization. Valid values: `AWS_IAM`	String	Yes
`endpoint.authorization.arn`	Amazon Resource Name (ARN) for the AWS Identity and Access Management (IAM) role to use for authentication.	String	Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscriber updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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 subscription

Update the subscription name or list of events. This operation overwrites the existing subscription values. You can't update the subscriberId or subscriptionId.

Request

To update a subscription, you make a PUT request to the developmentEvents/subscriptions resource.

Request path and header example

Copied to clipboard.

PUT /v0/developmentEvents/subscriptions/{subscriptionId}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`subscriptionId`	Path	Identifies the subscription. Formatted in the ACI format, `amzn1.alexa.subscription.{id}`. Valid values: 1 – 255 characters.	String	Yes
`access token`	Header	LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "subscriber.name.1",
    "endpoint": {
        "uri": "https://sns.amazonaws.com/example.topic",
        "authorization": {
            "type": "AWS_IAM",
            "arn": "arn:aws:iam::us-east-1:1"
        }
    }
}

Request body properties

Property	Description	Type	Required
`name`	Name for the subscription.	String	Yes
`events`	List of skill development events that trigger notifications to the subscriber endpoint. For more details about events, see Alexa Skill Development Event Schemas. Valid values: `AlexaDevelopmentEvent.ManifestUpdate`, `AlexaDevelopmentEvent.SkillPublish`, `AlexaDevelopmentEvent.SkillCertification`, `AlexaDevelopmentEvent.InteractionModelUpdate`, `AlexaDevelopmentEvent.All`, `AlexaCustomerFeedbackEvent.SkillReviewPublish`.	Array of strings

Response

A successful response returns 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Subscription updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error code and message. `{ "message": "The property is outside the allowed range.", "code": "INVALID_STRING_LENGTH" }`
`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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. 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.

Was this page helpful?

Provide feedback

Last updated: Aug 01, 2024