Skip to main content
Create an identity verification session. Returns a QR code and session ID for the user to scan with their UIP app.

​
Body Parameters

​
intent
string
required
Description of why you’re requesting identity verification. Shown to the user in the UIP app.Example: "Sign in to Example App" or "Verify age for content access"
​
requested_data
array
Optional array specifying which identity attributes to request. If omitted or empty, all available data is returned.Valid values: first_name, last_name, date_of_birth, country, expires_atExample: ["first_name", "last_name", "date_of_birth"]

​
Example Request

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 Example App",
    "requested_data": ["first_name", "last_name", "date_of_birth"]
  }'

​
Response (200 OK)

{
  "session_id": "sess_1a2b3c4d5e6f",
  "expires_at": "2025-01-11T12:35:00Z",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
​
session_id
string
required
Unique identifier for this session. Use this to poll for results.
​
expires_at
string
required
ISO 8601 timestamp when the session expires (5 minutes from creation).
​
qr_code
string
required
Base64-encoded PNG data URI of the QR code. Display this to desktop users. The QR code encodes https://www.uip.id/{session_id}.

​
Implementation Flow

1

Create Session

Call POST /v1/identify with your intent and optional requested data fields
2

Display QR Code or Deep Link

Desktop: show the qr_code image. Mobile: show an “Open UIP” button linking to https://www.uip.id/{session_id}
3

Poll for Result

Call GET /v1/identify/:id every 2-3 seconds until status is completed or expired
4

Use Verified Data

Extract identity fields and audit_id from the completed response. Save audit_id for compliance.
No webhooks needed. The Identify API uses simple polling. No redirect URIs, no code exchange.

​
Common Use Cases

Request first_name and last_name to authenticate users and create accounts
{
  "intent": "Sign in to your account",
  "requested_data": ["first_name", "last_name"]
}
Request only the date_of_birth field to verify age without exposing other identity data
{
  "intent": "Verify you're 18+ to access content",
  "requested_data": ["date_of_birth"]
}
Request the country field to ensure compliance with regional regulations
{
  "intent": "Verify your location for service availability",
  "requested_data": ["country"]
}
Omit requested_data or pass empty array to receive all available identity attributes
{
  "intent": "Complete your profile setup"
}

​
Errors

See the Error Handling Guide for comprehensive error handling strategies. Possible error codes:
  • auth/missing-api-key - No API key provided in Authorization header
  • auth/invalid-api-key - Invalid API key
  • auth/revoked-api-key - API key has been revoked
  • auth/business-archived - Business account has been archived
  • request/invalid-payload - Request payload is invalid or missing required fields
  • payment/insufficient-funds - Insufficient account balance
  • resource/not-found - Session not found (GET endpoint)
  • internal/server-error - Failed to create or retrieve session