Address Book REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. For details, see Get Started with Alexa Smart Properties APIs.

Use the Address Book REST API to manage address books, associate address books to rooms, and add contacts to an address book in Alexa Smart Properties (ASP).

Before you add a contact to an address book of a room, you must create the communications profile to enable the calling capability. Alexa uses the communication profile ID instead of a unit ID to identify the Alexa-enabled devices in the room. For more details, see Communications REST API Reference.

If you want to create and manage address books and contacts in the ASP management console instead, see Manage Communications Features in the Management Console.

Resource limits

The Address Book API defines the following resource limits. If you exceed the limit, the request fails with a message in the response body that indicates the limit reached.

Resource	Limit	Error message
Contacts per address book.	2000	You have reached the maximum number of contacts that can be created per address book: 2000.
Address books associated with a unit.	10	You have reached the maximum number of address books that can be associated with a unit: 10.
Phone numbers associated with a unit.	10	You have reached the maximum number of phone numbers that can be associated with a unit: 10.
Units associated with an address book.	2500	You have reached the maximum number of units that can be associated with an address book: 2500.
Phone numbers per contact.	3	The number of phone numbers must be between 1 and 3.
Address books per organization.	35000	You have reached maximum number of address books that you can create per organization: 35000.

API endpoint

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

Country	Endpoint
CA, US	`https://api.amazonalexa.com`
DE, ES, FR, IT, UK	`https://api.eu.amazonalexa.com`
JP	`https://api.fe.amazonalexa.com`

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Operations

The Address Book API supports the following types of operations:

Manage address books – Create address books and associate them with rooms on your property.
Manage contacts – Create contacts and add them to an address book. You can create a contact with a phone number, communication profile, or WebRTC service provider.

Manage address books

Operation	HTTP Method and URI
Create address book	`POST /v1/addressBooks`
Delete address book	`DELETE /v1/addressBooks/{addressBookId}`
Get address book	`GET /v1/addressBooks/{addressBookId}`
List address books	`GET /v1/addressBooks?maxResults={maxResults}&nextToken={nextToken}`
Update address book	`PUT /v1/addressBooks/{addressBookId}`
Create address book association	`POST /v1/addressBooks/{addressBookId}/unitAssociations`
Create address book associations in bulk	`POST /v1/addressBooks/{addressBookId}/unitAssociations/batch`
Delete address book association	`DELETE /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}`
List address book associations for unit	`GET /v1/addressBooks/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken}`
List unit associations for an address book	`GET /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken}`

Manage contacts

Operation	HTTP Method and URI
Create contact	`POST /v1/addressBooks/{addressBookId}/contacts`
Create contacts in bulk	`POST /v1/addressBooks/{addressBookId}/contacts/batch`
Delete contact	`DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId}`
Get contact	`GET /v1/addressBooks/{addressBookId}/contacts/{contactId}`
List contacts	`GET /v1/addressBooks/{addressBookId}/contacts?maxResults={maxResults}&nextToken={nextToken}`
Update contact	`PUT /v1/addressBooks/{addressBookId}/contacts/{contactId}`

Create address book

Create an address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create an address book, you make a POST request to the /v1/addressBooks resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "Address Book for Property Name"
}

Request body properties

Property	Description	Type	Required
`name`	Address book name. Valid value: 1–50 alphanumeric characters.	String	Yes

Response

A successful response returns HTTP 201 Created, along with the address book ID. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

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

Response body properties

Property	Description	Type
`addressBookId`	Identifies the new address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains an address book ID.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete address book

Delete the specified address book.

Note: You can't delete an address book that's associated with a unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To delete an address book, you make a DELETE request to the /v1/addressBooks/{addressBookId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Address book deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get address book

Get the details of the specified address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get the details of the address book, you make a GET request to the v1/addressBooks/{addressBookId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details of the address book. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "addressBookId": "amzn1.alexa.addressbook.did.1000",
    "name": "Example Property Name"
}

Response body properties

Property	Description	Type
`addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String
`name`	Address book name. Valid value: 1–50 alphanumeric characters.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains details about the specified address book.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List address books

Get the list of address books owned by the caller.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To list address books, you make a GET request to the /v1/addressBooks resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–1000. Default: 100.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of address books. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
            "addressBookId": "amzn1.alexa.addressbook.did.1000",
            "name": "Property Address Book"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.1"
    }
}

Response body properties

Property	Description	Type
`results`	List of address books.	Array of objects
`results[].addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String
`results[].name`	Address book name. Valid value: 1–50 alphanumeric characters.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of address books owned by the caller.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update address book

Update the name of the specified address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To update the book name you make a PUT request to the /v1/addressBooks/{addressBookId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "name": "Example Property Name"
}

Request body properties

Property	Description	Type	Required
`name`	Address book name. Valid value: 1–50 alphanumeric characters.	String	Yes

Response

A successful response returns HTTP 200 OK, along with XYZ. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Address book properties updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create address book association

Associate an address book with the specified unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create an association, you make a POST request to the /v1/addressBooks/{addressBookId}/unitAssociations resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

Request body properties

Property	Description	Type	Required
`unitId`	Identifies the unit to associate with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	Yes

Response

A successful response returns HTTP 201 Created, along with the association. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

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

Response body properties

Property	Description	Type
`unitId`	Identifies the unit to associate with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String

HTTP status codes

Status	Description
`204 No Content`	Response body contains the unit - address book association.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create address book associations in bulk

Associate the specified address book with up to 100 units.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create associations, you make a POST request to the /v1/addressBooks/{addressBookId}/unitAssociations/batch resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

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

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

Request body properties

Property	Description	Type	Required
`items`	List of units to associate with the address book.	Array of objects	Yes
`items[].itemId`	Unique identifier for the contact, usually a sequence of numbers starting from 1.	Integer	Yes
`items[].unitId`	Identifies the unit to associate with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String

Response

A successful response returns HTTP 200 OK, along with the list of associations. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body examples

The following example shows a successful response with contact IDs assigned to each item.

The following example shows a response body with both success and error message at the individual item level. Both results and errors properties can coexist in the same response.

The following example shows a response body with all items failed.

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

Response body properties

Property	Description	Type
`results`	List of success results.	Array of objects
`results[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item. Not included if the error is at the request level.	Integer
`results[].unitId`	Identifies the unit associated with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`results[].addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String
`errors`	(Optional) List of error results. For details about possible the error property values, see Error property values for individual items.	Array of objects
`errors[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item.	Integer
`errors[].status`	HTTP response code for the failed request item.	Integer
`errors[].errorCode`	Type of error that occurred.	String
`errors[].errorDescription`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error description.	String

Error property values for individual items

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

HTTP status codes

Status	Description
`200 OK`	Associations created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: `ItemId` is mandatory for all request items `AddressBookId` is not valid. Please check your Input. `ItemId` should be unique for each request item. Multiple requests with itemId [X] present. Request item list size must be between 1 to 100.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete address book association

Remove the association between an address book and a unit.

Note: You must delete all address book associations before you can delete the unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To remove an association, you make a DELETE request to the /v1/addressBooks/{addressBookId}/unitAssociations resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`unitId`	Query	Identifies the unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Association deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List address book associations for a unit

Get a list of address books associated with the specified unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get associations, you make a GET request to the /v1/addressBooks/unitAssociations resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`unitId`	Query	Identifies the unit. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–200. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of address book associations. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1235"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.2"
    }
}

Response body properties

Property	Description	Type
`results`	List of associations.	Array of objects
`results[].unitId`	Identifies the unit associated with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`results[].addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the unit - address book associations.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List unit associations for an address book

Get the list of unit associations for the specified address book. You can optionally specify the unit ID to get the association for a specific unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get associations, you make a GET request to the /v1/addressBooks/{addressBookId}/unitAssociations resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`unitId`	Query	Identifies the unit. When `unitId` is present, the response contains the association between `addressBookId` and `unitId`. If not present, the response contains a list of all units associated with the given `addressBookId`. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–400. Default: 50.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of unit associations for the specified address book. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.102",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.103",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.2"
    }
}

Response body properties

Property	Description	Type
`results`	List of associations.	Array of objects
`results[].unitId`	Identifies the unit associated with the address book. Formatted as Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`results[].addressBookId`	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the unit - address book associations.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create contact

Add a contact to the specified address book. A contact can be an address book entry that represents a callable Alexa-enabled device, PSTN number, or WebRTC endpoint. You can create a contact with a phone number, communication profile, or service provider contact ID for WebRTC calling.

Important: For each contact, you can only use one contact type. For example, if you created a contact with a phone number, you can't associate the same contact with a provider contact ID.

Note: You must omit the phoneNumbers object in requests for France (fr-FR).

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create a contact, you make a POST request to the /v1/addressBooks/{addressBookId}/contacts resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body examples

The following examples show requests to create a contact in the specified address book. You can define a contact as a phone number, communication profile, or WebRTC service provider.

Request body properties

Property	Description	Type	Required
`contact`	Contact to create. Include one type of contact: `number`, `alexaCommunicationProfileId`, or `providerContact`.	Object	Yes
`contact.name`	Contact name. Valid value: 1–50 alphanumeric characters.	String	Yes
`contact.number`	Contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. You can specify up to three phone numbers for a contact. Note: You can't include a phone number in `fr-FR`.	String	No
`contact.alexaCommunicationProfileId`	Identifies the communication profile for a unit. This value is the same as the `profileId` listed in the Communications REST API Reference. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	No
`contact.providerContact`	Include for WebRTC calling only.	Object	No
`contact.providerContact.id`	Internal ID of the service provider. Formatted as an Amazon Common Identifier (ACI), `amzn1.comms.csp.id.{id}`.	String	No

Response

A successful response returns HTTP 201 Created, along with the contact ID. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

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

Response body properties

Property	Description	Type
`contactId`	ID that represents the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String

HTTP status codes

Status	Description
`204 No Content`	Reciprocal association created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: A contact must have at least one `number`, `alexaCommunicationProfileId`, or `providerContact.id` property. A contact can't have both a `number` and a `alexaCommunicationProfileId`. The `alexaCommunicationProfileId` must be between 40 and 200 characters .
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create contacts in bulk

Create address book contacts in bulk. You can create up to 100 contacts in a single request. A contact is an address book entry that represents a callable Alexa-enabled device or PSTN number. You can create a contact with a phone number or a communication profile.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create multiple contacts, you make a POST request to the /v1/addressBooks/{addressBookId}/contacts/batch resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "items": [{
            "itemId": 1,
            "contact": {
                "name": "Mary - Room 202",
                "phoneNumbers": [{
                        "number": "+15555551212"
                    },
                    {
                        "number": "+15555551213"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
                "name": "Bob - Room 203",
                "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.1234"
            }
        }
    ]
}

Request body properties

Property	Description	Type	Required
`items`	List of contacts to add to the address book.	Array of objects	Yes
`items[].itemId`	Unique identifier for the contact, usually a sequence of numbers starting from 1.	Integer	Yes
`items[].contact`	Contact to create. Include one type of contact per item: `number`, `alexaCommunicationProfileId`, or `providerContact`.	Object	Yes
`items[].contact.name`	Contact name. Valid value: 1–50 alphanumeric characters.	String	Yes
`items[].contact.number`	Contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. You can specify up to three phone numbers for a contact. Note: You can't include a phone number in `fr-FR`.	String	No
`items[].contact.alexaCommunicationProfileId`	Identifies the communication profile for a unit. This value is the same as the `profileId` listed in the Communications REST API Reference. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	No
`items[].contact.providerContact`	Include for WebRTC calling only.	Object	No
`items[].contact.providerContact.id`	Internal ID of the service provider. Formatted as an Amazon Common Identifier (ACI), `amzn1.comms.csp.id.{id}`.	String	No

Response

A successful response returns HTTP 201 Created, along with the list of contact IDs. For overall request failure, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error. If errors occur for individual items, the response body includes the success and error items.

Response body examples

The following example shows a successful response with contact IDs assigned to each item.

The following example shows a response body with both success and error message at the individual item level. Both results and errors properties can coexist in the same response.

The following example shows a response body with all items failed.

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

Response body properties

Property	Description	Type
`results`	List of success results.	Array of objects
`results[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item. Not included if the error is at the request level.	Integer
`results[].contactId`	Unique identifier for the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String
`errors`	(Optional) List of error results. For details about possible the error property values, see Error property values for individual items.	Array of objects
`errors[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item.	Integer
`errors[].status`	HTTP response code for the failed request item.	Integer
`errors[].errorCode`	Type of error that occurred.	String
`errors[].errorDescription`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error description.	String

Error property values for individual items

`status`	`errorCode`	`errorDescription`
`400`	`INVALID_PARAM`	Contact must have at least one PhoneNumber or a CommunicationProfileId.
`400`	`INVALID_PARAM`	A Contact can't contain both PhoneNumber and a CommunicationProfileId. You must add either one.
`400`	`INVALID_PARAM`	AlexaCommunicationProfileId isn't in standard format.
`400`	`INVALID_PARAM`	Given phone number is not per E.164 format.
`400`	`INVALID_PARAM`	Contact is mandatory.
`400`	`INVALID_PARAM`	Contact Name must be between 1 and 50 characters.
`400`	`INVALID_PARAM`	Number of phone numbers must be between 1 and 3.
`400`	`INVALID_PARAM`	ItemId is mandatory for all request items.
`400`	`INVALID_PARAM`	ItemId should be unique for each request item. Multiple requests with itemId [X] present.
`400`	`INVALID_PARAM`	Request item list size must be between 1 to 100.
`403`	`FORBIDDEN`	Requested action cannot be performed as you don't have access over the specified resource.
`500`	`INTERNAL_ERROR`	An internal service error occurred.

HTTP status codes

Status	Description
`204 No Content`	Reciprocal association created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete contact

Delete a contact from the specified address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To delete a contact, you make a DELETE request to the /v1/addressBooks/{addressBookId}/contacts/{contactId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`contactId`	Path	Identifies the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Contact deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get contact

Get the details of the specified contact from the address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	Phone number supported: US, UK, CA, JP Phone number not supported: FR, IT, DE, ES	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get a contact, you make a GET request to the /v1/addressBooks/{addressBookId}/contacts/{contactId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`contactId`	Path	Identifies the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the details of the specified contact. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body examples

The following examples show contact details: phone number, communication profile, or WebRTC service provider.

Response body properties

Property	Description	Type
`contact`	Contact to create. Includes one type of contact: `number`, `alexaCommunicationProfileId`, or `providerContact`.	Object
`contact.name`	Contact name. Valid value: 1–50 alphanumeric characters.	String
`contact.number`	(Optional) Contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. You can specify up to three phone numbers for a contact. Note: You can't include a phone number in `fr-FR`	String
`contact.alexaCommunicationProfileId`	(Optional) Identifies the communication profile for a unit. This value is the same as the `profileId` listed in the Communications REST API Reference. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String
`contact.providerContact`	(Optional) Included for WebRTC calling only.	Object
`contact.providerContact.id`	Internal ID of the service provider. Formatted as an Amazon Common Identifier (ACI), `amzn1.comms.csp.id.{id}`.	String
`contactId`	Uniquely identifies the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.did.{id}`.	Integer

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of contacts from the specified address book.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

List contacts

Get the list of contacts for a given address book.

Note: The phoneNumbers object isn't returned in requests for France (fr-FR).

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To list contacts, you make a GET request to the /v1/addressBooks/{addressBookId}/contacts resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–1000. Default: 100.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of contacts. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
            "contactName": "Example Contact Name 1",
            "contactId": "amzn1.alexa.contact.did.1101"
        },
        {
            "contactName": "Example Contact Name 2",
            "contactId": "amzn1.alexa.contact.did.1234"
        },
        {
            "contactName": "Example Contact Name 3",
            "contactId": "amzn1.alexa.contact.did.1235"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.1"
    }
}

Response body properties

Property	Description	Type
`results`	List of contacts.	Array of objects
`results[].contactName`	Name of the contact. Valid value: 1–50 alphanumeric characters.	String
`results[].contactId`	Unique identifier for the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.did.{id}`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of contacts from the specified address book.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update contact

Update the metadata for the specified contact in an address book.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	Phone number supported: US, UK, CA, JP Phone number not supported: FR, IT, DE, ES	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To update a contact, you make a PUT request to the /v1/addressBooks/{addressBookId}/contacts/{contactId} resource.

Request path and header example

Copied to clipboard.

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

Request path and header parameters

Parameter	Located in	Description	Type	Required
`addressBookId`	Path	Identifies the address book. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.addressbook.did.{id}`.	String	Yes
`contactId`	Path	Identifies the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body examples

The following examples show requests to update a contact in the specified address book. You can define a contact as a phone number, communication profile, or WebRTC service provider.

Request body properties

Property	Description	Type	Required
`contact`	Contact to create. Include one type of contact: `number`, `alexaCommunicationProfileId`, or `providerContact`.	Object	Yes
`contact.name`	Contact name. Valid value: 1–50 alphanumeric characters.	String	Yes
`contact.number`	Contact phone number. Must be a US, UK, or Canada (CA) telephone number in E.164 format. You can specify up to three phone numbers for a contact. Note: You can't include a phone number in `fr-FR`.	String	No
`contact.alexaCommunicationProfileId`	Identifies the communication profile for a unit. This value is the same as the `profileId` listed in the Communications REST API Reference. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	No
`contact.providerContact`	Include for WebRTC calling only.	Object	No
`contact.providerContact.id`	Internal ID of the service provider. Formatted as an Amazon Common Identifier (ACI), `amzn1.comms.csp.id.{id}`.	String	No

Response

A successful response returns HTTP 200 OK, along the updated contact. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of contacts from the specified address book.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Provide feedback

Last updated: frontmatter-missing