Why use applications?

Applications represent the client applications (web apps, mobile apps, physical locations, etc.) that interact with ID.me services. Once an application is created, you receive a unique UUID that can be attached to your interactions with ID.me. This enables application-level interaction tracking and reporting, providing visibility into which specific applications are driving traffic, conversions, and user behavior. Additional use cases and capabilities may be added in the future.

API specifications

API specifications are not publicly available. Please contact your account manager or solution consultant to obtain detailed integration specifications.

API endpoints

Creating an application

POST /v1/organizations/{organizationUuid}/applications

Returns the created application object including the generated UUID.

Applications are created under a specific organization. You must provide the organization’s UUID in the path. The application creation requires several fields including the application name, status, class, and claimant UUID. The API validates conditional field dependencies. For example, certain architecture and platform fields are only valid when the application class is “digital”.

Key requirements

• Organization UUID is required in the path
• Required fields: name, status, class, claimantUuid
• Optional fields: type, subtype, architectureType, operatingSystem, deviceTypes, consumerUuid, userTypes
  • Field values:

    Value	Definition
    name	Defined by the user
    claimantUuid	The UUID of an existing organization that defines which organization the application belongs to. This can be the organizationUuid provided in the request path or the UUID of another organization (for example, ID.me itself), depending on the ownership model.
    consumerUuid	The consumerUuid field is optional and is only required in specific migration scenarios. If provided, include the UUID when creating the application. Most external integrations do not need to supply this value.

Retrieving a single application

GET /v1/applications/{applicationUuid}

Returns the application object with all attributes.

Retrieve detailed information about a specific application using its UUID. The API enforces authorization. Users must have access to the application’s parent organization. If the user lacks access, a 404 response is returned to prevent enumeration.

Key requirements

• Application UUID is required in the path
• User must have read access to the application’s organization

Retrieving applications for an organization

GET /v1/organizations/{organizationUuid}/applications

Returns an array of application objects (empty array if none exist).

Retrieve all applications that belong to a specific organization. This is useful when you need to list or audit all applications under an organization. Authorization is enforced at the organization level.

Key requirements

• Organization UUID is required in the path
• User must have access to the specified organization

Updating an application

PATCH /v1/applications/{applicationUuid}

Returns the updated application object.

Partially update an existing application using PATCH semantics. Only the fields provided in the request body will be modified. This endpoint is commonly used to update application status, including soft deletion.

Key requirements

• Application UUID is required in the path
• Only updateable fields can be modified: status, class, type, subtype, architectureType, operatingSystem, deviceTypes, userTypes
• Immutable fields: name, organizationUuid, claimantUuid, consumerUuid
• The same conditional validation rules apply as during creation
• User must have access to the application’s organization

Soft deletion

To soft delete an application, use PATCH to change the application’s status to an inactive or deleted status value.

Getting enum values

GET /v1/applications/enums

Returns an array of valid enum values as strings, sorted alphabetically.

This endpoint returns the valid enum values for application attributes. You must use these values when creating or updating an application, as the API validates all enum fields against the allowed values.

Query parameters

Field dependencies

The enum values have hierarchical dependencies that reflect the following conditional validation rules:

These dependencies ensure that applications are created with valid and consistent attribute combinations. For example, you cannot specify an operating system unless the application architecture type supports it.

Example workflow

The following demonstrates a typical workflow and how the endpoints work together.

1
# Get available statuses
2
GET /v1/applications/enums?enum_name=status
3
Response: ["active", "inactive", ...]
4
5
# Get available classes
6
GET /v1/applications/enums?enum_name=class
7
Response: ["digital", "physical", ...]
8
9
# Get types for digital class
10
GET /v1/applications/enums?enum_name=type&class=digital
11
Response: ["web", "mobile", ...]
12
13
# Get architecture types (assuming class=digital was determined)
14
GET /v1/applications/enums?enum_name=architectureType&class=digital
15
Response: ["native", "web", ...]

1
POST /v1/organizations/550e8400-e29b-41d4-a716-446655440000/applications
2
{
3
  "name": "Mobile Banking App",
4
  "status": "active",
5
  "class": "digital",
6
  "type": "mobile",
7
  "architectureType": "native",
8
  "claimantUuid": "123e4567-e89b-12d3-a456-426614174000",
9
  "userTypes": ["personal", "business"]
10
}
11
12
Response: {
13
  "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
14
  "name": "Mobile Banking App",
15
  "status": "active",
16
  ...
17
}

1
GET /v1/organizations/550e8400-e29b-41d4-a716-446655440000/applications
2
3
Response: [
4
  {
5
    "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
6
    "name": "Mobile Banking App",
7
    "status": "active",
8
    ...
9
  },
10
  ...
11
]

1
PATCH /v1/applications/7c9e6679-7425-40de-944b-e07fc1f90ae7
2
{
3
  "status": "inactive"
4
}
5
6
Response: {
7
  "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
8
  "name": "Mobile Banking App",
9
  "status": "inactive",
10
  ...
11
}

Additional notes

• All endpoints require proper authentication (access token for external usage and JWT for internal usage)
• UUID formats are validated for all UUID parameters
• Conditional field validation ensures data consistency across related attributes
• The enums endpoint should be consulted when building forms or validation logic to ensure submitted values are current

AI agent

If you are utilizing an AI agent to assist with writing the API client, please download the JSON file below and provide it to your agent.