Unit Settings API


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

API endpoint

In the request header, set Host to one of 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

JP

https://api.fe.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}

Delete all timers for a unit

DELETE /v1/alerts/timers?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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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 Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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 Senior Living Core

US

US, CA, IT, DE, JP

US, UK, FR, CA, IT, DE, ES, JP

None

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

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

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.

Delete all timers for a unit

Call DELETE /v1/alerts/timers?unitId={unitId} to delete all timers on all endpoints in a unit. To delete timers on just one endpoint, see [Delete all timers for an endopint] (../alexa-smart-properties/endpoint-api.html#delete-all-timers)

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US

US

None

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

DELETE /v1/alerts/timers?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

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

Timers were successfully deleted on all endpoints in the unit. Note that this status code is returned even if the unit has no timers 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 for Hospitality and Senior Living subscriptions. 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

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 Baden-Württemberg

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

s141788

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

JP

TUNEIN

s99441

ABC Classic Sydney

JP

TUNEIN

s135097

Big B Radio - JPOP

JP

TUNEIN

s260885

CIT Radio

JP

TUNEIN

s310605

NHK WORLD-JAPAN

JP

TUNEIN

s27437

WBGO

JP

TUNEIN

s254202

Animega

The following table lists the supported providerId and stationId values for Healthcare subscriptions. 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 (IHR_CLASSIC_ROCK)

US

I_HEART_RADIO

4429

Hip Hop (IHR_HIPHOP)

US

I_HEART_RADIO

4422

Pop (IHR_POP)

US

I_HEART_RADIO

4418

Country (IHR_COUNTRY)

US

I_HEART_RADIO

7193

Latin (IHR_LATIN)

US

I_HEART_RADIO

5953

Dance (IHR_DANCE)

US

I_HEART_RADIO

5162

Gospel (IHR_GOSPEL)

US

I_HEART_RADIO

4242

Jazz (IHR_JAZZ)

US

I_HEART_RADIO

6377

Classical (IHR_CLASSICAL)

US

I_HEART_RADIO

4409

Mix (IHR_MIX)

US

I_HEART_RADIO

4717

Oldies (IHR_OLDIES)

US

I_HEART_RADIO

4447

Alternative (IHR_ALTERNATIVE)

US

I_HEART_RADIO

7312

Wynn's Station (IHR_WYNN_MUSIC)


Was this page helpful?

Last updated: Feb 13, 2024