Unit Settings 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 hospitality partners. See Get Started with Alexa Smart Properties for Hospitality APIs.

Use the Unit API to manage unit settings for Alexa Smart Properties for hospitality units such as rooms.

Note: When you create a unit, you must set the default music provider and the default music station in order to be able to control the music experience in the unit.

API endpoint

The endpoint of the Unit Settings API is https://api.amazonalexa.com.

Authentication

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

Operations

The Unit Settings API includes the following operations.

Operation	HTTP Method and URI
Get the default music station setting	`GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences`
Set the default music station setting	`PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences`
Delete all alarms for a unit	`DELETE /v1/alerts/alarms?unitId={unitId}`
Delete all reminders for a unit	`DELETE /v1/alerts/reminders?unitId={unitId}`

Get the default music station setting

Call GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to get the default music station preferences for a given unit.

This operation is available in the following countries.

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

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

Host: api.amazonalexa.com
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 example

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

Response body parameters

Field	Description	Type	Required
`providerId`	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
`stationId`	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
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	The request is throttled.

Set the default music station setting

Call PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to set the default music station preferences for a given unit.

This operation is available in the following countries.

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

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body example

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

Request body parameters

Field	Description	Type	Required
`providerId`	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
`stationId`	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

Host: api.amazonalexa.com
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.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request	The request is malformed or is missing one or more required parameters.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too many requests	The request is throttled.

Delete all alarms for a unit

Call DELETE /v1/alerts/alarms?unitId={unitId} to delete all alarms on all endpoints in a unit. This API call is an extension of the AVS Alarms REST API.

This operation is available in the following countries.

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

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

DELETE /v1/alerts/alarms?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

Request body

None.

Request parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

Host: api.amazonalexa.com
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

Upon successful deletion, the server returns an HTTP 204 No Content status response. A successful payload does not contain a body.

HTTP/1.1 204 No Content
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "code": "{Code}",
        "endpointId": "{EndpointId}",
        "description": "{ErrorMessage}"
    }]
}

Error response parameters

Field	Description	Type	Required
`code`	The error name, for example, `DEVICE_UNREACHABLE`.	String	No
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	No
`description`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

Error handling for multiple device failure

If there is an error on a particular device in the unit, the API records the failure and continues deleting alarms on the remaining devices. The response returns the endpoint ID and reason for each device failure, as shown in the following example.

If there are multiple failures with the same failure reason, the response returns the most accurate HTTP status code (for example, 504 DEVICE_NOT_REACHABLE if all failures are because of unreachable devices).
If there are multiple failures with different failure reasons, the response returns the 500 INTERNAL_SERVER_ERROR status code, with more specific details for each failure listed in the array of errors.

HTTP/1.1 500 INTERNAL_SERVER_ERROR
Content-Type: application/json

{
    "errors": [{
            "code": "DEVICE_NOT_REACHABLE",
            "endpointId": "{ENDPOINT_ID_1}",
            "description": "Device not reachable / offline"
        },
        {
            "code": "INTERNAL_SERVER_ERROR",
            "endpointId": "{ENDPOINT_ID_2}",
            "description": "Unexpected Error"
        }
    ]
}

HTTP response codes

Status Code	Name	Description
204	No content	Alarms were successfully deleted on all endpoints in the unit. Note that this status code is returned even if the unit has no alarms to delete.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The authentication token is invalid or doesn't have access to the resource.
401	FORBIDDEN	The user doesn't have permission to perform the operation, or the unit doesn't exist.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
504	DEVICE_NOT_REACHABLE	The device is offline or unreachable.

Delete all reminders for a unit

Call DELETE /v1/alerts/reminders?unitId={unitId} to delete all reminders on all endpoints in a unit.

This operation is available in the following countries.

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

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

DELETE /v1/alerts/reminders?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

Request body

None.

Request parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

Host: api.amazonalexa.com
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

Upon successful deletion, the server returns an HTTP 204 No Content status response. A successful payload doesn't contain a body.

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "type": "{ErrorType}",
        "endpointId": "{EndpointId}",
        "message": "{ErrorMessage}"
    }]
}

Error response parameters

Field	Description	Type	Required
`type`	The error name, such as `DEVICE_UNREACHABLE`.	String	No
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	No
`message`	The error message for the error. The error message appears only for debugging/logging purposes. You must not share it with the user. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Reminders were successfully deleted on all endpoints in the unit. Note that this status code is returned even if the unit has no reminders to delete.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The authentication token is invalid or doesn't have access to the resource.
403	FORBIDDEN	The user doesn't have permission to perform the operation, or the unit doesn't exist.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
504	DEVICE_NOT_REACHABLE	The device is offline or unreachable.

Provider and station ID reference

The following table lists the supported providerId and stationId values. Country/region string is in ISO 3166-1 alpha-2 format.

Country/Region String	Provider ID	Station ID	Description
US	I_HEART_RADIO	4802	American Top 40
US	I_HEART_RADIO	4426	Classic Rock (The Classic Rock Channel)
US	I_HEART_RADIO	4429	Hip Hop / R&D (The Beat)
US	I_HEART_RADIO	4422	Pop / Top 40 (Hit Nation)
US	I_HEART_RADIO	4418	Country (iHeartCountry Radio)
US	I_HEART_RADIO	7193	Latin (Latino Hits)
US	I_HEART_RADIO	5953	Dance (Evolution)
US	I_HEART_RADIO	5162	Christian / Gospel (K-LOVE)
US	I_HEART_RADIO	4242	Jazz (Smooth Jazz)
US	I_HEART_RADIO	6377	Classical (Classical Highlights)
US	I_HEART_RADIO	4409	Mix / Variety (Today's Mix)
US	I_HEART_RADIO	4717	Oldies (Real Oldies)
US	I_HEART_RADIO	4447	Alternative (Alternative Radio)
US	I_HEART_RADIO	7312	Wynn Music
US	I_HEART_RADIO	8757	Legoland Radio
US	I_HEART_RADIO	9414	Disney Resorts Radio
CA	TUNEIN	s24752	VOCM
CA	TUNEIN	s12375	CFCY-FM
CA	TUNEIN	s31141	NEWSTALK 1010
CA	TUNEIN	s31204	CJAD 800
CA	TUNEIN	s12364	Classical FM
CA	TUNEIN	s20305	CBC Radio One Toronto
CA	TUNEIN	s31282	Lite 92.1
CA	TUNEIN	s7723	KX 94.7
CA	TUNEIN	s95963	Coast 101.1
CA	TUNEIN	s24756	ROCK 95
CA	TUNEIN	s12492	CHOI 98, 1 Radio X
CA	TUNEIN	s12363	LITE 88.5
CA	TUNEIN	s31140	580 CFRA
CA	TUNEIN	s24648	OZFM
CA	TUNEIN	s31229	JAZZ.FM91
CA	TUNEIN	s31182	Zoomer Radio
CA	TUNEIN	s47709	Cool 100.1 FM1
CA	TUNEIN	s31267	AM 800 CKLW
CA	TUNEIN	s122372	102.3 Now Radio
CA	TUNEIN	s12182	Seaside FM
CA	TUNEIN	s25284	CBC Radio One Halifax
CA	TUNEIN	s24761	KX96
CA	TUNEIN	s31121	The Fox 99.9
CA	TUNEIN	s292162	CNN International
CA	TUNEIN	s24940	BBC Radio 2
UK	TUNEIN	s45300	Jazz (Jazz FM)
UK	TUNEIN	s287575	Relaxing ( The Relaxing Radio Show)
UK	TUNEIN	s266086	Ambi Nature Radio
UK	GLOBAL_PLAYER	7946cba4-3a8c-424a-a2e5-e555bb8a09a3	Pop (Smooth Thames Valley)
UK	GLOBAL_PLAYER	c374b219-8b87-4c9f-aade-4704727b48bd	Great Hits (from Gold)
UK	GLOBAL_PLAYER	66a602fa-f80a-4c2f-9fab-26bb436c7376	Country (Smooth Country)
UK	GLOBAL_PLAYER	789e024c-6c90-4793-a54b-fd6be69d5274	Classical (Classic FM)
UK	GLOBAL_PLAYER	eee30e01-9a26-4e82-81a2-45012648baa3	Rock (Radio X London)
UK	GLOBAL_PLAYER	5b08094f-59fa-41ba-8e81-78f0ad0b26db	Dance (Heart Dance)
UK	GLOBAL_PLAYER	5af71b40-104e-45ac-8940-c99418a5bafe	Heart (Heart London)
FR	TUNEIN	s16492	Jazz (TSF Jazz)
FR	TUNEIN	s298983	Smooth Jazz (Crooner Radio Lounge)
FR	TUNEIN	s178199	Pop (Pop Gold)
FR	TUNEIN	s196675	Country (Chris country FM)
FR	TUNEIN	s107537	Classical
FR	TUNEIN	s257854	Relaxing
FR	TUNEIN	s266086	Meditation (Ambi Nature Radio)
FR	TUNEIN	s243906	Lullabies
FR	TUNEIN	s54693	Rock (Hotmixradio Rock)
FR	RADIO_FRANCE	64	Fip Rock
FR	RADIO_FRANCE	65	Fip Jazz
FR	RADIO_FRANCE	66	Fip Groove
FR	RADIO_FRANCE	69	Fip Monde
FR	RADIO_FRANCE	70	Fip Nouveautés
FR	RADIO_FRANCE	71	Fip Reggae
FR	RADIO_FRANCE	74	Fip Electro
FR	RADIO_FRANCE	78	Fip Pop
FR	RADIO_FRANCE	401	Classique Easy
FR	RADIO_FRANCE	403	Concerts Radio France
FR	RADIO_FRANCE	604	Mouv' Rap US
FR	RADIO_FRANCE	605	Mouv' Rap Français
FR	CRYSTAL	M1JL001	NRJ
FR	CRYSTAL	M1JL002	Nostalgie
FR	CRYSTAL	M1JL003	Cherie FM
FR	CRYSTAL	M1JL004	Rire et Chansons
FR	CRYSTAL	MC7K001	RFM
FR	CRYSTAL	MC7K002	Virgin Radio
FR	CRYSTAL	M2M4001	Skyrock
FR	CRYSTAL	M55R056	m Radio
FR	CRYSTAL	M164001	Radio Classique
FR	CRYSTAL	M55R118	Voltage
DE	ARD	urn:ard:permanent-livestream:8354f410521b7ea8	Bayern 1
DE	ARD	urn:ard:permanent-livestream:8b939df5fa39be0b	WDR 2
DE	ARD	4811532122718200	SWR3
DE	ARD	5647975057457150	NDR 2
DE	ARD	4910277581602810	1Live
DE	ARD	urn:ard:permanent-livestream:e868c2d1ca1a735d	Bayern 3
DE	ARD	5126119082688510	SWR4 BW
DE	ARD	urn:ard:permanent-livestream:2c2ba1a9a224a773	mdr Sachsen
DE	ARD	4876948635385850	SWR1 BW
DE	ARD	urn:ard:permanent-livestream:4ce6861c20c7af36	mdr Jump
DE	ARD	urn:ard:permanent-livestream:1e32c42a0fb482b5	hr3
DE	ARD	urn:ard:permanent-livestream:943831064f22c43f	hr4
DE	TUNEIN	s172068	Klassik Radio Lounge
DE	TUNEIN	s132073	Radio Regenbogen
DE	TUNEIN	s132073	Schlager Radio
DE	TUNEIN	s25028	Klassik Radio Live
DE	TUNEIN	s158432	Absolut relax
DE	TUNEIN	s299525	bigFM Sunset Lounge
DE	TUNEIN	s80044	Radio TEDDY
DE	TUNEIN	s231559	RADIO BOB! BOBs Alternative Rock
DE	TUNEIN	s97168	ffn 80er
DE	TUNEIN	s304965	ENERGY Deutschrap
DE	TUNEIN	s97055	planet radio black beats
IT	CRYSTAL	M1CPD001	RTL 102.5
IT	CRYSTAL	M93Y001	RDS 100% Grandi Successi
IT	CRYSTAL	M1CPD005	Radiofreccia
IT	RADIO_MEDIASET	station.003	R101
IT	RADIO_MEDIASET	station.004	Radio Monte Carlo
IT	TUNEIN	s295386	Radio Italia
IT	TUNEIN	s138450	Radio Kiss Kiss
IT	TUNEIN	s25206	Radio Zeta
IT	TUNEIN	s292956	Classica by Kondarte
IT	TUNEIN	s95148	Radio Cafe
IT	TUNEIN	s74100	Radio 80
IT	TUNEIN	s1216	Radio Deejay
IT	TUNEIN	s16202	RDS Radio
IT	TUNEIN	s16526	Radio 105
IT	TUNEIN	s63367	RAI Radio 1
IT	TUNEIN	s69185	Virgin Radio Italy
IT	TUNEIN	s63397	RAI Radio 2
IT	TUNEIN	s26090	Radio 24
ES	CRYSTAL	M2V7001	COPE Madrid
ES	CRYSTAL	M2V7003	COPE Mas Madrid
ES	CRYSTAL	M2V7011	COPE Barcelona
ES	CRYSTAL	M2V7072	Cadena 100
ES	CRYSTAL	M2V7073	Rock FM
ES	CRYSTAL	M2A9001	Europa FM
ES	CRYSTAL	M2A9002	Melodia FM
ES	CRYSTAL	MRKYFTLNN8954001	Radio Nacional
ES	CRYSTAL	MRKYFTLNN8954002	Radio Clasica
ES	CRYSTAL	MRKYFTLNN8954003	Radio 3
ES	CRYSTAL	MRKYFTLNN8954004	Radio 4
ES	CRYSTAL	MRKYFTLNN8954005	Radio 5 Todo Noticias
ES	CRYSTAL	MRKYFTLNN8954007	Radio Nacional Madrid
ES	CRYSTAL	M2V7002	COPE Deportes
ES	TUNEIN	s125335	Hit FM
ES	CRYSTAL	M2MT0K9VNORV4O006	Canal Sur Radio

Was this page helpful?

Provide feedback

Last updated: Apr 07, 2023