Skip to main content

​
Overview

The Identify API authenticates users through their UIP identity and returns verified personal information. Users always see exactly what data you’re requesting and can choose to approve or deny the request.

Biometric Security

Authentication with verified identity data

QR Code Ready

Automatic generation for desktop flows

Granular Control

Request only the data you need

Real-time Webhooks

Instant authentication notifications

​
Request Parameters

webhook_url (required)

Type: string (URL format)URL to receive authentication results. Must be HTTPS in production.Your webhook will receive a POST request when the user completes or cancels authentication.
Type: array of stringsSpecific data fields to request from the user. If empty or omitted, requests all available data.Available fields:
  • name - User’s complete legal name
  • date_of_birth - Date of birth as Unix timestamp
  • country_of_origin - Country where identity was verified (ISO 3166-1 alpha-2)
  • expiry_date - ID card expiration date as Unix timestamp (must be explicitly requested)
Default: name, date_of_birth, and country_of_origin (unless specific fields requested)
Type: stringIndicates the user’s device context for optimal flow:
  • mobile - User wants to authenticate on their current mobile device
  • desktop - User wants to scan QR code with another device
Default: desktop
Type: string (URL format)Deep link URL to return the user to your app after mobile authentication. Required when device_type: "mobile".Format: yourapp://auth-callback or https://yourapp.com/auth-callback
Type: integerNote: This parameter is not currently supported. The API always returns date_of_birth as a Unix timestamp. Developers must calculate age from the timestamp in their application logic.For age verification: Request date_of_birth, convert the Unix timestamp to a date, calculate age, and apply restrictions in your backend.
Type: objectAdditional data to associate with the authentication session for your records.Common fields: user_ip, session_info, internal_user_id, contextNote: Metadata is returned in webhook responses

​
Available Data Fields

Control exactly what information you receive. Users will see your business name and the specific data you’re requesting.

​
name

User’s complete legal name as verified during identity verification (powered by Didit).Example: "Alice Marie Johnson"Privacy note: Only request if you need the user’s real name.Included by default: Yes

​
date_of_birth

User’s date of birth as a Unix timestamp (seconds since epoch).Example: 643852800 (represents May 15, 1990)Note: Developers must convert Unix timestamp to desired date format. To verify age, calculate age from timestamp in your application logic.Included by default: Yes

​
country_of_origin

Country where the user’s identity was verified, using ISO 3166-1 alpha-2 country codes.Example: "US", "GB", "CA"Use case: Geographic restrictions, compliance requirementsIncluded by default: Yes

​
Privacy Best Practice

Only request the data you actually need
Users can see exactly what you’re requesting and are more likely to approve minimal data requests. All responses always include the user’s uip_id regardless of requested fields.

​
Request Examples

Omit the requested_data parameter or pass an empty array to request the standard fields.This returns:
  • uip_id (always included)
  • name
  • date_of_birth
  • country_of_origin
Note: expiry_date is NOT included by default—must be explicitly requested.Use case: Initial user registration where you need complete profile information.
Only request the fields you need for your use case.Example: Only request name and date of birth.
{
  "requested_data": ["name", "date_of_birth"]
}
This returns:
  • uip_id (always included)
  • name
  • date_of_birth
Use case: Account verification, personalization
Include expiry_date to verify the user’s government ID has not expired.
{
  "requested_data": ["name", "date_of_birth", "country_of_origin", "expiry_date"]
}
This returns:
  • uip_id (always included)
  • name
  • date_of_birth
  • country_of_origin
  • expiry_date - ID card expiration date
Use case: Compliance verification, fraud prevention, identity validity checks
The Identify API always returns date_of_birth as a Unix timestamp. Developers must calculate age from this timestamp in their application.To verify age:
  1. Request date_of_birth field (included by default)
  2. Receive Unix timestamp in webhook response
  3. Convert timestamp to date and calculate age in your backend
  4. Apply age restrictions based on your requirements
Example calculation:
timestamp = 643852800
birth_date = new Date(timestamp * 1000)
age = calculate_age(birth_date, today)
if (age >= 21) { grant_access() }
Use case: Age-restricted content, alcohol sales, gambling, mature content verification
For users authenticating on their mobile device, specify device_type: "mobile" and provide a redirect URL.Response includes an app_url that opens the UIP app directly, skipping the QR code.Use case: Mobile web apps, progressive web apps

​
Common Use Cases

Goal: Replace username/password authenticationFlow:
  1. User clicks “Login with UIP”
  2. Call Identify API with empty requested_data (or just name)
  3. Display QR code or redirect to app
  4. Receive webhook confirmation
  5. Create user session using uip_id
Benefits:
  • No password storage or management
  • Government-verified identities
  • Biometric security
  • Zero friction for users

​
Response Times

API Response

< 200msInitial API call returns QR code or deep link instantly

User Action

10-30 secondsAverage time for user to scan and authenticate

Webhook Delivery

< 1 secondWebhook sent immediately after user completes action

​
Next Steps

Get API Keys

Start integrating UIP authentication

QR Integration Guide

Learn about device flows and QR implementation

API Reference

Complete API reference with request/response schemas

Error Handling

Handle errors gracefully in your integration