Welcome to ID.me for developers! If you are interested in integrating ID.me, you are in the right place. Here we will cover how to get started implementing ID.me.
ID.me REST API
To get started with an integration you’ll need to do the following:
Terms of Use
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:
- ID.me users own their data.
- ID.me is a user-centric, permissions based platform that requires explicit permission for each transmission of information from a user to a partner brand through ID.me.
- You may not sell ID.me user data to third party sites.
- You cannot replicate the core user experience of ID.me
Endpoints
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.
Endpoint
https://api.id.me/api/public/v1/userinfo.json
HTTP Request Method
GET
Response Content Type
application/json
Parameters
| Name | Description |
|---|---|
access_token
|
The client identifier received during app registration. It is automatically generated and located in your application dashboard. |
callback
|
A parameter that defines the policy you are requesting permission to access. |
Responses
The response from ID.me's REST API attributes endpoint is returned in JSON format.
Example Responses
{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Sunny"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Nader"
},
{
"handle": "email",
"name": "Email",
"value": "sunny.nader@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "76024"
}
],
"status": [
{
"group": "alumni",
"subgroups": [
null
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Debi"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Herman"
},
{
"handle": "email",
"name": "Email",
"value": "debi.herman@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "91701-7550"
}
],
"status": [
{
"group": "doctor_canada",
"subgroups": [
null
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Solange"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Morar"
},
{
"handle": "email",
"name": "Email",
"value": "solange.morar@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "65957"
}
],
"status": [
{
"group": "medical",
"subgroups": [
"Athletic Trainer"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Julieann"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Heidenreich"
},
{
"handle": "email",
"name": "Email",
"value": "julieann.heidenreich@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "13800"
}
],
"status": [
{
"group": "government",
"subgroups": [
"Local"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Shawn"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Davis"
},
{
"handle": "email",
"name": "Email",
"value": "shawn.davis@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "13650-3457"
}
],
"status": [
{
"group": "military",
"subgroups": [
"Veteran"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Yulanda"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Cartwright"
},
{
"handle": "email",
"name": "Email",
"value": "yulanda.cartwright@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "63390-4249"
}
],
"status": [
{
"group": "military_canada",
"subgroups": [
"Veteran for Canada"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Pandora"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Nolan"
},
{
"handle": "email",
"name": "Email",
"value": "pandora.nolan@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "36964"
}
],
"status": [
{
"group": "nurse",
"subgroups": [
"Other"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Chery"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Bechtelar"
},
{
"handle": "email",
"name": "Email",
"value": "chery.bechtelar@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "82868-7893"
}
],
"status": [
{
"group": "nurse_canada",
"subgroups": [
"Registered Nurse for Canada"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Carlota"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Johns"
},
{
"handle": "email",
"name": "Email",
"value": "carlota.johns@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "11761-1023"
}
],
"status": [
{
"group": "responder",
"subgroups": [
"EMT"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Haley"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Volkman"
},
{
"handle": "email",
"name": "Email",
"value": "haley.volkman@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "66830-9955"
}
],
"status": [
{
"group": "responder_canada",
"subgroups": [
"EMT for Canada"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Frieda"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Collier"
},
{
"handle": "email",
"name": "Email",
"value": "frieda.collier@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "78560-6414"
}
],
"status": [
{
"group": "student",
"subgroups": [
null
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Kraig"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Corkery"
},
{
"handle": "email",
"name": "Email",
"value": "kraig.corkery@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "05915-2225"
}
],
"status": [
{
"group": "student_canada",
"subgroups": [
null
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Willie"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Simonis"
},
{
"handle": "email",
"name": "Email",
"value": "willie.simonis@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "57923"
}
],
"status": [
{
"group": "teacher",
"subgroups": [
"PreK-12 School Employee"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Nana"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Bergnaum"
},
{
"handle": "email",
"name": "Email",
"value": "nana.bergnaum@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "67554-4678"
}
],
"status": [
{
"group": "teacher_canada",
"subgroups": [
"School Employee for Canada"
],
"verified": true
}
]
}{
"attributes": [
{
"handle": "fname",
"name": "First Name",
"value": "Lesley"
},
{
"handle": "lname",
"name": "Last Name",
"value": "Grady"
},
{
"handle": "email",
"name": "Email",
"value": "lesley.grady@id.me"
},
{
"handle": "uuid",
"name": "Unique Identifier",
"value": "d733a89e2e634f04ac2fe66c97f71612"
},
{
"handle": "zip",
"name": "Zip Code",
"value": "22593"
}
],
"status": [
{
"group": "employee",
"subgroups": [
"Medina Regional Hospital"
],
"verified": true
}
]
}Values
The JSON response contains the verification status and attributes for the user. The specific attributes returned depend on your application configuration and needs.
Attributes
Default Attributes
These are standard response values configured by default. The data passed back depends on your application configuration and requirements.
| Handle | Name | 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 |
email
|
Primary email set by user | |
zip
|
Postal Code | Postal code set by user |
Additional Community_verification Attributes
These are standard response values configured by default. The data passed back depends on your application configuration and requirements.
| Handle | Name | Description |
|---|---|---|
alumni_award_date
|
Alumni Award Date | Award Date |
alumni_degree_status
|
Alumni Degree Status | Degree Status |
alumni_graduated
|
Alumni Graduated | Graduated |
alumni_school_type
|
Alumni School Type | School Type |
alumni_school_name
|
Alumni School Name | School Name |
alumni_graduation_date
|
Alumni Graduation Date | Graduation Date |
Status
| Handle | Description |
|---|---|
group
|
Community user is verified for |
subgroups
|
Subgroup under the community the user is verified for |
verified
|
Status of user verification |
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.