Communications API

Manage communication profiles

To support calling, a unit must create a communications profile – communications Profiles aren't auto-created. When you create communication profile for a unit, it's assigned a unique identifier called a profileId. You can then add the profileId as a contact in the address book of a different unit.

Create a communication profile

Call POST /v1/communications/profile/ to create a communication profile. When you create a communication profile, it enables the communication capability and creates a profileId for a unit. If a profile already exists for the unit, the existing profileID for the unit is returned. Optionally, you can provide a Name for the profile, which will appear as a display name for the unit (e.g. room) that the profile belongs to. If a profile for the unit already exists, the API will return 201 and update the profile display name if different from the one previously applied.

Request format

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

Request path parameters

None.

Request body format

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name"
}

Request body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKYQJ4REIHURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave"
}

Request body parameters

Field Description Type Required
entity The entity for which communication profile is being created. Object Yes
entity.type The type of ID you are using to create a communication profile.
Accepted value: UNIT		 String Yes
entity.id The unit ID you are using to create a communications profile, in the format "amzn1.alexa.unit.did.{UnitId}" String Yes
name Display name for communication profile.
The name string must consist of 1 to 128 Unicode (UTF-8) characters and follow the following rules: 1) Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, or apostrophes. Other special characters are not permitted. 2)Names must contain at least one number or letter.		 String No

Response header

HTTP/1.1 201 Created

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 format

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

Response body parameters

Field Description Type
type The type of id used to create a communication profile.
Possible value: UNIT		 String
Id The unit ID used to create a communications profile. String
profileId A unique profile id that identifies a communication profile. Generated when creating a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. String

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "UnitId is not valid. Please check your Input."
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request UnitId is not valid. Please check your Input.
400 Bad Request The profileId is not valid
400 Bad Request name is not valid
401 Unauthorized The LWA token is expired or invalid.
403 Limit exceeded The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found UnitId doesn't exist.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Create communication profiles in bulk

Call POST /v1/communications/profiles/batch to create communication profiles in bulk. You can create profiles for up to 100 units in a single request (one profile per unit). Each unit receives a unique profileId. You can then add the profileId as a contact in the address book of a different unit.

Request format

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

Request path parameters

None.

Request body format

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId-1}"
            },
            "name": "{optionalProfileDisplayName1}"
        },
        {
            "itemId": {uniqueRequestItemId2},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId-2}"
            },
            "name": "{optionalProfileDisplayName2}"
        }
    ]
}

Request body example

{
    "items": [
        {
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
            },
            "name": "Front desk"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
            },
            "name": "Hotel Restaurant"
        }
    ]
}

Request body parameters

Field Description Type Required
items A list of items for which to execute the operation. List Yes
itemId The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. Integer Yes
type The type of ID you are using to create a communication profile.
Accepted value: UNIT		 String Yes
id The unit ID you are using to create a communications profile, in the format "amzn1.alexa.unit.did.{UnitId}" String Yes
name Profile display name for communication profile. This name appears on the target Alexa device or in the Alexa app when a guest makes an outbound call. It also appears when a contact is created for this unit on an Alexa device in another unit in the same property. String No

Response header

HTTP/1.1 200 OK

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 for individual items

The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.

Response body format

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId}"
            },
            "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId},
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Response body example

{
    "successfulResults": [
        {
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
            },
            "profileId": "amzn1.alexa.communications.profile.did.XDTYU7678IJ3DT4EDFT4WSDFT776REWER"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 500,
            "errorCode": "INTERNAL_ERROR",
            "errorDescription": "Something went wrong."
        }
    ]
}

Response body parameters for individual items

Field Description Type Required
successfulResults This object contains the communication profiles that were successfully created for request items. Object Yes
itemId The unique ID of a request item for which communication profile creation succeeded or failed. Integer Yes
type The type of ID for the communication profile.
Accepted value: UNIT		 String Yes
id The unit ID for the communications profile. String Yes
profileId A unique profile ID that identifies a communication profile. Generated when creating a communication profile for the first time. If a communication profile already exists, the existing profileID for the unit is returned. String Yes
errors This object contains failed communication profile creation information for request items. Object Yes
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages for individual items

Status Code Error Code Error Message
400 INVALID_PARAM "UnitId is not valid. Please check your Input."
400 INVALID_PARAM "Given entityType in request is not supported. Currently we only support UNIT entityType."
400 INVALID_PARAM "Entity is mandatory."
400 INVALID_PARAM "EntityType must be between 1 and 10 characters."
400 INVALID_PARAM "EntityId must be between 1 and 1000 characters."
400 INVALID_PARAM "Name must consist of 1 to 128 characters."
403 FORBIDDEN "Requested action cannot be performed as you don't have access over the specified resource."
500 INTERNAL_ERROR "An internal service error occurred."

Error response body for overall request failure

The following example shows an error response body for an entire request, not for individual items.

Error response body format for HTTP status codes 401, 429, and 503

{
    "message": "{ErrorMessage}"
}

Error response body example for HTTP status codes 401, 429, and 503

{
    "message": "Invalid access token"
}

Response body parameters for overall request failure for error codes 401, 429, and 503

Field Description Type Required
message Error message for HTTP status codes 401, 429, and 503. String Yes

Error response body format for other 4xx and 5xx HTTP status codes

{
    "errors": [
        {
            "itemId": {uniqueRequestItemId}, // This is optional if error is for request level
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, with itemId

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "",
            "errorDescription": "Given entityType in request is not supported. Currently we only support UNIT entityType."
        },
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "",
            "errorDescription": "UnitId is not valid. Please check your Input"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, without itemId

{
    "errors": [
        { 
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Request item list size must be between 1 to 100"
        }
    ]
}

Response body parameters for overall request failure for other 4xx and 5xx HTTP status codes

Field Description Type Required
errors This object contains failed communication profile creation information for request items. Object Yes
itemId The unique identifier of the request item for which profile creation failed. Integer No
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages for overall request failure

Status Code Error Code Error Message
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "ItemId should be unique for each request item. Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

Update a communication profile

Call PUT /v1/communications/profile/{profileId} to update the display name for a communication profile.

Request format

PUT /v1/communications/profile/ HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
profileId The unique profile id that identifies the communication profile being updated. Generated when you created a communication profile. String Yes

Request body format

{
    "name": "<profile display name>"
 }

Request body example

{
    "name": "Dave"
 }

Request body parameters

Field Description Type Required
name Display name for communication profile.
The name string must consist of 1 to 128 Unicode (UTF-8) characters and follow the following rules: 1) Characters must be numbers, letters (Chinese characters and non-Roman letters are permitted), spaces, or apostrophes. Other special characters are not permitted. 2)Names must contain at least one number or letter.		 String No

Response header

HTTP/1.1 204 No Content

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 format

None.

Response body example

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "profileId is not valid. Please check your Input."
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request The profileId is not valid
400 Bad Request name is not valid
400 Bad Request name is required
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found UnitId doesn't exist.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Get a communication profile by profileId

Call GET /v1/communications/profile/{profileId} to get the unit ID associated with a communication profile.

Request format

GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
profileId The unique profile id that identifies the communication profile you are fetching. Generated when you created a communication profile for the first time. String Yes

Request body

None.

Response header

HTTP/1.1 200 OK

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 format

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

Response body parameters

Field Description Type
entity.type The type of id used to create the communication profile.
Accepted value: UNIT		 String
entity.Id The unit ID used to create the communications profile. String
name Display name for the communication profile. String
profileId.profileId The unique profile id of the communication profile. Generated when you created a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. String

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "ProfileId is not valid. Please check your Input"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found UnitId doesn't exist.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Get a communication profile by entity id

Call GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id} to get the unit ID associated with a communication profile.

Request format

GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
entity.type The type of id for the communication profile you are fetching.
Accepted value: UNIT		 String Yes
entity.id The unit ID of the communication profile you are fetching, in the format "amzn1.alexa.unit.did.{UnitId}" String Yes

Request body

None.

Response header

HTTP/1.1 200 OK

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 format

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Dave",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

Response body parameters

Field Description Type
entity.type The type of id used to create the communication profile.
Accepted value: UNIT		 String
entity.id The unit ID used to create the communications profile. String
name Display name for the communication profile. String
profileId.profileId The unique profile id of the communication profile. Generated when you created a communication profile for the first time. If a communication profile already exists, the existing profileID for the Unit is returned. String

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Communication profile does not exist for the given entity"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The provided entity type isn't supported.
Accepted values: UNIT.
400 Bad Request UnitId isn't valid. Please check your Input.
400 Bad Request The profileId is not valid
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found UnitId doesn't exist.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Delete a communication profile

Call DELETE /v1/communications/profile/{profileId} to delete a communication profile. This call completes the following actions:

  • Disables the communication capability.
  • Deletes the profileId assigned to a unit.
  • Delete any contacts in address books where profileID is the contact.

Request format

GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
profileId The unique profile id that identifies the communication profile you are deleting. Generated when you created a communication profile for the first time. String Yes

Request body

None.

Response header

HTTP/1.1 204 No Content

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

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Communication profile does not exist"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request The profileId is not valid
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not Found The communication profile doesn't exist.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Manage address books

Create an address book

Call POST /v1/addressBooks to create an address book.

Request format

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

Request path parameters

None.

Request body format

{
    "name": "{addressbookName}"
}

Request body example

{
    "name": "Example Hotel Seattle"
}

Request body parameters

Field Description Type Required
name The address book name. Must be between 1 and 50 characters long. String Yes

Response header

HTTP/1.1 201 Created

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 format

{
    "addressBookId": "amzn1.alexa.addressbook.did.{id}"
}

Response body example

{
    "addressBookId": "amzn1.alexa.addressbook.did.AFFIZRSWWLHI24RAVPYBTH435G63MEAVPYGFCCP3MR4DEGEE35CEX6I2KVU2PWNJG6FEZARP3B5NRWFJDJPTHAMAV35XSNW24NHRYNXEL4VY3P5ROWZGH7P2RE654AOX4E"
}

Response body parameters

Field Description Type Required
addressBookId The address book ID for the new address book, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Name must be between 1 and 50 characters"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Limit exceeded The request exceeds the limit on the number of address books that an organization can own. Per-user soft limit and config controlled.
403 Forbidden The user doesn't have permission to perform the operation.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

List address books

Call GET /v1/addressBooks to retrieve the list of address books. The optional maxResults and nextToken values provide pagination for the results.

Request format

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

Request query parameters

Field Description Type Required
maxResults Maximum number of results per call. The value of this parameter must be between 1 and 1000. The default value is 100. Integer No
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

Request body

None.

Response header

HTTP/1.1 200 OK
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

Success response body format

{
    "results": [
        {
            "addressBookId": "amzn1.alexa.addressbook.did.{id}",
            "name": "{addressBookName}"
        }, 
    ],
    "paginationContext": {
     "nextToken": "{nextToken}"
    }
}

Success response body example

{
    "results": [
        {
            "addressBookId": "amzn1.alexa.addressbook.did.AEIDIDYHLJGARHFICBJKJFPOQF67CUTIU6QZA7DYPV5JEMPOQY4XVY323UUT7GWCXMAMRODWU55GLVRKWS4UTUJLFGVDCZ2DBVPOFUUCCHKW2J4557K56VLMJPVBNECJBE",
            "name": "Example Hotel Seattle"
        }
 
    ],
    "paginationContext": {
     "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAF-ACXJUajwy_DQYFKIIKNHt9CS5EUCimxqdvXoJOiEoGUJ1oxvFCfj1lAy8bJ47fK85FjBF0j5Z95HyaxgqDPXsxHkHx7kuZ0ybI7r7N716qI0IxFM_XOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

Response body parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
name The address book name. String Yes

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Received invalid pagination token. Please check the pagination value passed"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Get an address book

Call GET /v1/addressBooks/{addressBookId} to retrieve the metadata for an address book.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body

None.

Response header

HTTP/1.1 200 OK

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

Success response body format

{
    "addressBookId": "amzn1.alexa.addressbook.did.{id}",
    "name": "{addressbookName}"
}

Success response body example

{
    "addressBookId": "amzn1.alexa.addressbook.did.AEWEYSYTUWWISWGD32TNVUP67Z2KEI3XGOTDTEYHWKFL2QB55D7IV2O3CAYIGO4PEEL3UUFOBPMHK6FWWZMBJUT4EY4WLJHY63HA7GATUOC3K7CH4EK3QHXEXOKGDGEJBQ",
    "name": "Example Hotel Seattle"
}

Response body parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
name The address book name. String Yes

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "AddressBookId does not exist"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Update an address book

Call PUT /v1/addressBooks/{addressBookId} to update the address book name.

Request format

PUT /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body format

{
    "name": "{addressbookName}"
}

Request body example

{
    "name": "Example Hotel Seattle"
}

Request body parameters

Field Description Type Required
name The new address book name. Must be between 1 and 50 characters long. String Yes

Response header

HTTP/1.1 200 OK

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

Success response body

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Address book name is mandatory"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Delete an address book

Call DELETE /v1/addressBooks/{addressBookId} to delete an address book.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body

None.

Response header

HTTP/1.1 204 No Content

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

Success response body

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Address book ID must be between 10 and 1000 characters"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID wasn't found.
409 Conflict The address book can't be deleted, because it's associated with a unit. The user must delete the association first, and then delete the address book.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Manage contacts

Create a contact

Call POST /v1/addressBooks/{addressBookId}/contacts to add a contact to an address book. A contact is an address book entry that represents a callable Alexa device or PSTN number. You can create a contact with either a phone number or a communication profile.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body format with a phone number

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    }
}

Request body example with single phone number

{
    "contact": {
        "name": "Example Hotel Reception",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    }
}

Request body example with multiple phone numbers

{
    "contact": {
        "name": "Example Hotel Laundry Service",
        "phoneNumbers": [
            {
                "number": "+12055551233"
            },
            {
                "number": "+12055551244"
            }
        ]
    }
}

Request body format with a communication profile

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    }
}

Request body example with a communication profile

{
    "contact": {
        "name": "Example Hotel Laundry Service",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

Request body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: Phone number isn't supported in France (fr-FR). String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes

Response header

HTTP/1.1 201 Created

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 format

{
    "contactId": "amzn1.alexa.contact.did.{id}"
}

Response body example

{
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
400 Bad Request A contact must have at least one number object or a alexaCommunicationProfileId
400 Bad Request A contact can't have both a number and a alexaCommunicationProfileId
400 Bad Request The alexaCommunicationProfileId must be between 40 and 200 characters
400 Bad Request The profileId is not valid
401 Unauthorized The LWA token is expired or invalid.
403 Limit exceeded The request exceeds the limit on the number of contacts per unit. Per-user soft limit and config controlled.
403 Forbidden The user doesn't have permission to perform the operation.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Create contacts in bulk

Call POST /v1/addressBooks/{addressBookId}/contacts/batch to create address book contacts in bulk. You can create up to 100 contacts in a single request. A contact is an address book entry that represents a callable Alexa device or PSTN number. You can create a contact with either a phone number or a communication profile.

Request format

POST /v1/addressBooks/{addressBookId}/contacts/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request path parameters

None.

Request body format with a phone number and with a communication profile

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
            "contact": {
                "name": "{contactName}",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": {uniqueRequestItemId2},
            "contact": {
              "name": "{contactName}",
              "alexaCommunicationProfileId": "{communicationProfile}"
            }
        }
    ]
}

Request body example with a Phone number and with a communication profile

{
    "items": [
        {
            "itemId": 1,
            "contact": {
                "name": "Diego Ramirez",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
              "name": "Nurse station",
              "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.XER5678IJHYTREW45678I9OLKI876REDS"
            }
        }
    ]
}

Request body parameters

Field Description Type Required
items A list of items for which to execute the operation. List Yes
itemId The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. Integer Yes
number The contact phone number. Must be in E.164 format. Up to three phone numbers can be added. Note: You can't add both a phone number and a alexaCommunicationProfileId to the same contact. String Yes
alexaCommunicationProfileId The id of your communication profile. Note: You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes
name The contact name. Must be between 1 and 50 characters long. String Yes

Response header

HTTP/1.1 200 OK

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 for individual items

The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.

Response body format

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId1},
            "contactId": "amzn1.alexa.contact.did.{contactId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId2},
            "status": {StatusCode},
            "errorCode": {ErrorCode},
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Response body example

{
    "successfulResults": [
        {
            "itemId": 1, 
            "contactId": "amzn1.alexa.contact.did.XDFTYHUJKKMIUT56E45DER5678IJJRF"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 500,
            "errorCode": "INTERNAL_ERROR",
            "errorDescription": "Something went wrong."
        }
    ]
}

Response body parameters for individual items

Field Description Type Required
successfulResults This object contains the contacts that were successfully created for request items. Object Yes
itemId The unique ID of a request item for which contact creation succeeded. Integer Yes
contactId A unique contact ID that identifies a contact. Generated when creating a contact for the first time. String Yes
errors This object contains failed contact creation information for request items. Object Yes
itemId The unique identifier of the request item for which contact creation failed. Integer Yes
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages for individual items

Status Code Error Code Error Message
400 INVALID_PARAM "Contact must have atleast one PhoneNumber or a CommunicationProfileId"
400 INVALID_PARAM "A Contact cannot contain both PhoneNumber and a CommunicationProfileId. You must add either one."
400 INVALID_PARAM "AlexaCommunicationProfileId 'amzn1.AESAS5HB7E4RMTCQHMOHA2' is not in standard format"
400 INVALID_PARAM "Given phone number is not per E.164 format"
400 INVALID_PARAM "Contact is mandatory"
400 INVALID_PARAM "Contact Name must be between 1 and 50 characters"
400 INVALID_PARAM "Number of phonenumbers has to be between 1 and 3"
400 INVALID_PARAM "Contact Name must be between 1 and 50 characters"
403 FORBIDDEN "Requested action cannot be performed as you don't have access over the specified resource"
500 INTERNAL_ERROR "An internal service error occurred."

Error response body for overall request failure

The following example shows an error response body for an entire request, not for individual items.

Error response body format for HTTP status codes 401, 429, and 503

{
    "message": "{ErrorMessage}"
}

Error response body example for HTTP status codes 401, 429, and 503

{
    "message": "Invalid access token"
}

Response body parameters for overall request failure

Field Description Type Required
message Error message for HTTP status codes 401, 429 and 503. String Yes

Error response body format for other 4xx and 5xx HTTP status codes

{
    "errors": [
        {
            "itemId": {uniqueRequestItemId}, // This is optional if error is for request level
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, with itemId

{
    "errors": [
        {
            "itemId": 1,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "AlexaCommunicationProfileId 'xyz' is not in standard format"
        },
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Given phone number is not per E.164 format"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, without itemId

{
    "errors": [
        {
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "ItemId is mandatory for all request items"
        }
    ]
}

Response body parameters for other 4xx and 5xx HTTP status codes

Field Description Type Required
errors This object contains failed contact creation information for request items. Object Yes
itemId The unique ID of a request item for which contact creation succeeded or failed. Integer No
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages

Status Code Error Code Error Message
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "ItemId should be unique for each request item. Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

List contacts

Call GET /v1/addressBooks/{addressBookId}/contacts to retrieve the contacts for a given address book. The optional maxResults and nextToken values provide pagination for the results.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request query parameters

Field Description Type Required
maxResults Maximum number of results per call. The value of this parameter must be between 1 and 1000. The default value is 100. Integer No
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

Request body

None.

Response header

HTTP/1.1 200 OK
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 format

{
    "results": [
        {
            "contactName": "{contactName}",
            "contactId": "amzn1.alexa.contacts.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

Response body example

{
    "results": [
        {
            "contactName": "Marriott Reception",
            "contactId": "amzn1.alexa.contact.did.AGNA6I63RJBIV7EFEL73AJEIUZ7XGKDCB7VYRO6JTLMHX72F2P4YX4ZVZNCWB3SZR5ZS5ETPJTCCHCTV2NV2XU66GCKSNGF54PZCBCUE"
        },
        {
            "contactName": "Blueacre Restaurant",
            "contactId": "amzn1.alexa.contact.did.AEWC6RQGHIKFWT6UMMWWLHCS5Y6HBJACWEF35Y2FB7FO2QACH6MV7VEFE3CKLJZDFENFKAEQKFW6C4SCWO6ERFZ4KGGCXTKC2HXUYQMC"
        }
    ],
    "paginationContext": {
        "nextToken": "AAEAAcpUKRGBVjzoVWM6lljL35vnWNJEqQmscd4Zm6oRLWl8AAAAAF-D0_sNXPigGsCK9AvcWkfVahZ0RTA0tTLrTBFRL81qFM2lGK0ZZ8erl47sqVEMPBRxIvSjNaQrmBIS8UjNvHDck-fQJHFkm-r27-0lylTI_oMPC1h4MIo6bAEeGZqWbq0JxmMUdRvTpRgoImeEW5GUccVq-2Zf21YFOaHIkvXmBkaFdBDP2T1i5WD5OxiAwd1PEBTRZ"
    }
}

Response body parameters

Field Description Type Required
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes
contactName The contact name. Must be between 1 and 50 characters long. String Yes
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Get a contact

Call GET /v1/addressBooks/{addressBookId}/contacts/{contactId} to retrieve the metadata for a contact.

Request format

GET /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes

Request body

None.

Response header

HTTP/1.1 200 OK

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 format with phone number

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    },
    "contactId": "amzn1.alexa.contacts.did.{contactIdid}"
}

Response body example with phone number

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

Response body format with communication profile

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    },
    "contactId": "amzn1.alexa.contact.did.{contactId}"
}

Response body example with communication profile

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

Response body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be in E.164 format. Up to three phone numbers can be added. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: The phoneNumbers object isn't returned in requests for France (fr-FR) accounts. String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or contact ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Update a contact

Call PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} to update the metadata for a contact.

Request format

PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes

Request body format with phone number

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    }
}

Request body example with phone number

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "phoneNumbers": [
            {
                "number": "+16055554412"
            }
        ]
    }
}

Request body format with communication profile

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    }
}

Request body example with communication profile

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

Request body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. Note: Phone number isn't supported in France (fr-FR). String Yes
alexaCommunicationProfileId The id of your communication profile. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. This value is the same as the profileId listed in the Manage communication profiles section. String Yes

Response header

HTTP/1.1 200 OK

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.

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or contact ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Delete a contact

Call DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId} to delete a contact from an address book.

Request format

DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
contactId The contact ID, in the format "amzn1.alexa.contacts.did.{id}". String Yes

Request body

None.

Response header

HTTP/1.1 204 No Content

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

Success response body

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "Contact ID is not valid. Please check your input"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or contact ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Manage address book associations

Create an address book association

Call POST /v1/addressBooks/{addressBookId}/unitAssociations to associate an address book with a unit.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body format

{
    "unitId": "amzn1.alexa.unit.did.{id}"
}

Request body example

{
    "unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU"
}

Request body parameters

Field Description Type Required
unitId The unit ID to associate with the address book, in the format "amzn1.alexa.unit.did.{id}". String Yes

Response header

HTTP/1.1 201 Created

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 format

{
    "unitId": "amzn1.alexa.unit.did.{id}",
    "addressBookId": "amzn1.alexa.addressbook.did.{id}"
}

Response body example

{
    "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
    "addressBookId": "amzn1.alexa.addressbook.did.AFWNDND4TUBMMIU4P7HHXI2TY27FGYRODJVSYQUENRKSI4FTWTSJB3UUGI5WSH2LMQOYPSDDIJUG6NN336JKARWGXM2POYAB3LVOLVZ5XBO2WZX32SU5D54NF3RSEDGIPU"
}

Response body parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
addressBookId The address book ID for the new address book, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "You have reached maximum allowed limit of AddressBooks that can be associated per Unit: 3"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Limit exceeded The request exceeds the limit on the number of units that an address books can be associated with, or the number address books that can be associated with a unit.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or unit ID wasn't found.
409 Conflict The address is already associated with the unit.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Create address book associations in bulk

Call POST /v1/addressBooks/{addressBookId}/unitAssociations/batch to associate an address book with up to 100 units.

Request format

POST /v1/addressBooks/{addressBookId}/unitAssociations/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request body format

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
             "unitId": "amzn1.alexa.unit.did.{unitId-1}"
        },
        {
            "itemId": {uniqueRequestItemId2},
             "unitId": "amzn1.alexa.unit.did.{unitId-2}"
        }
    ]
}

Request body example

{
    "items": [
        {
            "itemId": 1, 
             "unitId": "amzn1.alexa.unit.did. XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ "

        },
        {
            "itemId": 2, 
             "unitId": "amzn1.alexa.unit.did.DRR56T7UIOLKI76TREDFTY998TYGDFGT4DFR " 
        }
    ]
}

Request body parameters

Field Description Type Required
items A list of items for which to execute the operation. List Yes
itemId The unique ID of a request item. Typically item IDs are a sequence of numbers from starting from 1. Integer Yes
unitId The unit ID you are using to create an address book association, in the format "amzn1.alexa.unit.did.{UnitId}". String Yes

Response header

HTTP/1.1 200 OK

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 for individual items

The following example shows a response body with both success and error message at the individual item level. Both successfulResults and errors can co-exist in the same response.

Response body format

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId1}, 
             "unitId": "amzn1.alexa.unit.did.{unitId-1}",
             "addressBookId": "amzn1.alexa.addressbook.did.{addressBookId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId2}
            "status": {StatusCode},
            "errorCode": {ErrorCode},
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Response body example

{
    "successfulResults": [
        {
            "itemId": 1, 
             "unitId": "amzn1.alexa.unit.did.XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ",
             "addressBookId": "amzn1.alexa.addressbook.did.DRFDCFRT6789876TR56789OLIUYTFY7654EDDF"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 409,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "AddressBook is already associated with the Unit"
        }
    ]
}

Response body parameters for individual items

Field Description Type Required
successfulResults This object contains the address book associations that were successfully created for request items. Object Yes
itemId The unique ID of a request item for which address book association creation succeeded or failed. Integer Yes
unitId The unit ID for the address book association. String Yes
addressBookId A unique ID that identifies an address book association. Generated when creating an address book association for the first time. String Yes
errors This object contains failed address book association creation information for request items. Object Yes
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages for individual items

Status Code Error Code Error Message
400 INVALID_PARAM "UnitId is not valid. Please check your Input."
400 INVALID_PARAM "UnitId is mandatory."
403 FORBIDDEN "Requested action cannot be performed as you don't have access over the specified resource."
404 INVALID_PARAM "UnitId doesn't exist."
409 INVALID_PARAM "AddressBook is already associated with the Unit"
500 INTERNAL_ERROR "An internal service error occurred."

Error response body for overall request failure

The following example shows an error response body for an entire request, not for individual items.

Error response body format for HTTP status codes 401, 429, and 503

{
    "message": "{ErrorMessage}"
}

Error response body example for HTTP status codes 401, 429, and 503

{
    "message": "Invalid access token"
}

Response body parameters for overall request failure for error codes 401, 429, and 503

Field Description Type Required
message Error message for HTTP status codes 401, 429, and 503. String Yes

Error response body format for other 4xx and 5xx HTTP status codes

{
    "errors": [
        { 
            "itemId": {uniqueRequestItemId}, // This is optional if error is for request level
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, with itemId

{
    "errors": [
        {
            "itemId": 2,
            "status": 403,
            "errorCode": "FORBIDDEN",
            "errorDescription": "Requested action cannot be performed as you don't have access over the specified resource"
        }
    ]
}

Error response body example for other 4xx and 5xx HTTP status codes, without itemId

{
    "errors": [
        {
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "ItemId is mandatory for all request items"
        }
    ]
}

Response body parameters for overall request failure for other 4xx and 5xx HTTP status codes

Field Description Type Required
errors This object contains failed address book association creation information for request items. Object Yes
itemId The unique ID of a request item for which address book association creation succeeded or failed. Integer No
status HTTP response code for a failed request item. Integer Yes
errorCode The error code for the error. Enum Yes
errorDescription The error message for the error. String Yes

HTTP status codes and error messages for overall request failure

Status Code Error Code Error Message
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "AddressBookId is not valid. Please check your Input"
400 INVALID_PARAM "ItemId should be unique for each request item. Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
403 FORBIDDEN "The user doesn't have permission to perform the operation."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

List address book associations for a unit

Call GET /v1/addressBooks/unitAssociations to retrieve the list of address books that are associated with a unit. The optional maxResults and nextToken values provide pagination for the results.

Request format

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

Request query parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
maxResults Maximum number of results per call. The maximum value is 100. The default value is 10. Integer No
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

Request body

None.

Response header

HTTP/1.1 200 OK

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 format

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.{id}",
            "addressBookId": "amzn1.alexa.addressbook.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

Response body example

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
            "addressBookId": "amzn1.alexa.addressbook.did.AF2B2LU7KDOZAMUJRTVCT66DWPFP3BOQ4RZ5GPHAVCIJTMQBJHEDHLANZOJFZSKLG6X2SVE3YCCUZVCP5R7RNZBKI6KHYHGFFLVFIVVJKNU24O45BRMHPBGQ35IPRBZTSI"
        },
        {
            "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
            "addressBookId": "amzn1.alexa.addressbook.did.AFOEHWC2DFKIOVNRS7NXM7MCVHNTDODUUXZ5XCXFTBNNEL6QDLC6OTHOES6PRRKP6MRSKE4EZ6APO4TTVZF56QNQYUKYSHTATCGG4AKO2NGZPJ2ZXRZP5M2MUPJWU7FORE"
        }
    ],
    "paginationContext": {
             "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

Response body parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified unit ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Get an address book association

Call GET /v1/addressBooks/{addressBookId}/unitAssociations to retrieve an address book association. The optional maxResults and nextToken values provide pagination for the results.

Request format

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

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request query parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". When unitId is present, this call returns the association between addressBookId and unitId. If not, it returns a list of all units associated with the given addressBookId. String No
maxResults Maximum number of results per call. The maximum value is 100. The default value is 10. Integer No
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

Request body

None.

Response header

HTTP/1.1 200 OK

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 format

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.{id}",
            "addressBookId": "amzn1.alexa.addressbook.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

Response body example

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU",
            "addressBookId": "amzn1.alexa.addressbook.did.AHZO6C2F4A4AUHY4EPFA3R5KHVBQ763U3ZWPPLXEUAWCVCKYVSTMXH2GR6TN7CFM4KQXMMNWJVAQBP2Y2YBUKOBUPOPNDFDW434MJQ4ZKV6YQNIC575PUW6RVVVUKMEWYA"
        }
    ],
    "paginationContext": {
             "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

Response body parameters

Field Description Type Required
unitId The unit ID, in the format "amzn1.alexa.unit.did.{id}". String Yes
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes
nextToken Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. For details, see Handling Pagination in Query Results. String No

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or unit ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Delete an address book association

Call DELETE /v1/addressBooks/{addressBookId}/unitAssociations to remove the association between an address book and a unit.

Request format

DELETE /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required
addressBookId The address book ID, in the format "amzn1.alexa.addressbook.did.{id}". String Yes

Request query parameters

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

Request body

None.

Response header

HTTP/1.1 204 No Content

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

Success response body

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

{
    "message": "AddressBook and Unit are not associated"
}

HTTP response codes

Status Code Description Reason
400 Bad Request The request is missing one or more required parameters, or the parameter values aren't valid.
401 Unauthorized The LWA token is expired or invalid.
403 Forbidden The user doesn't have permission to perform the operation.
404 Not found The specified address book ID or unit ID wasn't found.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Resource limits

Resource Default Error message on exceeding the limit
Maximum number of contacts allowed in an address book 2000 "You have reached the maximum number of contacts that can be created per address book: 2000"
Maximum number of address books that can be associated with a unit 10 "You have reached the maximum number of address books that can be associated with a unit: 10"
Maximum number of units that an address book can be associated with 2500 "You have reached the maximum number of units that can be associated with an address book: 2500"
Max number of phone numbers per contact 3 "The number of phone numbers must be between 1 and 3"
Max number of address books per organization 2500 "You have reached maximum number of address books that you can create per organization: 2500"