Reminders REST API Reference
Use the Alexa Reminders REST API to create and manage reminders on managed devices in your property. You can configure the text in the reminder, and then Alexa speaks the text from the device at the specific time you schedule. Use reminders to build voice experiences that help users remember daily tasks, events, schedules, or any other items they want to remember at a later time.
For a given endpoint, you can schedule one-time reminders including absolute reminders, such as a reminder at 3 PM, and relative reminders, such as a reminder in 10 minutes. You can also schedule recurring reminders, for example, a reminder every weekday at 7 AM.
API endpoint
Based on the country of your organization, set the Host
parameter in the request header to one of the following API endpoints.
Country | Endpoint |
---|---|
CA, US |
|
DE, ES, FR, IT, UK |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Reminders API includes the following operations.
Operation | HTTP method and URI |
---|---|
| |
| |
| |
| |
|
Create reminder
Create a new reminder on the specified Alexa-enabled endpoint. You can create up to 250 reminders per endpoint.
trigger.timezoneId
field, otherwise your reminder might ring at the wrong time. For more details about time zones, see Time zones for absolute times.This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
To create a reminder, you make a POST
request to the /v2/alerts/reminders
resource.
Request path and header example
POST /v2/alerts/reminders HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Header |
Access token for the customer. |
String |
Yes |
Request body examples
The following example creates a single reminder that triggers at 4:30 PM on June 21, 2024.
The following example creates a reminder that triggers 30 minutes after the specified request time of 2024-06-21T22:30:00 UTC. For a device with the time zone America/Los_Angeles
, this reminder is scheduled for June 21, 2024 at 4 PM. For a device with the time zone America/Denver
, this reminder is scheduled for June 21, 2024 at 5 PM.
The following example creates a reminder that triggers at 4:30 PM on the fifth day of each month, starting in June 2024 and ending in September 2024.
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
List of recipients to which to apply this reminder. You can provide one recipient only. |
Array of objects |
Yes |
|
Type of recipient. |
String |
Yes |
|
Endpoint on which to set the reminder. |
String |
Yes |
|
Describes the reminder. |
Object |
Yes |
|
Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the |
String |
No |
|
Contains information about the trigger for a reminder. |
Trigger object |
Yes |
|
Contains the spoken content in the reminder. |
AlertInfo object |
Yes |
Response
A successful response returns HTTP 202 Accepted
, along with the new reminder ID.
On error, the response returns the appropriate HTTP status code and includes a response body with the failed endpoint, the error code, and a human readable message.
Response body examples
The following example shows a successful creation of the reminder on the specified endpoint.
The following example shows a creation of the reminder on the specified endpoint failed.
Response body properties
Property | Description | Type |
---|---|---|
|
Type of response. |
String |
|
Human-readable description of the result. The message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the message. |
String |
|
List of endpoints where the reminder was successfully created. |
Array of objects |
|
(Optional) ID of the endpoint recipient for the reminder. |
String |
|
(Optional) ID of the new reminder. |
String |
|
List of endpoints where the reminder creation failed. |
Array of objects |
|
(Optional) ID of the endpoint recipient for the reminder. |
String |
|
(Optional) Error status code for the failed reminder. |
String |
|
(Optional) Short error code string. |
String |
|
(Optional) Detailed description of the error. |
String |
HTTP status codes
Status | Description |
---|---|
|
Successfully created the reminder. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed.
|
|
Requested resource not found. |
|
Indicates a request conflict with the current state of the target resource.
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Delete reminder
Delete the specified reminder by reminder ID.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
To delete a reminder, you make a DELETE
request to the /v2/alerts/reminders
resource.
Request path and header example
DELETE /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the reminder to delete. |
String |
Yes |
|
Header |
LWA access token. For details, see Authentication. |
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 object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Reminder deleted successfully. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get reminder
Get the specified reminder by reminder ID.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
To get a reminder, you make a GET
request to the ` /v2/alerts/reminders` resource.
Request path and header example
GET /v2/alerts/reminders/{reminderId}
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 |
---|---|---|---|---|
|
Path |
ID of the reminder to retrieve. |
String |
Yes |
|
Header |
LWA access token. For details, see Authentication. |
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 details of the specified reminder.
On error, the response returns the appropriate HTTP status code and includes a response body with an Error object.
Response body examples
The following response body examples show output for absolute, recurring, and relative reminders.
Response body properties
Property | Description | Type |
---|---|---|
|
Recipient for this reminder. |
Object |
|
Type of recipient. |
String |
|
Endpoint on which to apply the reminder. |
String |
|
Contents of the reminder. |
Object |
|
Unique ID of this reminder. |
String |
|
Creation time of the reminder. |
String |
|
Time of last update to the reminder. |
String |
|
Status of the reminder.
|
String |
|
Version of the reminder. |
String |
|
Contains information about the trigger for a reminder. |
Trigger object |
|
Contains the spoken content in the reminder. |
AlertInfo object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the list of reminders for the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List reminders on endpoint
List all scheduled reminders for the specified endpoint.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
To list reminders, you make a GET
request to the /v2/alerts/reminders
resource.
Request path and header example
`GET /v2/alerts/reminders?recipient.type={recipientType}}&recipient.id={recipientId}&owner={owner}` HTTP/1.1
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 |
---|---|---|---|---|
|
Query |
Type of recipient. |
String |
Yes |
|
Query |
Unique endpoint ID of the recipient. |
String |
Yes |
|
Query |
Filter endpoints to those associated with the owner. |
String |
Yes |
|
Header |
LWA access token. For details, see Authentication. |
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 reminders for the specified endpoint.
Response body example
{
"results": [
{
"recipient": {
"id": "amzn1.alexa.endpoint.did.1234",
"type": "Endpoint"
},
"reminder": {
"reminderId": "reminder.Id.4",
"createdTime": "2024-06-24T20:59:12.772Z",
"updatedTime": "2024-06-24T20:59:12.929Z",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"scheduledTime": "2024-06-24T18:00:00.000",
"timeZoneId": "America/Denver",
"offsetInSeconds": 0
},
"status": "ON",
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "en-US",
"text": "Bingo starts at five p.m.",
"ssml": "<speak>Bingo starts at five p.m.</speak>"
}
]
}
},
"version": "2"
}
},
{
"recipient": {
"id": "amzn1.alexa.endpoint.did.1234",
"type": "Endpoint"
},
"reminder": {
"reminderId": "reminder.Id.22",
"createdTime": "2024-06-21T23:36:25.342Z",
"updatedTime": "2024-06-24T03:29:53.945Z",
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"scheduledTime": "2024-06-24T17:40:00.000",
"timeZoneId": "America/Denver",
"offsetInSeconds": 0,
"recurrence": {
"startDateTime": "2024-06-01T00:00:00.000-06:00",
"endDateTime": "2024-09-30T00:00:00.000-06:00",
"recurrenceRules": [
"FREQ=DAILY;INTERVAL=1;BYHOUR=17;BYMINUTE=40"
]
}
},
"status": "ON",
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "en-US",
"text": "Take your medication every day after dinner",
"ssml": "<speak>Take your medication every day after dinner</speak>"
}
]
}
},
"version": "3"
}
}
]
}
Response body properties
Property | Description | Type |
---|---|---|
|
List of reminders associated with the specified endpoint. |
Array of objects |
|
List of recipients for this reminder. |
Array of objects |
|
Type of recipient. |
String |
|
Endpoint on which to apply the reminder. |
String |
|
Contents of the reminder. |
Object |
|
Unique ID of the reminder. |
Object |
|
Creation time of the reminder. |
String |
|
Time of last update to the reminder. |
String |
|
Status of the reminder.
|
String |
|
Version of the reminder. |
String |
|
Contains information about the trigger for a reminder. |
Trigger object |
|
Contains the spoken content in the reminder. |
AlertInfo object |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the list of reminders for the specified endpoint. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Update reminder
Update the specified reminder. To update the reminder, you must specify all reminder properties. Use Get reminder to get the reminder object, and then update the properties you want to change. For example, if you want to change the reminder text, but keep the original scheduled time, set the text
and ssml
properties to the new text, and set the values in the trigger
object to the same values you used when you created the reminder.
This operation is available in the following countries.
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
US |
US, UK, FR, CA, IT, DE, ES |
US, UK, FR, CA, IT, DE, ES |
US |
Request
To update a reminder, you make a PUT
request to the /v2/alerts/reminders
resource.
Request path and header example
PUT /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
Parameter | Located in | Description | Type | Required |
---|---|---|---|---|
|
Path |
ID of the reminder to update. |
String |
Yes |
|
Header |
LWA access token. For details, see Authentication. |
String |
Yes |
Request body example
{
"recipient": {
"type": "Endpoint",
"id": "amzn1.alexa.endpoint.did.1234"
},
"reminder": {
"trigger": {
"type": "SCHEDULED_ABSOLUTE",
"timeZoneId": "America/Los_Angeles",
"recurrence": {
"startDateTime": "2019-05-10T6:00:00.000",
"endDateTime": "2019-08-10T10:00:00.000",
"recurrenceRules": [
"FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=10;INTERVAL=1;"
]
}
},
"alertInfo": {
"spokenInfo": {
"content": [
{
"locale": "en-US",
"text": "Bingo starts at 5pm",
"ssml": "<speak> Bingo starts at five p.m.</speak>"
}
]
}
}
}
}
Request body properties
Property | Description | Type | Required |
---|---|---|---|
|
Recipient for the reminder. |
Object |
Yes |
|
Type of recipient. |
String |
Yes |
|
Endpoint on which to set the reminder. |
String |
Yes |
|
Describes the reminder. |
Object |
Yes |
|
Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the |
String |
No |
|
Contains information about the trigger for a reminder. |
Trigger object |
Yes |
|
Contains the spoken content in the reminder. |
AlertInfo object |
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 object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
Status | Description |
---|---|
|
Reminder updated successfully |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed.
|
|
Requested resource not found. |
|
Indicates a request conflict with the current state of the target resource.
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Time zones for absolute times
When you set a reminder trigger to an absolute time by using the scheduledTime
property, the reminder plays at either the time zone of the device or a specific time zone you define in the request as follows:
- To set a reminder in the same time zone of the device, set the
scheduledTime
property and leave thetimeZoneId
field unset. - To set a reminder in a specific the time zone, set both the
scheduledTime
andtimeZoneId
properties.
timeZoneId
. For example, if the device is in America/Los Angeles
, a time of 2019-06-01T19:00:00
in America/New_York
speaks and displays as 4 PM PDT.Object definitions
The Reminders API defines the following objects.
AlertInfo object
The AlertInfo
object defines spoken and display alert information for the reminder.
Property | Description | Type |
---|---|---|
|
Contains information about the spoken content in the reminder. |
Object |
|
Spoken content in the alert. |
Array of objects |
|
Defines the locale and language for the reminder text. |
String |
|
Default text used for display and spoken content. |
String |
|
(Optional) Text used for spoken content, generated with SSML. |
String |
Error object
The Error
object defines the error type and message included in the response when an error occurs.
The following example shows the response body with the error type and message.
{
"type": "REMINDER_NOT_FOUND",
"message": "Reminder does not exist."
}
Property | Description | Type |
---|---|---|
|
Type of error that occurred. |
String |
|
Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String |
Recurrence object
The Recurrence
object defines the rules for recurring reminders. You can define recurring reminders when the trigger type is SCHEDULED_ABSOLUTE
.
The following table defines the properties of the object.
Property | Description | Type |
---|---|---|
|
(Optional) Start of the recurrence pattern. Default is current time. |
String |
|
(Optional) End of the recurrence pattern. Default is no end time. |
String |
|
(Optional) Recurrence pattern for repeating reminders.
|
Array of RRULEs |
Trigger object
The Trigger
object defines the schedule time type, absolute or relative, and rules for one-time or recurring reminders.
The following table defines the properties of the object.
Property | Description | Type |
---|---|---|
|
Indicates type of trigger. |
String |
|
(Optional) Specifies the number of seconds after which the reminder plays. |
Integer |
|
(Optional) Intended trigger date and time for this reminder, scheduled at an absolute time. Specify in ISO 8601 format,
|
String |
|
(Optional) Specifies the time zone, such as |
String |
|
(Optional) Specifies recurrence information for reminders that repeat at regular intervals. |
Recurrence object |
Related topics
Last updated: Dec 04, 2024