Communications API

Note: This API is only available to registered Alexa for Hospitality partners. See Get Started with Alexa for Hospitality APIs.

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.

Note: The alexaCommunicationsProfileId listed in the Manage Contact APIs is the same as the profileId listed in this section.

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.

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}"
    }
}

Request body example

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

Request body parameters

Field	Description	Type	Required
`type`	The type of id you are using to create a communication profile. Accepted value: `UNIT`	String	Yes
`id`	The UnitId you are using to create a communications profile, in the format `"amzn1.alexa.unit.did.{UnitId}"`	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

{
    "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 UnitId 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.
401	Unauthorized	The LWA token is expired or invalid.
400	Bad Request	The `profileId` is not valid
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.

Get a communication profile by profileId

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

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}"
    },
    "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 the communication profile. Accepted value: `UNIT`	String
`Id`	The UnitId used to create the communications profile.	String
`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	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.

Get a communication profile by entity id

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

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 UnitId 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}"
    },
    "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 the communication profile. Accepted value: `UNIT`	String
`Id`	The UnitId used to create the communications profile.	String
`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	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.

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.

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.
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. You can create a contact with either a phone number or a communication profile.

Note: Only one contact can be created in each API call.

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

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

Note: All of a unit's address book associations must be deleted before the unit itself can be deleted.

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	500	"You have reached the maximum number of contacts that can be created per address book: 500"
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	100	"You have reached the maximum number of units that can be associated with an address book: 100"
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"