Reminders API

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

Note: This API is only available to registered Alexa Smart Properties partners. For details, see Get Started with Alexa Smart Properties APIs.

Use the Alexa Reminders API v2 to create and manage reminders on managed devices in your property. You can configure the text in the reminder, and 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.

The API uses JSON over HTTP with OAuth authentication and provides capabilities such as scheduling absolute reminders (for example, a reminder at 3 PM) or relative reminders (for example, a reminder in 10 minutes), updating and deleting reminders, and listing all reminders for a given device. You can also schedule one-time and recurring reminders.

API endpoint

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

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

Important: In the UK and EU, you can't use the Reminders API for health use cases such as medication reminders. This is true even when using the Health Consent Framework.

Authentication

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

Operations

The Reminders API includes the following operations.

Operation	HTTP method and URI
Create a reminder	`POST /v2/alerts/reminders`
Get a reminder	`GET /v2/alerts/reminders/{reminderId}`
Update a reminder	`PUT /v2/alerts/reminders/{reminderId}`
Delete a reminder	`DELETE /v2/alerts/reminders/{reminderId}`
Get all reminders on an endpoint	`GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.<endpointId>&recipient.type=Endpoint&owner=~caller`

Create a reminder

Creates a new 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 create a reminder, you make a POST request.

Request header example

POST /v2/alerts/reminders HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access_token`	Header	LWA access token. For details, see Authentication.	String	Yes
`Content-Type`	Header	`application/json`	String	Yes

Request body examples

Absolute reminder example

The following example creates a single reminder that triggers at 4:30 PM on June 21, 2024.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "scheduledTime": "2024-06-21T16:30:00.000",
      "timeZoneId": "America/Los_Angeles"
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Recurring reminder example

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.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "trigger": {
      "type": "SCHEDULED_ABSOLUTE",
      "recurrence": {
        "startDateTime": "2024-06-01T00:00:00.000",
        "endDateTime": "2024-09-30T00:00:00.000",
        "recurrenceRules": [
          "FREQ=MONTHLY;BYMONTHDAY=5;BYHOUR=16;BYMINUTE=30;INTERVAL=1;"
        ]
      }
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Relative reminder example

The following example creates a reminder that triggers 30 minutes after the specified request time of 2024-06-21T22:30:00. This request time is in 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.

{
  "recipients": [
    {
      "type": "Endpoint",
      "id": "amzn1.alexa.endpoint.did.1234"
    }
  ],
  "reminder": {
    "requestTime": "2024-06-21T22:30:00",
    "trigger": {
      "type": "SCHEDULED_RELATIVE",
      "offsetInSeconds": "1800"
    },
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at five p.m.",
            "ssml": "<speak>Bingo starts at five p.m.</speak>"
          }
        ]
      }
    }
  }
}

Request body properties

Property	Description	Type	Required
`recipients`	Array of recipients to which to apply this reminder. You can provide exactly one recipient.	Array of objects	Yes
`recipients[].type`	Type of recipient. Accepted values: `Endpoint`.	Enum	Yes
`recipients[].id`	Unique identifier for the recipient. This must be an endpoint ID.	String	Yes
`reminder`	Contents of the reminder.	Object	Yes
`reminder.requestTime`	Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the `offsetInSeconds` to the `requestTime` to calculate the trigger time for a relative reminder. When not provided, defaults to the current date and time. Specify the `requestTime` in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`. Provide the `requestTime` in UTC time, not in the local time zone of the device. The API then uses the time zone of the device to calculate the reminder time. For example, assume the `requestTime` is `2024-06-21T22:30:00` and the `offsetInSeconds` is `1800` (30 minutes). 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.	String	No
`reminder.trigger`	Contains information about the trigger for a reminder.	Object	Yes
`reminder.trigger.type`	Indicates type of trigger. Accepted values: `SCHEDULED_ABSOLUTE` or `SCHEDULED_RELATIVE`.	Enum	Yes
`reminder.trigger.offsetInSeconds`	Applies when `trigger.type` is `SCHEDULED_RELATIVE`. Specifies the number of seconds after the `requestTime` to play the reminder. Not applicable when the `trigger.type` is `SCHEDULED_ABSOLUTE`.	Integer	Yes when the `trigger.type` is `SCHEDULED_RELATIVE`.
`reminder.trigger.scheduledTime`	Trigger date and time for a single reminder scheduled at an absolute time (`SCHEDULED_ABSOLUTE`). Provide the date and time in ISO 8601 format. For example, `2024-06-24T18:00:00.000` for June 24, 2024 at 6 PM. Not applicable when `trigger.type` is `SCHEDULED_RELATIVE`. Ignored for recurring reminders. Use the `trigger.recurrence.recurrenceRules` property to specify the time for a recurring reminder.	String	Yes when the `trigger.type` is `SCHEDULED_ABSOLUTE`.
`reminder.trigger.timeZoneId`	A string containing the ID of the time zone. For valid values, see List of tz database time zones identifiers. If you don't provide a time zone, the reminder defaults to use the time zone of the device. Not applicable when the `trigger.type` is `SCHEDULED_RELATIVE`. For details about time zones, see Time zones for absolute times.	Enum	No
`reminder.trigger.recurrence`	Specifies recurrence information for reminders that repeat at regular intervals. Not applicable when the `trigger.type` is `SCHEDULED_RELATIVE`.	Object	No
`reminder.trigger.recurrence.startDateTime`	Optional. The start of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, defaults to the current date and time.	Enum	No
`reminder.trigger.recurrence.endDateTime`	Optional. The end of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, the recurring reminder continues indefinitely.	Enum	No
`reminder.trigger.recurrence.recurrenceRules`	The recurrence pattern for a repeating alert, in the RRULE format. Supported Values: `FREQ`, `BYMONTHDAY`, `BYDAY`, `BYHOUR`, `BYMINUTE`, `BYSECOND`, and `INTERVAL` The supported FREQ RRULE patterns are `FREQ=DAILY`, `FREQ=WEEKLY`, `FREQ=MONTHLY`, and `FREQ=YEARLY` The minimum interval between two recurrence values is one hour for the en-US locale and four hours for all other supported locales. The maximum interval for `DAILY`, `WEEKLY` and `MONTHLY` patterns is 31 days. The maximum interval for `YEARLY` pattern is one year. If these constraints aren't met, the request returns a 400 error.	String[]	Yes
`reminder.alertInfo`	Specifies information about the reminder.	Object	Yes
`reminder.alertInfo.spokenInfo`	Contains information about the spoken content in the reminder.	Object	Yes
`reminder.alertInfo.spokenInfo.content`	Contains the content of the reminder.	Object[]	Yes
`reminder.alertInfo.spokenInfo.content[].locale`	Defines the locale and language for the reminder text.	String	Yes
`reminder.alertInfo.spokenInfo.content[].ssml`	Text used for spoken content, in Speech Synthesis Markup Language (SSML) format. If you don't provide a value for this field, `alertInfo.spokenInfo.content.text` handles both text and spoken content. Reminders supports the SSML speak tag.	String	No
`reminder.alertInfo.spokenInfo.content[].text`	Default text used for display and spoken content. If you provide a value in the `ssml` property, the `text` property is used for display only.	String	Yes

Time zones for absolute times

When a reminder trigger is set to an absolute time 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:

To set a reminder in the same time zone of the device, set the scheduledTime property and leave the timeZoneId field unset.
To set a reminder in a specific the time zone, set both the scheduledTime and timeZoneId properties.

Note: For speech and display purposes, Alexa always uses the original time zone of the device. This translation typically occurs if the user's device isn't in the same time zone specified in timeZoneId. For example, if the customer's device is in PDT (Los Angeles), a time of 2019-06-01T19:00:00 in America/New_York speaks and displays as 4 PM PDT.

Response

For a well-formed request, the API returns HTTP 202 Accepted and a response body where the type property indicates whether the reminder was successfully created. If an error occurred, the response body contains at status property with the error code and human readable message.

Response body examples

Success case

{
  "type": "ALL_SUCCESS",
  "message": "All reminders created successfully.",
  "successResults": [
    {
      "id": "amzn1.alexa.endpoint.did.1234",
      "reminderId": "<reminderId>"
    }
  ],
  "errors": []
}

Failed case

{
  "type": "ALL_FAILED",
  "message": "All reminders failed to created.",
  "successResults": [],
  "errors": [
    {
      "id": "amzn1.alexa.endpoint.did.1234",
      "status": 400,
      "errorCode": "DEVICE_NOT_SUPPORTED",
      "errorDescription": "Reminders are not supported on this device."
    }
  ]
}

Response headers

Property	Description	Type
`Content-Type`	Contains `application/json`	String
`X-Amzn-RequestId`	A UUID generated for the individual request.	String

Response body properties

Property	Description	Type
`type`	Type of response. Possible values: `ALL_SUCCESS`, `ALL_FAILED`.	Enum
`message`	Detailed description of the result.	String
`successResults[]`	List of endpoints where the reminder was successfully created.	Array of objects
`successResults[].id`	The ID of the recipient for the reminder.	String
`successResults[].reminderId`	The ID of the reminder.	String
`errors[]`	List of endpoints where creating the reminder failed.	Array of objects
`errors[].id`	The ID of the recipient for the reminder.	String
`errors[].status`	Error status code for the failed reminder.	String
`errors[].errorCode`	Short error code string.	String
`errors[].errorDescription`	Detailed description of the error.	String

HTTP status codes

Status	Type	Message
400	`INVALID_INPUT_TIME_FORMAT`	Request time date format incorrect.
400	`INVALID_TRIGGER`	Type and field don't match => `SCHEDULED_ABSOLUTE` has `offsetInSeconds` or `SCHEDULED_RELATIVE` has `scheduledTime`.
400	`TRIGGER_SCHEDULED_TIME_IN_PAST`	Scheduled time is in the past.
400	`INVALID_TRIGGER_SCHEDULED_TIME_FORMAT`	Date format isn't supported.
400	`INVALID_TRIGGER_TIME_ZONE`	Time zone isn't valid.
400	`INVALID_TRIGGER_RECURRENCE`	Recurrence pattern is invalid.
400	`UNSUPPORTED_TRIGGER_RECURRENCE`	Recurrence pattern is valid but not currently supported.
400	`UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL`	Recurrence pattern is valid but minimum interval between two occurrences isn't supported.
400	`INVALID_ALERT_INFO`	Alert info is missing locale / invalid locale format. Text string is too long.
400	`INVALID_TRIGGER_OFFSET`	Invalid relative time offset.
400	`UNSUPPORTED_SCHEDULED_TIME_FORMAT`	Unsupported trigger scheduled time format. Supported format is `YYYY-MM-DDTHH:mm:ss.SSS/YYYY-MM-DDTHH:mm:ss/YYYY-MM-DDTHH:mm`.
400	`INVALID_INPUT`	Invalid input error. Check the arguments and try again.
400	`INVALID_RECIPIENT_ID`	Recipient ID not valid
400	`INVALID_RECIPIENT_TYPE`	Recipient type isn't supported
400	`DEVICE_NOT_REACHABLE`	Device not reachable/offline. A directive to create the reminder is sent upon invocation if the reminder is set to go off within seven days.
400	`DEVICE_NOT_SUPPORTED`	Reminders aren't supported on this device.
400	`TOO_MANY_RECIPIENTS`	The number of recipients has exceeded the allowable threshold of 1. The Reminders API doesn't currently support bulk reminders.
401	`UNAUTHORIZED`	The incoming request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.
403	`MAX_REMINDERS_EXCEEDED`	Max limit of reminders on the device reached.
403	`FORBIDDEN`	The user doesn't have permission to perform this operation.
409	`MISSING_TIME_ZONE`	Device has no time zone set.
429	`MAX_RATE_EXCEEDED`	The request was throttled.
500	`INTERNAL_SERVER_ERROR`

Get a reminder

Retrieve a reminder by 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, make a GET request with the reminderId.

Request header example

GET /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access_token`	Header	LWA access token. For details, see Authentication.	String	Yes
`Content-Type`	Header	`application/json`	String	Yes
`reminderId`	Path	ID for the reminder to retrieve.	String	Yes

Request body example

The request has no body.

Response

A successful response returns HTTP/1.1 200 and a response body with the reminder.

Response body example

Single, absolute scheduled reminder

{
    "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
    },
    "reminder": {
        "reminderId": "b4ebac8b...",
        "createdTime": "2024-06-21T23:24:44.931Z",
        "updatedTime": "2024-06-21T23:24:45.066Z",
        "trigger": {
            "type": "SCHEDULED_ABSOLUTE",
            "scheduledTime": "2024-06-21T18: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"
    }
}

Recurring reminder

{
    "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
    },
    "reminder": {
        "reminderId": "aebbb725...",
        "createdTime": "2024-06-21T23:31:53.722Z",
        "updatedTime": "2024-06-21T23:31:53.957Z",
        "trigger": {
            "type": "SCHEDULED_ABSOLUTE",
            "scheduledTime": "2024-07-05T16:30: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=MONTHLY;INTERVAL=1;BYMONTHDAY=5;BYHOUR=16;BYMINUTE=30"
                ]
            }
        },
        "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": "3"
    }
}

Relative reminder

{
  "recipient": {
    "id": "amzn1.alexa.endpoint.did.1234",
    "type": "Endpoint"
  },
  "reminder": {
    "reminderId": "a64744c5...",
    "createdTime": "2024-06-21T20:15:57.272Z",
    "updatedTime": "2024-06-21T20:15:57.425Z",
    "trigger": {
      "type": "SCHEDULED_RELATIVE",
      "scheduledTime": "2024-06-21T14:17:57.235",
      "timeZoneId": "America/Denver",
      "offsetInSeconds": 120
    },
    "status": "ON",
    "alertInfo": {
      "spokenInfo": {
        "content": [
          {
            "locale": "en-US",
            "text": "Bingo starts at 5pm",
            "ssml": "<speak> Bingo starts at five p.m.</speak>"
          }
        ]
      }
    },
    "version": "3"
  }
}

Response body properties

Property	Description	Type
`recipient`	Recipient for this reminder.	Object
`recipient.type`	The type of the recipient. Possible values: `Endpoint`.	Enum
`recipient.id`	Unique identifier for the recipient. This is always an endpoint ID.	String
`reminder`	Contents of the reminder.	Object
`reminder.reminderId`	Unique ID of this reminder alert.	String
`reminder.createdTime`	Created time of this reminder in ISO 8601 format.	String
`reminder.updatedTime`	Last updated time of this reminder in ISO 8601 format.	String
`reminder.status`	Indicates the current status of the reminder. Possible values: `ON` – This is an active reminder that will play in the future. `COMPLETED` – The reminder has already triggered. Completed reminders are deleted after three days.	Enum
`reminder.version`	Version of this reminder alert. Version numbers are incremented upon update.	String
`reminder.trigger`	Contains information about the trigger for the reminder.	Object
`reminder.trigger.type`	Indicates type of trigger. Possible values: `SCHEDULED_ABSOLUTE` or `SCHEDULED_RELATIVE`.	Enum
`reminder.trigger.offsetInSeconds`	Applies when the `trigger.type` is to `SCHEDULED_RELATIVE`. Specifies the number of seconds after `requestTime` to play the reminder.	Integer
`reminder.trigger.scheduledTime`	Trigger date and time of the reminder in ISO 8601 format. For a relative reminder, this field contains the calculated trigger time based on the `requestTime` and `offsetInSeconds` provided when creating the reminder. For a recurring reminder, this field contains either the next trigger date and time, or the most recent trigger date and time, based on the recurrence rules. There is an expected delay between when an instance of the recurring reminder is delivered and when the device schedules the next instance. During this delay, the `scheduledTime` returns the most recent trigger date and time and not the future time. For longer recurrence intervals, the device schedules the next instance in three to four hours. For shorter intervals, the scheduling occurs in under an hour.	String
`reminder.trigger.timeZoneId`	A string containing the ID of the time zone. For details about time zones, see Time zones for absolute times.	Enum
`reminder.trigger.recurrence`	Contains recurrence information for reminders that repeat at regular intervals.	Object
`reminder.trigger.recurrence.startDateTime`	The start of the recurrence pattern. Includes both the date and time.	String
`reminder.trigger.recurrence.endDateTime`	The end of the recurrence pattern. Returns an empty string for reminders that don't have a defined end time and therefore repeat indefinitely.	String
`reminder.trigger.recurrence.recurrenceRules`	The recurrence pattern for a repeating reminder, in the RRULE format.	String
`reminder.alertInfo`	Contains information about the reminder.	Object
`reminder.alertInfo.spokenInfo`	Contains information about the spoken content in the reminder.	Object
`reminder.alertInfo.spokenInfo.content`	Contains the content of the reminder. There can be multiple entries because the caller might have specified different reminders for different locales.	Array of objects
`reminder.alertInfo.spokenInfo.content.locale`	Locale for the reminder content.	String
`reminder.alertInfo.spokenInfo.content.text`	Default text used for display and spoken content.	String
`reminder.alertInfo.spokenInfo.content.ssml`	Text used for spoken content, in Speech Synthesis Markup Language (SSML) format.	String

HTTP status codes

Status	Type	Message
400	`INVALID_REMINDER_ID`	The provided reminder ID is invalid.
401	`UNAUTHORIZED`	The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.
403	`FORBIDDEN`	The user doesn't have permission to perform this operation.
404	`REMINDER_NOT_FOUND`	Reminder doesn't exist.
429	`MAX_RATE_EXCEEDED`	The request was throttled
500	`INTERNAL_SERVER_ERROR`

Example 404 response body

HTTP/1.1 404 Not Found 
Content-Type: application/json 
X-Amzn-RequestId: \<UUID generated for this particular request\>

{  
    "type": "REMINDER_NOT_FOUND",
    "message": "Reminder does not exist."
}

Update a reminder

Updates a 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, make a PUT call with the reminderId and a request body. You must include the full reminder object with the trigger and alertInfo objects.

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 creating the reminder.

Request header example

PUT /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header parameters

Parameter	Located in	Description	Type	Required
`access_token`	Header	LWA access token. For details, see Authentication.	String	Yes
`Content-Type`	Header	`application/json`	String	Yes
`reminderId`	Path	ID for the reminder to update.	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`	Recipient for the reminder. Provide an object with the `type` and `id`. Important: This property accepts a single object. This is different from the create reminder operation, which uses the `recipients` property and accepts an array of recipient objects.	Object	Yes
`recipient.type`	Type of recipient. Accepted values: `Endpoint`.	Enum	Yes
`recipient.id`	Unique identifier for the recipient. This must be an endpoint ID.	String	Yes
`reminder`	Contents of the reminder.	Object	Yes
`reminder.requestTime`	Specifies the date and time to use when scheduling a relative reminder, specified in coordinated universal time (UTC). The API applies the `offsetInSeconds` to the `requestTime` to calculate the trigger time for a relative reminder. When not provided, defaults to the current date and time. Specify the `requestTime` in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`. Provide the `requestTime` in UTC time, not in the local time zone of the device. The API then uses the time zone of the device to calculate the reminder time. For example, assume the `requestTime` is `2024-06-21T22:30:00` and the `offsetInSeconds` is `1800` (30 minutes). 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.	String	No
`reminder.trigger`	Contains information about the trigger for a reminder.	Object	Yes
`reminder.trigger.type`	Indicates type of trigger. Accepted values: `SCHEDULED_ABSOLUTE` or `SCHEDULED_RELATIVE`.	Enum	Yes
`reminder.trigger.offsetInSeconds`	Applies when `trigger.type` is `SCHEDULED_RELATIVE`. Specifies the number of seconds after the `requestTime` to play the reminder. Not applicable when the `trigger.type` is `SCHEDULED_ABSOLUTE`.	Integer	Yes when the `trigger.type` is `SCHEDULED_RELATIVE`.
`reminder.trigger.scheduledTime`	Trigger date and time for a single reminder scheduled at an absolute time (`SCHEDULED_ABSOLUTE`). Provide the date and time in ISO 8601 format. For example, `2024-06-24T18:00:00.000` for June 24, 2024 at 6 PM. Not applicable when `trigger.type` is `SCHEDULED_RELATIVE`. Ignored for recurring reminders. Use the `trigger.recurrence.recurrenceRules` property to specify the time for a recurring reminder.	String	Yes when the `trigger.type` is `SCHEDULED_ABSOLUTE`.
`reminder.trigger.timeZoneId`	A string containing the ID of the time zone. For valid values, see List of tz database time zones identifiers. If you don't provide a time zone, the reminder defaults to use the time zone of the device. Not applicable when the `trigger.type` is `SCHEDULED_RELATIVE`. For details about time zones, see Time zones for absolute times.	Enum	No
`reminder.trigger.recurrence`	Specifies recurrence information for reminders that repeat at regular intervals. Not applicable when the `trigger.type` is `SCHEDULED_RELATIVE`.	Object	No
`reminder.trigger.recurrence.startDateTime`	Optional. The start of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, defaults to the current date and time.	Enum	No
`reminder.trigger.recurrence.endDateTime`	Optional. The end of the recurrence pattern. Defined with both the date and time in ISO 8601 format. When not provided, the recurring reminder continues indefinitely.	Enum	No
`reminder.trigger.recurrence.recurrenceRules`	The recurrence pattern for a repeating alert, in the RRULE format. Supported Values: `FREQ`, `BYMONTHDAY`, `BYDAY`, `BYHOUR`, `BYMINUTE`, `BYSECOND`, and `INTERVAL` The supported FREQ RRULE patterns are `FREQ=DAILY`, `FREQ=WEEKLY`, `FREQ=MONTHLY`, and `FREQ=YEARLY` The minimum interval between two recurrence values is one hour for the en-US locale and four hours for all other supported locales. The maximum interval for `DAILY`, `WEEKLY` and `MONTHLY` patterns is 31 days. The maximum interval for `YEARLY` pattern is one year. If these constraints aren't met, the request returns a 400 error.	String[]	Yes
`reminder.alertInfo`	Specifies information about the reminder.	Object	Yes
`reminder.alertInfo.spokenInfo`	Contains information about the spoken content in the reminder.	Object	Yes
`reminder.alertInfo.spokenInfo.content`	Contains the content of the reminder.	Object[]	Yes
`reminder.alertInfo.spokenInfo.content[].locale`	Defines the locale and language for the reminder text.	String	Yes
`reminder.alertInfo.spokenInfo.content[].ssml`	Text used for spoken content, in Speech Synthesis Markup Language (SSML) format. If you don't provide a value for this field, `alertInfo.spokenInfo.content.text` handles both text and spoken content. Reminders supports the SSML speak tag.	String	No
`reminder.alertInfo.spokenInfo.content[].text`	Default text used for display and spoken content. If you provide a value in the `ssml` property, the `text` property is used for display only.	String	Yes

Response

A successful response returns HTTP/1.1 204 No Content with no response body. If an error occurs, the response includes a response body with the error information.

Response body example

The following example shows the response body for an error response.

{  
    "type": "INVALID_INPUT_TIME_FORMAT",
    "message": "Request time date format incorrect."
}

Response body properties

Parameter	Description	Type
`type`	Short description.	Enum
`message`	Detailed description of the result.	String

HTTP status codes

Status	Type	Message
400	`INVALID_INPUT_TIME_FORMAT`	Request time date format incorrect.
400	`INVALID_TRIGGER`	Type and field don't match => `SCHEDULED_ABSOLUTE` has `offsetInSeconds` or `SCHEDULED_RELATIVE` has `scheduledTime`.
400	`TRIGGER_SCHEDULED_TIME_IN_PAST`	Scheduled time is in the past.
400	`INVALID_TRIGGER_SCHEDULED_TIME_FORMAT`	Date format isn't supported.
400	`INVALID_TRIGGER_TIME_ZONE`	Time zone isn't valid.
400	`INVALID_TRIGGER_RECURRENCE`	Recurrence pattern is invalid.
400	`UNSUPPORTED_TRIGGER_RECURRENCE`	Recurrence pattern is valid but not currently supported.
400	`UNSUPPORTED_TRIGGER_RECURRENCE_INTERVAL`	Recurrence pattern is valid but minimum interval between two occurrences isn't supported.
400	`INVALID_ALERT_INFO`	Alert info is missing locale / invalid locale format. Text string is too long.
400	`INVALID_TRIGGER_OFFSET`	Invalid relative time offset.
400	`UNSUPPORTED_SCHEDULED_TIME_FORMAT`	Unsupported trigger scheduled time format. Supported format is `YYYY-MM-DDTHH:mm:ss.SSS/YYYY-MM-DDTHH:mm:ss/YYYY-MM-DDTHH:mm`.
400	`INVALID_INPUT`	Invalid input error. Check the arguments and try again.
400	`INVALID_RECIPIENT_ID`	Recipient ID not valid
400	`INVALID_RECIPIENT_TYPE`	Recipient type isn't supported
400	`DEVICE_NOT_REACHABLE`	Device not reachable/offline. A directive to create the reminder is sent upon invocation if the reminder is set to go off within seven days.
400	`DEVICE_NOT_SUPPORTED`	Reminders aren't supported on this device.
400	`TOO_MANY_RECIPIENTS`	The number of recipients has exceeded the allowable threshold of 1. The Reminders API doesn't currently support bulk reminders.
401	`UNAUTHORIZED`	The incoming request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.
403	`MAX_REMINDERS_EXCEEDED`	Max limit of reminders on the device reached.
403	`FORBIDDEN`	The user doesn't have permission to perform this operation.
404	`REMINDER_NOT_FOUND`	Reminder to update doesn't exist.
409	`MISSING_TIME_ZONE`	Device has no time zone set.
409	`VERSION_CONFLICT`	The given version doesn't match latest version. This could occur if there are two concurrent updates for the same reminder.
429	`MAX_RATE_EXCEEDED`	The request was throttled
500	`INTERNAL_SERVER_ERROR`

Delete a reminder

Deletes the specified 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 delete a reminder, make a PUT call with the reminderId for the reminder to delete.

Request header example

DELETE /v2/alerts/reminders/{reminderId}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header parameters

Parameter	Located in	Description	Type	Required
`access_token`	Header	LWA access token. For details, see Authentication.	String	Yes
`Content-Type`	Header	`application/json`	String	Yes
`reminderId`	Path	ID for the reminder to delete.	String	Yes

Request body example

The request has no body.

Response

A successful call returns HTTP/1.1 204 No Content. If an error occurs, the response includes a response body with the error information.

Response body example

The following example shows the response body for an error response.

{
  "type": "FORBIDDEN",
  "message": "The user does not have permission to perform this operation."
}

Response body properties

Parameter	Description	Type
`type`	Short description.	Enum
`message`	Detailed description of the result.	String

HTTP status codes

Status	Type	Message
400	`INVALID_REMINDER_ID`	The provided reminder ID is invalid.
400	`DEVICE_NOT_REACHABLE`	Device not reachable/offline.
401	`UNAUTHORIZED`	The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.
403	`FORBIDDEN`	The user doesn't have permission to perform this operation.
404	`REMINDER_NOT_FOUND`	Reminder doesn't exist.
429	`MAX_RATE_EXCEEDED`	The request was throttled
500	`INTERNAL_SERVER_ERROR`

Get all reminders on an endpoint

Gets all the scheduled reminders for a specified endpoint. There is a 250 reminder limit on a device per caller.

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 the reminders for an endpoint, make a GET call and set recipient.id to the endpoint ID.

GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.<endpointId>&recipient.type=Endpoint&owner=~caller

Request header example

GET /v2/alerts/reminders?recipient.id=amzn1.alexa.endpoint.did.{endpointId}&recipient.type=Endpoint&owner=~caller HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {Access Token}

Request header and query parameters

Parameter	Located in	Description	Type	Required
`recipient.id`	Query	Unique identifier for the recipient. This is an endpoint ID.	String	Yes
`recipient.type`	Query	Type of recipient. Accepted values: `Endpoint`	String	Yes
`owner`	Query	Owner of the reminders to retrieve. Accepted values: `~caller`. This means that operation returns reminders created by the user calling the operation.	String	Yes
`access_token`	Header	LWA access token. For details, see Authentication.	String	Yes
`Content-Type`	Header	`application/json`	String	Yes

Request body example

The request has no body.

Response

Returns the reminders for the specified endpoint.

Response body example

{
  "results": [
    {
      "recipient": {
        "id": "amzn1.alexa.endpoint.did.1234",
        "type": "Endpoint"
      },
      "reminder": {
        "reminderId": "84d26afa...",
        "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": "c85c15a9...",
        "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

The operation returns an array of results (results[]). Each result in the array has the properties shown in the following table.

Property	Description	Type
`recipient`	Recipient for this reminder.	Object
`recipient.type`	The type of the recipient. Possible values: `Endpoint`.	Enum
`recipient.id`	Unique identifier for the recipient. This is always an endpoint ID.	String
`reminder`	Contents of the reminder.	Object
`reminder.reminderId`	Unique ID of this reminder alert.	String
`reminder.createdTime`	Created time of this reminder in ISO 8601 format.	String
`reminder.updatedTime`	Last updated time of this reminder in ISO 8601 format.	String
`reminder.status`	Indicates the current status of the reminder. Possible values: `ON` – This is an active reminder that will play in the future. `COMPLETED` – The reminder has already triggered. Completed reminders are deleted after three days.	Enum
`reminder.version`	Version of this reminder alert. Version numbers are incremented upon update.	String
`reminder.trigger`	Contains information about the trigger for the reminder.	Object
`reminder.trigger.type`	Indicates type of trigger. Possible values: `SCHEDULED_ABSOLUTE` or `SCHEDULED_RELATIVE`.	Enum
`reminder.trigger.offsetInSeconds`	Applies when the `trigger.type` is to `SCHEDULED_RELATIVE`. Specifies the number of seconds after `requestTime` to play the reminder.	Integer
`reminder.trigger.scheduledTime`	Trigger date and time of the reminder in ISO 8601 format. For a relative reminder, this field contains the calculated trigger time based on the `requestTime` and `offsetInSeconds` provided when creating the reminder. For a recurring reminder, this field contains either the next trigger date and time, or the most recent trigger date and time, based on the recurrence rules. There is an expected delay between when an instance of the recurring reminder is delivered and when the device schedules the next instance. During this delay, the `scheduledTime` returns the most recent trigger date and time and not the future time. For longer recurrence intervals, the device schedules the next instance in three to four hours. For shorter intervals, the scheduling occurs in under an hour.	String
`reminder.trigger.timeZoneId`	A string containing the ID of the time zone. For details about time zones, see Time zones for absolute times.	Enum
`reminder.trigger.recurrence`	Contains recurrence information for reminders that repeat at regular intervals.	Object
`reminder.trigger.recurrence.startDateTime`	The start of the recurrence pattern. Includes both the date and time.	String
`reminder.trigger.recurrence.endDateTime`	The end of the recurrence pattern. Returns an empty string for reminders that don't have a defined end time and therefore repeat indefinitely.	String
`reminder.trigger.recurrence.recurrenceRules`	The recurrence pattern for a repeating reminder, in the RRULE format.	String
`reminder.alertInfo`	Contains information about the reminder.	Object
`reminder.alertInfo.spokenInfo`	Contains information about the spoken content in the reminder.	Object
`reminder.alertInfo.spokenInfo.content`	Contains the content of the reminder. There can be multiple entries because the caller might have specified different reminders for different locales.	Array of objects
`reminder.alertInfo.spokenInfo.content.locale`	Locale for the reminder content.	String
`reminder.alertInfo.spokenInfo.content.text`	Default text used for display and spoken content.	String
`reminder.alertInfo.spokenInfo.content.ssml`	Text used for spoken content, in Speech Synthesis Markup Language (SSML) format.	String

HTTP status codes

Status	Type	Message
400	`INVALID_REMINDER_ID`	The provided reminder ID is invalid.
400	`INVALID_RECIPIENT_TYPE`	Th provided recipient type is invalid
401	`UNAUTHORIZED`	The request is missing a valid access token in the Authorization HTTP Header. The token might be malformed or have expired.
403	`FORBIDDEN`	The user doesn't have permission to perform this operation.
429	`MAX_RATE_EXCEEDED`	The request was throttled
500	`INTERNAL_SERVER_ERROR`

Alexa Smart Properties REST API Reference

Was this page helpful?

Provide feedback

Last updated: Aug 01, 2024

Reminders API

API endpoint

Authentication

Operations

Create a reminder

Request

Request header example

Request path and header parameters

Request body examples

Request body properties

Time zones for absolute times

Response

Response body examples

Response headers

Response body properties

HTTP status codes

Get a reminder

Request

Request header example

Request path and header parameters

Request body example

Response

Response body example

Response body properties

HTTP status codes

Example 404 response body

Update a reminder

Request

Request header example

Request header parameters

Request body example

Request body properties

Response

Response body example

Response body properties

HTTP status codes

Delete a reminder

Request

Request header example

Request header parameters

Request body example

Response

Response body example

Response body properties

HTTP status codes

Get all reminders on an endpoint

Request

Request header example

Request header and query parameters

Request body example

Response

Response body example

Response body properties

HTTP status codes

Related topics

Was this page helpful?