Skip to main content
Get up and running with UIP’s Identify API in minutes. This guide walks you through creating your first identity verification session with working code examples.
Prerequisites: You need an API key from business.uip.digital. New accounts get $5 in credits to test with.

​
1. Get Your API Key

1

Sign up

Visit business.uip.digital and create your account with UIP identity verification
2

Create API Key

Navigate to Settings > API Keys and create a new key
3

Save it securely

Copy the key immediately and store it in an environment variable. It is only shown once.

​
2. Create an Identify Session

Make your first API call to create an identity verification session: 
curl -X POST https://api.uip.digital/v1/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Sign in to My App",
    "requested_data": ["first_name", "last_name", "date_of_birth"]
  }'
Response: 
{
  "session_id": "sess_1a2b3c4d5e6f",
  "expires_at": "2025-01-11T12:35:00Z",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
The QR code is returned as a base64 PNG data URI. Use device detection to show the right UX:
  • Desktop users — display the QR code image for scanning
  • Mobile users — display an “Open UIP” button that links to https://www.uip.id/{session_id}
<!-- Device detection: show QR on desktop, deep link on mobile -->
<div id="uip-desktop">
  <img id="uip-qr" alt="Scan with UIP app to verify identity" />
  <p>Scan with UIP app</p>
</div>

<div id="uip-mobile" style="display: none;">
  <a id="uip-link" class="button">Open UIP</a>
</div>

<script>
  const isMobile = /iPhone|iPad|Android/i.test(navigator.userAgent);

  if (isMobile) {
    document.getElementById('uip-desktop').style.display = 'none';
    document.getElementById('uip-mobile').style.display = 'block';
    document.getElementById('uip-link').href =
      `https://www.uip.id/${sessionId}`;
  } else {
    // qr_code from API response is a base64-encoded PNG data URI
    document.getElementById('uip-qr').src = qrCode;
  }
</script>
Session lifetime: Sessions expire after 5 minutes. Show a timer and offer to generate a new session if it expires.
Future SDK: A client-side SDK is planned that will handle device detection, QR rendering, and polling automatically. For now, implement this logic in your application.

​
4. Poll for Completion

Poll GET /v1/identify/:id every 2-3 seconds. When the status changes to completed, the response includes all the verified identity data in the same response. 
async function pollIdentify(sessionId, apiKey) {
  while (true) {
    const res = await fetch(
      `https://api.uip.digital/v1/identify/${sessionId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const data = await res.json();

    if (data.status === 'completed') {
      // All verified data is right here
      console.log(`Verified: ${data.first_name} ${data.last_name}`);
      console.log(`Audit ID: ${data.audit_id}`);
      return data;
    }

    if (data.status === 'expired') {
      throw new Error('Session expired');
    }

    // Still pending -- wait and poll again
    await new Promise(r => setTimeout(r, 2500));
  }
}
Response when pending: 
{
  "status": "pending",
  "expires_at": "2025-01-11T12:35:00Z"
}
Response when completed: 
{
  "status": "completed",
  "expires_at": "2025-01-11T12:35:00Z",
  "audit_id": "audit_9z8y7x6w5v4u",
  "uip_id": "user_abc123def456",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "country": "US",
  "identity_expires_at": "2027-01-11T00:00:00Z"
}
That’s it. No webhooks, no redirect URIs, no code exchange. Your API key proves ownership of the session, so the verified data is returned directly.

​
Complete Example

Here is the full flow in one script: 
const API_KEY = process.env.UIP_API_KEY;
const BASE = 'https://api.uip.digital/v1';

// Step 1: Create session
const session = await fetch(`${BASE}/identify`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    intent: 'Sign in to My App',
    requested_data: ['first_name', 'last_name', 'date_of_birth']
  })
}).then(r => r.json());

console.log('Session created:', session.session_id);
console.log('Show QR code to user:', session.qr_code.substring(0, 50) + '...');

// Step 2: Poll for completion
let result;
while (true) {
  const poll = await fetch(`${BASE}/identify/${session.session_id}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  }).then(r => r.json());

  if (poll.status === 'completed') {
    result = poll;
    break;
  }
  if (poll.status === 'expired') {
    throw new Error('Session expired -- create a new one');
  }
  await new Promise(r => setTimeout(r, 2500));
}

// Step 3: Use the verified identity
console.log(`Welcome, ${result.first_name} ${result.last_name}!`);
console.log(`Audit trail: ${result.audit_id}`);

​
What’s Next?

Sign API

Request legally binding biometric signatures

Message API

Send encrypted messages with document attachments

QR Integration Guide

Device detection, QR display best practices, and deep linking