Communications API

Manage communication profiles

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

Create a communication profile

Call POST /v1/communications/profile/ to create a communication profile. When you create a communication profile, it enables the communication capability and creates a profileId for a unit. If a profile already exists for the unit, the existing profileID for the unit is returned.

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.
409 Conflict The address book can't be deleted, because it's associated with a unit. The user must delete the association first, and then delete the address book.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

Manage contacts

Create a contact

Call POST /v1/addressBooks/{addressBookId}/contacts to add a contact to an address book. You can create a contact with either a phone number or a communication profile.

Request format

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

Request path parameters

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

Request body format with a phone number

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

Request body example with single phone number

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

Request body example with multiple phone numbers

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

Request body format with a communication profile

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

Request body example with a communication profile

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

Request body parameters

Field Description Type Required
name The contact name. Must be between 1 and 50 characters long. String Yes
number The contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. Up to three phone numbers can be specified for a contact. You can't add both a phone number and a alexaCommunicationProfileId to the same contact. 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.
409 Conflict The address is already associated with the unit.
429 Too many requests Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout. Per-user soft limit and config controlled.
500 Internal Server Error An internal service error occurred.
503 Service Unavailable The service is currently unavailable to handle the request.

List address book associations for a unit

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

Request format

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

Request query parameters

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

Request body

None.

Response header

HTTP/1.1 200 OK

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Response body format

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

Response body example

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

Response body parameters

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

HTTP response codes

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

Get an address book association

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

Request format

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

Request path parameters

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

Request query parameters

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

Request body

None.

Response header

HTTP/1.1 200 OK

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Response body format

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

Response body example

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

Response body parameters

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

HTTP response codes

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

Delete an address book association

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

Request format

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

Request path parameters

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

Request query parameters

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

Request body

None.

Response header

HTTP/1.1 204 No Content

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type Required
X-Amzn-RequestId Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. String Yes

Success response body

None.

Error response body format

{
    "message": "{errorMessage}"
}

Error response body example

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

HTTP response codes

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

Resource limits

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