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/v3/attributes.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": "Juan"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "Krajcik"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "juan.krajcik@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "61379"
    },
    {
      "handle": "vaccination_status",
      "name": "Vaccination Status",
      "value": true
    },
    {
      "handle": "vaccine_brand",
      "name": "Manufacturer",
      "value": "Pfizer"
    },
    {
      "handle": "vaccine_date_1",
      "name": "1st Dose",
      "value": "2021-01-01"
    },
    {
      "handle": "vaccine_date_2",
      "name": "2nd Dose",
      "value": "2021-02-01"
    }
  ],
  "status": [
    {
      "group": "health",
      "subgroups": [
        null
      ],
      "verified": true
    },
    {
      "group": "covid_vaccine",
      "subgroups": null,
      "verified": true
    }
  ]
}

Covid-19 Health Status

Covid-19 Vaccine ID

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 Email Primary email set by user
zip Postal Code Postal code set by user

Additional Vaccine Attributes

These are standard response values configured by default. The data passed back depends on your application configuration and requirements.


Handle Description
phone_country_code Phone Country Code
phone_country_name Phone Country Name
resident_street Resident Street
license_type License type
license_usage License usage
street1 Street1
social_verified Social Verified
addresses Addresses
previous_addresses Previous address(es) if available
address_street Primary Street
address_street1 Primary Street1
address_street2 Primary Street2
address_city Primary City
address_state Primary State
address_province Primary Province
address_country Primary Country
address_zip Primary Postal Code
transaction Transaction ID
resident_city Resident City
identifier External ID
idme_employee IDme Employee
fingerprint Device Fingeprint
itin_short Last 4 of ITIN
resident_state Resident State
street2 Street2
mname Middle Name
full_name Full Name
suffix Suffix
gender Gender
phone Phone
street Street
city City
state State
country Country
social Full SSN
birth_date Birth Date
social_short Last 4 of SSN
records_validated Validated in financial records
group Group Association
multifactor Multifactor
credentials Verified credentials
age Age
resident_zip Resident Zip
static Static Value
passport_number Passport Number
passport_expiration_date Passport Expiration Date
passport_country_code Passport Country
province Province
emails_confirmed Confirmed Emails
itin Full ITIN
credential_aal Transaction AAL
credential_ial Transaction IAL
credential_aal_highest Available AAL
credential_ial_highest Available IAL
yubico_product_id Yubico Product ID
yubico_delivery_type Yubico Delivery Type
yubico_quantity Yubico Quantity
ssn_itin_short Last 4 of SSN/ITIN
idme_vulnerable IDme Vulnerable
ssn_validation_method SSN Validation Method
itin_validation_method ITIN Validation Method
ssn_itin Full SSN/ITIN

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.