Identify API

Authenticate users and retrieve verified identity information with UIP's core identification endpoint.

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.

Key Features

Biometric authentication with verified identity data
Granular data control - request only what you need
Automatic QR code generation for desktop flows
Real-time webhook notifications

Endpoint

POST https://identify.api.uip.id/v1/identify

Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Parameters

Parameter	Type	Required	Description
webhook_url	string	Yes	URL to receive authentication results
requested_data	array	No	Specific data fields to request. If empty, requests all available data

Available Data Fields

Control exactly what information you receive by specifying the requested_data array. Users will see your business name and exactly what data you're requesting, allowing them to make an informed decision to approve or deny access.

Standard Data Fields

full_name

User's complete legal name as verified during identity verification

date_of_birth

User's date of birth in YYYY-MM-DD format

country_of_origin

Country where user's identity was originally verified (ISO 3166-1 alpha-2)

Enterprise/Government Only

personal_number

Government-issued personal identification number (SSN, National ID, etc.)

Restricted Access: Only available to verified enterprise and government accounts with appropriate compliance credentials.

=� Privacy Best Practice

Only request the data you actually need for your use case. Users are more likely to approve requests that ask for minimal, relevant information.

Note: All responses will always include the user's public uip_id, even if not explicitly requested.

Request Examples

Request All Available Data

Leave requested_data empty to request all available data for your account type:

{
  "webhook_url": "Acme Inc",
  "webhook_url": "https://myapp.com/webhooks/uip",
  "requested_data": []
}

Request Specific Fields Only

Specify exactly which fields you need:

{
  "webhook_url": "MyFintech App",
  "webhook_url": "https://myapp.com/webhooks/uip",
  "requested_data": ["full_name", "date_of_birth"]
}

Enterprise Request (with Personal Number)

Enterprise and government accounts can request personal numbers:

{
  "webhook_url": "Government Agency",
  "webhook_url": "https://myapp.com/webhooks/uip/verify",
  "requested_data": ["full_name", "date_of_birth", "personal_number", "country_of_origin"]
}

Response Format

The API returns session information and, for desktop flows, a QR code for the user to scan with their mobile UIP app.

{
  "session_id": "sess_1234567890abcdef",
  "qr_data": "uip://identify/sess_1234567890abcdef",
  "mobile": false,
  "qr_image_url": "https://qr.uip.id/sess_1234567890abcdef.png",
  "expires_in": 180
}

Response Fields

Field	Type	Description
session_id	string	Unique identifier for this authentication session
qr_data	string	UIP protocol URL for authentication
mobile	boolean	Whether the request was detected as coming from a mobile device
qr_image_url	string	Pre-generated QR code image URL (desktop only)
expires_in	integer	Session expiration time in seconds (180 = 3 minutes)

Webhook Response

After the user completes authentication in their UIP app, you'll receive a webhook with the authentication result and requested user data.

Successful Authentication

{
  "event": "authentication_completed",
  "session_id": "sess_1234567890abcdef",
  "status": "success",
  "user_data": {
    "uip_id": "uip_user_9876543210",
    "full_name": "Alice Johnson",
    "date_of_birth": "1990-05-15",
    "country_of_origin": "US",
    "personal_number": "123-45-6789",
    "verified": true,
    "verification_level": "government_id"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Failed/Cancelled Authentication

{
  "event": "authentication_completed",
  "session_id": "sess_1234567890abcdef",
  "status": "failed",
  "error": "user_cancelled",
  "error_description": "User cancelled the authentication request",
  "timestamp": "2024-01-15T10:35:00Z"
}

� Important: Webhook Security

Always verify webhook authenticity using the signature header before processing the data.

X-UIP-Signature: sha256=your_webhook_signature

Complete Implementation

// JavaScript implementation
async function startUIPIdentification(requestedFields = []) {
  try {
    const response = await fetch('https://identify.api.uip.id/v1/identify', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + YOUR_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        webhook_url: 'https://myapp.com/webhooks/uip',
        requested_data: requestedFields
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    
    if (data.mobile) {
      // Mobile flow: redirect to UIP app
      window.location.href = data.qr_data;
    } else {
      // Desktop flow: show QR code
      displayQRCode(data.qr_image_url, data.expires_in);
    }
    
    return data.session_id;
  } catch (error) {
    console.error('UIP identification failed:', error);
    throw error;
  }
}

function displayQRCode(imageUrl, expiresIn) {
  const container = document.getElementById('qr-container');
  const img = document.createElement('img');
  img.src = imageUrl;
  img.alt = 'UIP Authentication QR Code';
  
  container.innerHTML = '';
  container.appendChild(img);
  
  // Show expiration countdown
  startCountdown(expiresIn);
}

// Usage examples
startUIPIdentification(); // Request all available data
startUIPIdentification(['full_name', 'date_of_birth']); // Request specific fields

Next Steps

Ready to implement UIP identification in your application?

Get API Keys QR Integration Guide