Communications API

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

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