Person Profile REST API Reference

Use the Person Profile REST API to get the recognized speaker contact information. The API returns the contact information from the person speaking to Alexa. Before you can use this API, your skill must request permission. For more details, see Request Recognized Speaker Contact Information for Use in Your Skill.

API endpoint

Use one of the following API hosts, based on the region where the customer is located:

  • North America: https://api.amazonalexa.com
  • Europe: https://api.eu.amazonalexa.com
  • Far East: https://api.fe.amazon.com

You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.

Authentication

Each API request must have an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest. The apiAccessToken encapsulates the permissions granted to your skill.

To access recognized speaker contact information, the following permission scopes must be enabled for your skill and granted by the customer.

Permission scope Description

alexa::person_id:read

Allows your skill to use Voice IDs.

alexa::profile:name:read

Allows your skill to get the full name of the recognized speaker.

alexa::profile:given_name:read

Allows your skill to get the given first name of the recognized speaker.

alexa::profile:mobile_number:read

Allows your skill to get the mobile phone number of the recognized speaker.

Operations

The Person Profile API includes the following operations.

Operation HTTP method and URI

Get full name

GET /v2/persons/~current/profile/name

Get given name

GET /v2/persons/~current/profile/givenName

Get mobile number

GET /v2/persons/~current/profile/mobileNumber

Get full name

Get the full name of the recognized speaker.

Request

To get the speaker name, you make a GET request to the /v2/persons/~current/profile resource.

Request path and header example

Copied to clipboard.

GET /v2/persons/~current/profile/name
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

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 full name of the recognized speaker. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "name": "John Smith"
}

Response body properties

Property Description Type

name

Full name of the recognized speaker.

String

HTTP status codes

Status Description

200 OK

Response body contains the full name of the recognized speaker.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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 given name

Get the given first name of the recognized speaker associated with the specified access token.

Request

To get the given name, you make a GET request to the /v2/persons/~current/profile resource.

Request path and header example

Copied to clipboard.

GET /v2/persons/~current/profile/givenName
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

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 given first name of the recognized speaker. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "name": "John"
}

Response body properties

Property Description Type

name

Given first name of the recognized speaker.

String

HTTP status codes

Status Description

200 OK

Response body contains the first name of the recognized speaker.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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 mobile number

Get the mobile number of the recognized speaker.

This operation returns the country code and phone number. The phone number might contain the country code, and by itself, the phone number value is a valid number for dialing.

Example phone number values: +917799827710, 7799827710, +91 7799 82 77 11, +91 7799-82-77-11. Example country code values: +1, 001, 1.

Request

To get the mobile number, you make a GET request to the /v2/persons/~current/profile resource.

Request path and header example

Copied to clipboard.

GET /v2/persons/~current/profile/mobileNumber
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

Access token for the customer.
Set to request.context.System.apiAccessToken property value retrieved from a request from Alexa.

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 mobile number of the recognized speaker. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "countryCode": "+91",
    "phoneNumber": "7799-82-77-11"
}

Response body properties

Property Description Type

countryCode

Specifies the country code of the mobile number.
Valid length: 1–10 characters

String

phoneNumber

Specifies the mobile number.
Valid length: 1–20 characters

String

HTTP status codes

Status Description

200 OK

Response body contains the mobile number of the recognized speaker.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

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 number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. 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?

Last updated: Aug 01, 2024