Proactive Suggestion API

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

Note: This API is only available to registered Alexa Smart Properties for healthcare partners. See Get Started with Alexa Smart Properties for Healthcare APIs.

For Alexa Smart Properties for hospitality property operators, the home screen on Alexa multimodal devices provides an opportunity for branding, upselling products and services (such as happy hours and spa services), and informing guests about events, updates, and skills.

As a solution integrator, you can use the Alexa Proactive Suggestion REST API to enable property managers to provide visual content to Alexa as suggestions. From those suggestions, Alexa chooses content items and displays them to customers on their devices' home screens. To create the visual experience for your suggestions, you use Alexa Presentation Language (APL).

API endpoint

The endpoint for the Proactive Suggestion API is https://api.amazonalexa.com.

Note: Use one of the following endpoints, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

Authentication

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

Operations

The Proactive Suggestion API includes the following operations.

Description	HTTP method and path
Create a campaign	`POST /v1/proactive/campaigns`
List campaigns	`GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken}`
Query campaigns	`POST /v1/proactive/campaigns/query`
Get a campaign	`GET /v1/proactive/campaigns/{campaignId}`
Delete a campaign	`DELETE /v1/proactive/campaigns/{campaignId}`

Create a campaign

Creates a campaign that renders the content as a suggestion to targeted recipients.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

Request body format

The request body contains a campaign entity that encapsulates the suggestion along with recipients and scheduling specifics for the information. The following example shows a campaign entity.

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
       (polymorphic object of type units)
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-01-01T10:00:00.00Z",
            "end": "2021-01-31T10:00:00.00Z"
        }
    }
}

Request body example

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "en-US",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Example notification title.",
                          "body": "Example notification text.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                          
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                       
                    }
                  },
                  {
                    "locale": "pt-BR",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Exemplo de título de notificação.",
                          "body": "Texto de notificação de exemplo.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                             
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                         
                    }
                  }
                ]
            }
        }]
   },
   "targeting": {
      "type": "UNITS",
      "values": [
        {
           "id": "amzn1.alexa.unit.did.unitId"
        }
      ]
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   }
}

Request body parameters

Field	Description	Type	Required
`suggestion`	A piece of information that Alexa can proactively deliver to users.	Object	Yes
`suggestion.variants[]`	A list of suggestion variants to present to users. The list must contain at least one variant.	Array	Yes
`suggestion.variants[].placement`	The place where the content can be rendered.	Object	Yes
`suggestion.variants[].placement.channel`	The name of the channel. Currently the only supported value is `"HOME"`, which refers to the home screen on Alexa multimodal devices.	String	Yes
`suggestion.variants[].content.values[]`	Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present.	Object	Yes
`suggestion.variants[].content.values[].locale`	The locale in which the content is rendered, in IETF BCP 47 format.	String	Yes
`suggestion.variants[].content.values[].document`	A link to the APL document to use for rendering. For details, see Use a linked document with RenderDocument. Not all APL features are supported.	String	Yes
`suggestion.variants[].content.values[].document.type`	The APL document type. Must be `Link`.	String	Yes
`suggestion.variants[].content.values[].document.src`	The APL document link. Currently only `"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"` is supported.	String	Yes
`suggestion.variants[].content.values[].datasources`	Object that can contain other objects that can be used to bind data to the APL document.	Map of data source objects	Yes
`suggestion.variants[].content.values[].datasources.displayText.title`	The text to be rendered in the title field of the document. This text is displayed in a large font on the home screen. Maximum length is 25 characters.	String	No
`suggestion.variants[].content.values[].datasources.displayText.body`	The text to be rendered in the body field of the document. This text is displayed in a smaller font below the title on the home screen. Maximum length is 60 characters.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action`	Object that specifies a skill to launch when the user taps a card on the screen.	Object	No
`suggestion.variants[].content.values[].datasources.displayText.action.type`	The type of action. The only allowed value is `SkillConnection`.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action.uri`	The skill to launch. Use the format `"connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345"` and replace the provider value with your skill ID.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action.input`	Unused. Leave empty.	Object	No
`suggestion.variants[].content.values[].datasources.background`	Object that specifies different aspects of the background.	Object	No
`suggestion.variants[].content.values[].datasources.background.backgroundImageSource`	URL for the background image.	String	Yes, if you include `suggestion.variants[].content.values[].datasources.background`
`targeting`	Polymorphic object that defines the recipients of the campaign. Target type: units.	Object	Yes
`scheduling`	The scheduling information for the campaign.	Object	Yes
`scheduling.activationWindow`	A time window object specifying the time in which a campaign is active.	Object	Yes
`scheduling.activationWindow.start`	The start of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.	String	Yes
`scheduling.activationWindow.end`	The end of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. Must be later than or equal to the start time.	String	Yes

Units target

The units that the campaign targets.

{
   "type": "UNITS",
   "values": [
      {
         "id": "amzn1.alexa.unit.did.unitId"
      }
   ]
}

Field	Description	Type	Required
`type`	The type of targeting criteria that should be applied. Accepted value: `UNITS`.	String	Yes
`values[]`	A list of objects that contain rooms' unit IDs in the form of `amzn1.alexa.unit.did.{id}`. This list can contain at most 100 unit IDs. Note: The unit IDs must be for rooms, not properties or room types.	Array	Yes
`values[].id`	A room's unit ID in the form of `amzn1.alexa.unit.did.{id}`.	String	Yes

Note: The legacy unit target format (which has a list of units.items) still works. However, for new implementations, use the current format of the API shown previously.

Success response header

HTTP/1.1 202 Accepted
Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body format

{
    "campaignId": "{exampleId}"
}

Response body parameters

Field	Description	Type
`campaignId`	Campaign ID for the campaign. You use this ID when you delete the campaign or get the campaign.	String

Note: Both the success and error responses also return a referenceId, which is a unique identifier that Amazon generates for a request.

HTTP response codes

Status Code	Name	Description
201	Created	The campaign was successfully created.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
429	Too Many Requests	Request has been throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

Update a campaign

Updates the suggestion entity of a campaign.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

PUT /v1/proactive/campaigns/{campaignId}/suggestion HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    }
}

Request body example

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "en-US",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Example notification title.",
                          "body": "Example notification text.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                          
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                       
                    }
                  },
                  {
                    "locale": "pt-BR",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Exemplo de título de notificação.",
                          "body": "Texto de notificação de exemplo.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                             
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                         
                    }
                  }
                ]
            }
        }
     ]
   }
}

Request body parameters

Field	Description	Type	Required
`suggestion`	A piece of information that Alexa can proactively deliver to users.	Object	Yes
`suggestion.variants[]`	A list of suggestion variants to present to users. The list must contain at least one variant.	Array	Yes
`suggestion.variants[].placement`	The place where the content can be rendered.	Object	Yes
`suggestion.variants[].placement.channel`	The name of the channel. Currently the only supported value is `"HOME"`, which refers to the home screen on Alexa multimodal devices.	String	Yes
`suggestion.variants[].content.values[]`	Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present.	Object	Yes
`suggestion.variants[].content.values[].locale`	The locale in which the content is rendered, in IETF BCP 47 format.	String	Yes
`suggestion.variants[].content.values[].document`	A link to the APL document to use for rendering. For details, see Use a linked document with RenderDocument. Not all APL features are supported.	String	Yes
`suggestion.variants[].content.values[].document.type`	The APL document type. Must be `Link`.	String	Yes
`suggestion.variants[].content.values[].document.src`	The APL document link. Currently only `"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"` is supported.	String	Yes
`suggestion.variants[].content.values[].datasources`	Object that can contain other objects that can be used to bind data to the APL document.	Map of data source objects	Yes
`suggestion.variants[].content.values[].datasources.displayText.title`	The text to be rendered in the title field of the document. This text is displayed in a large font on the home screen. Maximum length is 25 characters.	String	No
`suggestion.variants[].content.values[].datasources.displayText.body`	The text to be rendered in the body field of the document. This text is displayed in a smaller font below the title on the home screen. Maximum length is 60 characters.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action`	Object that specifies a skill to launch when the user taps a card on the screen.	Object	No
`suggestion.variants[].content.values[].datasources.displayText.action.type`	The type of action. The only allowed value is `SkillConnection`.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action.uri`	The skill to launch. Use the format `"connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345"` and replace the provider value with your skill ID.	String	No
`suggestion.variants[].content.values[].datasources.displayText.action.input`	Unused. Leave empty.	Object	No
`suggestion.variants[].content.values[].datasources.background`	Object that specifies different aspects of the background.	Object	No
`suggestion.variants[].content.values[].datasources.background.backgroundImageSource`	URL for the background image.	String	Yes, if you include `suggestion.variants[].content.values[].datasources.background`

Success response header

HTTP/1.1 202 Accepted
Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body format

The response has no body.

Response body parameters

The response has no body.

HTTP response codes

Status Code	Name	Description
202	Accepted	The request was accepted.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
404	Not Found	The campaign isn't found.
429	Too Many Requests	Request has been throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

List campaigns

Lists the campaigns you've created.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

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

Request body format

None.

Request path parameters

Field	Description	Type	Required
`maxResults`	Maximum number of results to display. The value of this parameter must be between 1 and 10. The default value is 10.	Integer	No
`nextToken`	Continuation token returned in the response object of the previous response to list campaigns.	String	No

Success response header

Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body format

{
   "results": [
      {
         "campaignId": "campaignId",
         "suggestion": {
            "variants": [{
               "placement": {
                  "channel": "HOME"
               },
               "content": {
                  "values": [{
                     "locale": "en-US",
                     "document": {},
                     "datasources": {}
                  }]
               }
            }]          
         },
         "targeting": {
            (polymorphic object of type units)
         },
         "scheduling": {
            "activationWindow": {
               "start": "2021-01-01T10:00:00.00Z",
               "end": "2021-01-31T10:00:00.00Z"
            }
         },
         "validationStatus": {
            "value": "string enum",   // IN_PROGRESS, APPROVED, or REJECTED
            "reason": "Explanation"
         }
     },
     {
        ... (another campaign and status) ...
     }
   ],
   "paginationContext": {
      "nextToken": "token from previous call"
   }
}

Response body parameters

Field	Description	Type
`results[]`	The list of campaigns you created, along with a validation status for each.	Array
`results[].campaign`	The details you submitted when you created the campaign. For the fields, see the request body format for creating a campaign.	Object
`results[].validationStatus`	The latest validation status for the campaign.	Object
`results[].validationStatus.value`	Enum that describes the latest validation status for the campaign. Valid values: `IN_PROGRESS`, `APPROVED`, `REJECTED`.	String
`results[].validationStatus.reason`	Explanation, if applicable, for the validation status value.	String
`paginationContext`	Object containing pagination information. If omitted, all evaluation results were already returned.	Object
`paginationContext.nextToken`	Continuation token that you use in the next call to list campaigns.	String

HTTP response codes

Status Code	Name	Description
202	Request Accepted	The request was accepted.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
429	Too Many Requests	Request has been throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

Query campaigns

Queries the campaigns for a list of units.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

POST /v1/proactive/campaigns/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

The following query returns active suggestions using one or more units.

{
    "query": {
        "and": [
            {
                "or": [
                    {
                        "match": {
                            "targeting.values.id": "U1"
                        }
                    },
                    {
                        "match": {
                            "targeting.values.id": "U2"
                        }
                    }
                ]
            },
            {
                "match": {
                    "targeting.type": "UNITS"
                }
            }
        ]
    },
    "paginationContext": {
        "maxResults": 10,
        "nextToken": "paginationTokenString"
    }
 }

Request body parameters

Field	Description	Type	Required
`query`	Object that provides filtering conditions to get suggestions. This object has only one allowed field, which can be either `AND` or `OR`. Each of these fields is a list type. These fields are usually followed by a filtering condition on a certain attribute of suggestions. These fields can also encompass another list of nested AND/OR filtering conditions. Queryable fields are JSON-flattened using the "`.`" operator. The query must adhere to the following rules: The query must match the structure shown in the request body examples. The query can only have one `and` operation. The only allowed condition is `match`. `query.and` is a list of two items. `query.and.or` is a list of minimum size 1 and maximum size 100. The only allowed field is `targeting.values.id`. The value of `targeting.type` can only be `UNITS`.	Query object	Yes
`paginationContext`	Object that contains pagination information.	Object	No
`paginationContext.maxResults`	Maximum number of suggestions to return in one request. The value of this parameter must be between 1 and 10. The default value is 10.	Integer	No
`paginationContext.nextToken`	Token you use to retrieve subsequent data in the previous response, if applicable. This field must either be null or a valid value returned from the server.	String	No

Query object

Field	Description	Type	Required
`and`	Conditions to apply using a logical `AND` operation. Example: `{"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}`	Array	No
`or`	Conditions to apply using a logical `OR` operation. Example: `{"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}`	Array	No

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: sample-request-id-value

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

{
    "paginationContext": {
        "nextToken": "paginationTokenString"
    },
    "results": [
        {
            "campaignId": "sample-id",
            "validationStatus": {
                "value": "IN_PROGRESS",
                "reason": "Explanation"
            },
            "suggestion": {
                "variants": [
                    {
                        "placement": {
                            "channel": "HOME"
                        },
                        "content": {
                            "values": [
                                {
                                    "locale": "en-US",
                                    "document": {
                                        "type": "Link",
                                        "src": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "Light and warm patio breakfast",
                                            "body": "Breakfast is served until 11:30 am!"
                                        }
                                    }
                                },
                                {
                                    "locale": "pt-BR",
                                    "document": {
                                        "type": "Link",
                                        "src": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "Café da manhã leve e quente no pátio",
                                            "body": "O café da manhã é servido até as 11h30!"
                                        }
                                    },
                                    "background": {
                                        "backgroundImageSource": "https://url-of-image.jpg"
                                    }
                                }
                            ]
                        }
                    }
                ]
            },
            "targeting": {
                "type": "UNITS",
                "values": [
                    {
                        "id": "amzn1.alexa.unit.did.unitId"
                    }
                ]
            },
            "scheduling": {
                "activationWindow": {
                    "start": "2021-01-01T10:00:00.00Z",
                    "end": "2021-01-31T10:00:00.00Z"
                }
            }
        }
    ]
 }

Response body parameters

Field	Description	Type
`paginationContext`	Object containing pagination information. If omitted, all evaluation results were already returned.	Object
`paginationContext.nextToken`	Continuation token that you use in the next call to query campaigns. If this field is null, all evaluation results were already returned. If this field isn't null, there are more evaluation results in the next page.	String
`results[*]`	The list of campaigns you created for the unit, along with a validation status for each campaign.	Array
`results[*].campaignId`	Campaign ID.	String
`results[*].validationStatus`	The latest validation status for the campaign.	Object
`results[*].validationStatus.value`	Enum that describes the latest validation status for the campaign. Valid values: `IN_PROGRESS`, `APPROVED`, `REJECTED`.	String
`results[*].validationStatus.reason`	Explanation, if applicable, for the validation status value.	String
`results[*].suggestion`	The message to deliver to users.	Object
`results[].suggestion.variants[]`	A list of suggestion variants to present to users. The list must contain at least one variant.	Array
`results[].suggestion.variants[].placement`	The place where the content can be rendered.	Object
`results[].suggestion.variants[].placement.channel`	The name of the channel. Currently the only supported value is `"HOME"`, which refers to the home screen on Alexa multimodal devices.	String
`results[].suggestion.variants[].content.values[*]`	Object that contains localized presentation data specific to the default content type. At least one localized presentation data element must be present.	Array
`results[].suggestion.variants[].content.values[*].locale`	The locale in which the content is rendered, in IETF BCP 47 format.	String
`results[].suggestion.variants[].content.values[*].document`	A link to the APL document to use for rendering. For details, see Use a linked document with RenderDocument. Not all APL features are supported.	Object
`results[].suggestion.variants[].content.values[*].document.type`	The APL document type. Must be `Link`.	String
`results[].suggestion.variants[].content.values[*].document.src`	The APL document link. Currently only `"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"` is supported.	String
`results[].suggestion.variants[].content.values[*].datasources`	Object that can contain other objects that can be used to bind data to the APL document.	Object
`results].suggestion.variants[].content.values[*].datasources.displayText.title`	The text to be rendered in the title field of the document. This text is displayed in a large font on the home screen. Maximum length is 25 characters.	String
`results[].suggestion.variants[].content.values[*].datasources.displayText.body`	The text to be rendered in the body field of the document. This text is displayed in a smaller font below the title on the home screen. Maximum length is 60 characters.	String
`results[].suggestion.variants[].content.values[*].datasources.background`	Object that specifies different aspects of the background.	Object
`results[].suggestion.variants[].content.values[*].datasources.background.backgroundImageSource`	URL for the background image.	String
`results[*].targeting`	Polymorphic object that defines the recipients of the campaign. One of three types of targets: units, users, or skill subscribers.	Object
`results[*].targeting.type`	The type of targeting criteria that should be applied.	String
`results[].targeting.values[]`	A list of objects that contain rooms' unit IDs in the form `amzn1.alexa.unit.did.{id}`.	Array
`results[].targeting.values[].id`	A room's unit ID in the form `amzn1.alexa.unit.did.{id}`.	String
`results[*].scheduling`	The scheduling information for the campaign.	Object
`results[*].scheduling.activationWindow`	A time window object specifying the time in which a campaign is active.	Object
`scheduling.activationWindow.start`	The start of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.	String
`scheduling.activationWindow.end`	The end of the time window. A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. Must be later than or equal to the start time.	String

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too Many Requests	Request is throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

Get a campaign

Retrieves a campaign that you created.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

GET /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body format

None.

Request path parameters

Field	Description	Type	Required
`campaignId`	The ID of the campaign to retrieve. This value is returned when you create a campaign.	String	Yes

Success response header

Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body format

{
   "campaignId": "campaignId",
   "suggestion": {
      "variants": [{
         "placement": {
            "channel": "HOME"
         },
         "content": {
            "values": [{
               "locale": "en-US",
               "document": {},
               "datasources": {}
            }]
         }
      }]  
   },
   "targeting": {
      (polymorphic object of type units)
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   },
   "validationStatus": {
      "value": "string enum",   // IN_PROGRESS, APPROVED, or REJECTED
      "reason": "Explanation"
   }
}

Response body parameters

Field	Description	Type
Campaign information	The details you submitted when you created the campaign. For the fields, see the request body format for creating a campaign.	Object
`ValidationStatus`	The status of the campaign validation.	Object
`validationStatus`	The latest validation status for the campaign.	Object
`validationStatus.value`	The latest validation status for the campaign. Valid values: `IN_PROGRESS`, `APPROVED`, `REJECTED`.	String
`validationStatus.reason`	Explanation, if applicable, for the validation status value.	String

HTTP response codes

Status Code	Name	Description
200	Successful	The request was processed successfully.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
404	Not Found	The campaign to delete isn't found.
429	Too Many Requests	Request has been throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.
503	Service Unavailable	Service is temporarily unavailable.

Delete a campaign

Deletes a campaign.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US	US, UK, FR, CA, IT, DE	US

Request format

DELETE /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`campaignId`	The ID of the campaign to delete. This value is returned when you create a campaign.	String	Yes

Request body

None.

Success response header

HTTP/1.1 202 OK
Host: {host value used in the request}
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

HTTP response codes

Status Code	Name	Description
202	Accepted	The delete request for the specified campaign has been accepted. The campaign will be deleted, but there's no guarantee that the suggestion wasn't already delivered.
400	Bad Request	The request is malformed or is missing one or more required parameters.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The access token is valid, but the user doesn't have the needed LWA scope permissions.
404	Not Found	The campaign to delete isn't found.
429	Too Many Requests	Request has been throttled.
500	Internal Server Error	The request couldn't be handled because of an internal service error.

Last updated: Jun 14, 2022

Proactive Suggestion API

API endpoint

Authentication

Operations

Create a campaign

Request format

Request body format

Request body example

Request body parameters

Units target

Success response header

Response body format

Response body parameters

HTTP response codes

Update a campaign

Request format

Request body format

Request body example

Request body parameters

Success response header

Response body format

Response body parameters

HTTP response codes

List campaigns

Request format

Request body format

Request path parameters

Success response header

Response body format

Response body parameters

HTTP response codes

Query campaigns

Request format

Request body format

Request body parameters

Query object

Success response header

Response body example

Response body parameters

HTTP response codes

Get a campaign

Request format

Request body format

Request path parameters

Success response header

Response body format

Response body parameters

HTTP response codes

Delete a campaign

Request format

Request path parameters

Request body

Success response header

Response body

HTTP response codes

Related topics