Beta Tester Management REST API Reference


After you set up a beta test for your Alexa skill, use the Beta Tester Management REST API to invite friends or family, your social network contacts, or other people for whom you have an email address to test your skill and provide feedback. You can send up to 500 invitations per test. At any time, you can add testers, remove testers, or end a test.

For more details about how to set up a beta test, see Beta Test Management REST API Reference.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Get an Access Token for SMAPI.

Operations

The Beta Tester Management API includes the following operations.

Operation HTTP method and URI

Add beta testers

POST /v1/skills/{skillId}/betaTest/testers/add

List beta testers

GET /v1/skills/{skillId}/betaTest/testers?maxResults={maxResults}&nextToken={nextToken}

Request feedback

POST /v1/skills/{skillId}/betaTest/testers/requestFeedback

Remove beta testers

POST /v1/skills/{skillId}/betaTest/testers/remove

Send reminders

POST /v1/skills/{skillId}/betaTest/testers/sendReminder

Add beta testers

Add testers to an existing beta test. You can add up to 500 testers.

On success, the tester receives an email with a customized link inviting them to be beta testers for your skill. Amazon controls the messaging for this invitation.

Request

To add testers, you make a POST request to the betaTest/testers resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/testers/add
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "testers": [{
        "emailId": "example@email.address"
    }]
}

Request body properties

Property Description Type Required

testers

List of testers to add.

Array of objects

Yes

testers[].emailId

Email address of the tester.

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

Request to add a beta tester succeeded.

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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List beta testers

Get the list of testers in the beta test for the specified skill.

Request

To list testers, you make a GET request to the betaTest/testers resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/betaTest/testers?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

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

maxResults

Query

Maximum number of results to return in the response.
Valid values: 1–500. Default: 100.

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

{
  "testers": [
    {
      "emailId": "example@email.address",
      "associationDate": "2018-09-26T07:32:37.589Z",
      "isReminderAllowed": true,
      "invitationStatus": "ACCEPTED"
    }
  ],
  "isTruncated": true,
  "nextToken": "someToken.1"
}

Response body properties

Property Description Type

testers

List of testers.

Array of objects

testers[].emailId

Email address of the tester.

String

testers[].associationDate

Date and time that the tester joined the beta test.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

String

testers[].isReminderAllowed

Indicates whether you can send the tester a reminder.

Boolean

testers[].invitationStatus

Status of the invitation request.
Valid values: ACCEPTED, NOT_ACCEPTED.

String

isTruncated

Indicates whether there are more items to return. If set to true, include nextToken a subsequent request.

Boolean

nextToken

(Optional) Included when there are more results to return. Use this value in a subsequent request.

String

HTTP status codes

Status Description

200 OK

Response body contains a list of testers.

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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Request feedback

Request feedback from the testers in a beta test for the specified skill. The system sends notification emails to testers that requests their feedback on your Alexa skill.

Request

To request feedback, you make a POST request to the betaTest/testers resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/testers/requestFeedback
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "testers": [{
        "emailId": "example@email.address"
    }]
}

Request body properties

Property Description Type Required

testers

List of testers to which to send reminders.

Array of objects

Yes

testers[].emailId

Email address of the tester.

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

Request to request feedback succeeded.

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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Remove testers

Remove testers from the beta test for the specified skill.

Request

To remove testers, you make a POST request to the betaTest/testers resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/testers/remove
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "testers": [{
        "emailId": "example@email.address"
    }]
}

Request body properties

Property Description Type Required

testers

List of testers to remove.

Array of objects

Yes

testers[].emailId

Email address of the tester.

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

Request to remove testers succeeded.

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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Send reminders

Send reminders to the testers in a beta test for the specified skill. The system sends notification emails to testers accept the invitation to participate in the beta test for your Alexa skill.

Request

To remove testers, you make a POST request to the betaTest/testers resource.

Request path and header example

Copied to clipboard.

POST /v1/skills/{skillId}/betaTest/testers/sendReminder
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1–255 characters.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "testers": [{
        "emailId": "example@email.address"
    }]
}

Request body properties

Property Description Type Required

testers

List of testers to remind.

Array of objects

Yes

testers[].emailId

Email address of the tester.

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

Request to remind testers succeeded.

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

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.


Was this page helpful?

Last updated: Jan 24, 2024