Before you start using the API, we have a few guidelines that we'd like to tell you about. We encourage you to read the full API Terms of Use, but here are the bullet points:
Protected REST endpoints can be access by making HTTP requests with the access token for a given user. The ID.me server will validate the access token to ensure it has not expired and that its scope covers the requested resource.
After receiving a successful verification response from the API, you should apply business logic to unlock the benefit you are offering to the end user. From a user experience perspective, it is recommended that you store the verified status in the user's session to keep the experience consistent in case the page is refreshed, the back button is pressed, etc. By hiding or disabling the button that inititiates the API call, you can prevent duplicate calls being made.
If you're writing an AJAX application, require a JSONP response, and would like to wrap our response with a callback, all you have to do is specify a callback parameter with the API call.
URI | Type |
---|---|
https://api.id.me/api/public/v3/attributes.json
?access_token=ACCESS_TOKEN |
JSON |
https://api.id.me/api/public/v3/attributes.json
?access_token=ACCESS_TOKEN &callback=callbackFunction |
JSONP |
GET
application/json
The response from ID.me's REST API attributes endpoint is returned in JSON format.
{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Danial"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Treutel"
},
{
"handle": "email",
"name": "Email",
"value": "danial.treutel@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "76862-3657"
},
{
"handle": "military_branch",
"name": "Military Branch",
"value": "Coast Guard"
},
{
"handle": "military_service_component",
"name": "Military Service Component",
"value": "active"
},
{
"handle": "military_service_started",
"name": "Military Service Started",
"value": "2020-04-11"
},
{
"handle": "military_service_ended",
"name": "Military Service Ended",
"value": "2000-04-11"
}
],
"status": [
{
"group": "military",
"subgroups": [
"Service Member"
],
"verified": true
}
]
}
The JSON response contains the verification status and attributes for the user. The specific attributes returned depend on your application configuration and needs.
Attributes | ||
Handle | Name | Value Description |
---|---|---|
uuid |
Unique Identifier |
ID randomly generated and unique to user |
fname |
First Name |
First name set by user |
lname |
Last Name |
Last name set by user |
|
Unique email set by user |
|
zip |
Zip Code |
Zip code set by user |
These are typical response values. The data passed back depends on your application configuration. |
Status | |
group |
Military Verification -
Government Employee Verification -
First Responder Verification -
Student Verification -
Alumni Verification -
Teacher Verification -
Employee Verification -
Nurse Verification -
Medical Verification -
|
subgroups |
Military Verification -
Government Employee Verification -
First Responder Verification -
Teacher Verification -
Employee Verification -
Nurse Verification -
|
verified |
|
Transactions | |
Transactional data can be passed back in the JSON response as well. If you are interested in learning more about the value of transactional data and how to add this data to the JSON response, please contact us. |
Once you have retreived the user’s attributes it is recommended that you store them in the user’s session to keep the experience consistent in case the page is refreshed, the back button is pressed, etc.
Storing key attributes about the user is vital to a seamless group affiliation verification experience. It is recommended to store these attributes in a seperate table within your database with some relation to the user record.
Handle | Name | Description |
---|---|---|
uuid | Unique Identifer | Unique identifier that is randomly generated and unique to user. |
Unique email set by the user. | ||
fname | First Name | First name set by user. |
lname | Last Name | Last name set by user. |