Communications API

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

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

Call POST /v1/addressBooks/{addressBookId}/contacts to add a contact to an address book.

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

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

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

Response body example

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    },
    "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.	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

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

Request body example

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

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 in E.164 format. Up to three phone numbers can be added.	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 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.	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.	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 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.	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.	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 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	500	"You have reached maximum number of address books that you can create per organization: 500"