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 |
---|---|
|
Allows your skill to use Voice IDs. |
|
Allows your skill to get the full name of the recognized speaker. |
|
Allows your skill to get the given first name of the recognized speaker. |
|
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 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
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 |
---|---|---|---|---|
|
Header |
Access token for the customer. |
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 |
---|---|---|
|
Full name of the recognized speaker. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the full name of the recognized speaker. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
Header |
Access token for the customer. |
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 |
---|---|---|
|
Given first name of the recognized speaker. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the first name of the recognized speaker. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
Header |
Access token for the customer. |
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 |
---|---|---|
|
Specifies the country code of the mobile number. |
String |
|
Specifies the mobile number. |
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the mobile number of the recognized speaker. |
|
Indicates that one or more properties in the request body aren't valid.
|
|
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. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested resource not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- Configure Permissions for Customer Information in Your Skill
- Enhance Your Skill With Address Information
Last updated: Aug 01, 2024