Documentation | REST API | ID.me Developers

API 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

Choose API Version:
V3 V2

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` https://api.id.me/api/public/v2/attributes.json`?access_token=ACCESS_TOKEN`	JSON
https://api.id.me/api/public/v3/attributes.json`?access_token=ACCESS_TOKEN`&`callback=callbackFunction` https://api.id.me/api/public/v2/attributes.json`?access_token=ACCESS_TOKEN`&`callback=callbackFunction`	JSONP

HTTP Method

GET

Response Content Type

application/json

Response

Choose API Version:
V3 V2

The response from ID.me's REST API attributes endpoint is returned in JSON format.

Example

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "military_branch",
      "name": "Military Branch",
      "value": "Army"
    },
    {
      "handle": "military_service_component",
      "name": "Military Service Component",
      "value": "active"
    },
    {
      "handle": "military_service_started",
      "name": "Military Service Started",
      "value": "2013-10-01"
    }
  ],
  "status": [
    {
      "group": "military",
      "subgroups": [
        "Service Member"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Service Member",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "military_branch": "Army",
  "military_service_component": "active",
  "military_service_started": "2013-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "military_branch",
      "name": "Military Branch",
      "value": "Army"
    },
    {
      "handle": "military_service_component",
      "name": "Military Service Component",
      "value": "active"
    },
    {
      "handle": "military_service_started",
      "name": "Military Service Started",
      "value": "2013-10-01"
    },
    {
      "handle": "military_service_ended",
      "name": "Military Service Ended",
      "value": "2017-10-01"
    }
  ],
  "status": [
    {
      "group": "military",
      "subgroups": [
        "Veteran"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Veteran",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "military_branch": "Army",
  "military_service_component": "active",
  "military_service_started": "2013-10-01",
  "military_service_ended": "2017-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "military_branch",
      "name": "Military Branch",
      "value": "Army"
    },
    {
      "handle": "military_service_component",
      "name": "Military Service Component",
      "value": "active"
    },
    {
      "handle": "military_service_started",
      "name": "Military Service Started",
      "value": "2013-10-01"
    },
    {
      "handle": "military_service_ended",
      "name": "Military Service Ended",
      "value": "2017-10-01"
    }
  ],
  "status": [
    {
      "group": "military",
      "subgroups": [
        "Retiree"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Retiree",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "military_branch": "Army",
  "military_service_component": "active",
  "military_service_started": "2013-10-01",
  "military_service_ended": "2017-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "military_member_branch",
      "name": "Military Member Branch",
      "value": "Army"
    },
    {
      "handle": "military_member_service_component",
      "name": "Military Member Service Component",
      "value": "active"
    },
    {
      "handle": "military_member_service_started",
      "name": "Military Member Service Started",
      "value": "2013-10-01"
    },
    {
      "handle": "military_member_service_ended",
      "name": "Military Member Service Ended",
      "value": "2017-10-01"
    }
  ],
  "status": [
    {
      "group": "military",
      "subgroups": [
        "Military Spouse"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Military Spouse",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "military_member_branch": "Army",
  "military_member_service_component": "active",
  "military_member_service_started": "2013-10-01",
  "military_member_service_ended": "2017-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "military_member_branch",
      "name": "Military Member Branch",
      "value": "Army"
    },
    {
      "handle": "military_member_service_component",
      "name": "Military Member Service Component",
      "value": "active"
    },
    {
      "handle": "military_member_service_started",
      "name": "Military Member Service Started",
      "value": "2013-10-01"
    },
    {
      "handle": "military_member_service_ended",
      "name": "Military Member Service Ended",
      "value": "2017-10-01"
    }
  ],
  "status": [
    {
      "group": "military",
      "subgroups": [
        "Military Family"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Military Family",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "military_member_branch": "Army",
  "military_member_service_component": "active",
  "military_member_service_started": "2013-10-01",
  "military_member_service_ended": "2017-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "government_department",
      "name": "Government Department",
      "value": "Department of the Treasury"
    }
  ],
  "status": [
    {
      "group": "government",
      "subgroups": [
        "Federal"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Federal",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "government_department": "Department of the Treasury"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "government_department",
      "name": "Government Department",
      "value": "Department of the Treasury"
    }
  ],
  "status": [
    {
      "group": "government",
      "subgroups": [
        "State"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "State",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "government_department": "Department of the Treasury"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "government_department",
      "name": "Government Department",
      "value": "Department of the Treasury"
    }
  ],
  "status": [
    {
      "group": "government",
      "subgroups": [
        "Local"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Local",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "government_department": "Department of the Treasury"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "registry_status",
      "name": "Registry Status",
      "value": "Valid"
    },
    {
      "handle": "registry_expiration",
      "name": "Registry Expiration",
      "value": "2017-10-01"
    }
  ],
  "status": [
    {
      "group": "responder",
      "subgroups": [
        "EMT"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "EMT",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "registry_status": "Valid",
  "registry_expiration": "2017-10-01"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    }
  ],
  "status": [
    {
      "group": "responder",
      "subgroups": [
        "Police Officer"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Police Officer",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "agency",
      "name": "Agency",
      "value": "Henderson FD - KY"
    }
  ],
  "status": [
    {
      "group": "responder",
      "subgroups": [
        "Firefighter"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "Firefighter",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "agency": "Henderson FD - KY"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "student_anticipated_graduation_date",
      "name": "Student Anticipated Graduation Date",
      "value": "2019-10-01"
    },
    {
      "handle": "student_school_name",
      "name": "Student School Name",
      "value": "Georgetown University"
    },
    {
      "handle": "student_enrollment_status",
      "name": "Student Enrollment Status",
      "value": "F"
    },
    {
      "handle": "student_school_type",
      "name": "Student School Type",
      "value": "4 YR/GRAD"
    }
  ],
  "status": [
    {
      "group": "student",
      "subgroups": [
        null
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": null,
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "student_anticipated_graduation_date": "2019-10-01",
  "student_school_name": "Georgetown University",
  "student_enrollment_status": "F",
  "student_school_type": "4 YR/GRAD"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    },
    {
      "handle": "teacher_school",
      "name": "Teacher School",
      "value": "Thomas Jefferson High School"
    },
    {
      "handle": "teacher_district",
      "name": "Teacher District",
      "value": "Fairfax County"
    },
    {
      "handle": "teacher_state",
      "name": "Teacher State",
      "value": "VA"
    }
  ],
  "status": [
    {
      "group": "teacher",
      "subgroups": [
        null
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": null,
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102",
  "teacher_school": "Thomas Jefferson High School",
  "teacher_district": "Fairfax County",
  "teacher_state": "VA"
}

{
  "attributes": [
    {
      "handle": "fname",
      "name": "First Name",
      "value": "Test"
    },
    {
      "handle": "lname",
      "name": "Last Name",
      "value": "User"
    },
    {
      "handle": "email",
      "name": "Email",
      "value": "test.user@id.me"
    },
    {
      "handle": "uuid",
      "name": "Unique Identifier",
      "value": "d733a89e2e634f04ac2fe66c97f71612"
    },
    {
      "handle": "zip",
      "name": "Zip Code",
      "value": "22102"
    }
  ],
  "status": [
    {
      "group": "employee",
      "subgroups": [
        "ID.me"
      ],
      "verified": true
    }
  ]
}

{
  "id": "d733a89e2e634f04ac2fe66c97f71612",
  "verified": true,
  "affiliation": "ID.me",
  "fname": "Test",
  "lname": "User",
  "email": "test.user@id.me",
  "zip": "22102"
}

Values

The JSON response contains the verification status and attributes for the user. The specific attributes returned depend on your application configuration and needs.

Handle	Name	Value Description
Attributes
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	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.

Parameter	Description and Value Range
Status
Attributes
uuid	User unique identifier
fname	First name set by user
lname	Last name set by user
email	Unique email set by user
zip	Zip code set by user
group	Troop ID - `military` Government ID - `government` Responder ID - `responder` Student ID - `student` Teacher ID - `teacher` Employee ID - `employee`
subgroups	affiliation	Troop ID - `Service Member` `Veteran` `Retiree` `Military Spouse` `Military Family` Government ID - `Federal` `State` `Local` Responder ID - `EMT` `Police Officer` `Firefighter` Student ID - Teacher ID - Employee ID - `ID.me`
verified	`true` or `false`
These are typical response values. The data passed back depends on your application configuration.

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.

Errors

If the user denies the access request or if the request is invalid, the client will be informed using the following parameters appended to the redirect uri:

Parameters

Name	Description
error	A single error code as described below.
error_description	A human-readable text providing additional information, used to assist in the understanding and resolution of the error occurred.
error_uri	A URI identifying a human-readable web page with information about the error, used to provide the end-user with additional information about the error.

Codes

Code	Description
invalid_request	The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed.
invalid_client	The client identifier provided is invalid.
unauthorized_client	The client is not authorized to use the requested response type.
redirect_uri_mismatch	The redirection URI provided does not match a pre-registered value.
access_denied	The end-user or authorization server denied the request.
unsupported_response_type	The requested response type is not supported by the authorization server.
invalid_scope	The requested scope is invalid, unknown, or malformed.

Best Practices

Creating a session

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 User Attribtues

Storing key attributes about the user is vital to a seamless group verification experience. It is recommended to store these attributes in a seperate table within your database with some relation to the user record.

Key Attributes

Handle	Name	Description
uuid	Unique Identifer	Unique identifier that is randomly generated and unique to user.
email	E-Mail	Unique email set by the user.
fname	First Name	First name set by user.
lname	Last Name	Last name set by user.

Was this section helpful?

Yes