Skip to main content
POST
/
identify
curl --request POST \
  --url https://api.uip.digital/v1/identify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "intent": "Sign in to Example App",
  "requested_data": [
    "name",
    "birthdate"
  ]
}
'
{
  "session_id": "sess_abc123def456",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expires_at": "2025-01-11T12:35:00Z"
}
Identify and verify a user’s identity with biometric verification. Returns a QR code or deep link for the user to scan with their UIP app. Use this endpoint to authenticate users, verify age requirements, check location, or validate other identity attributes.

​
Request

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer token with your API key: Bearer YOUR_API_KEY
Content-TypeYesMust be application/json

​
Body Parameters

​
intent
string
required
Description of why you’re requesting identity verification. This is 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: name, birthdate, countryExample: ["name", "birthdate"]
Any values not in the list above will be ignored. The user will only be asked to share the requested attributes.

​
Response

​
Success Response (200 OK)

​
session_id
string
required
Unique identifier for this authentication session
​
expires_at
string
required
ISO 8601 timestamp when the session expires (5 minutes from creation)
​
qr_code
string
required
Base64-encoded PNG image of the QR code for users to scan

​
Example Request

{
  "intent": "Sign in to Example App",
  "requested_data": ["name", "birthdate"]
}

​
Example Response

{
  "session_id": "sess_1a2b3c4d5e6f",
  "expires_at": "2025-01-11T12:35:00Z",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

​
Webhook Callback

When the user completes the authentication, UIP sends a POST request to your webhook URL with the result.
Important: Webhooks are only sent when the user completes authentication. If the user cancels or the session expires without completion, no webhook is sent. Your application should handle timeouts on your end (sessions expire after 5 minutes).

​
Successful Identification

{
  "event": "identify",
  "data": {
    "uip_id": "user_abc123def456",
    "audit_id": "audit_9z8y7x6w5v4u",
    "session_id": "sess_1a2b3c4d5e6f",
    "name": "John Doe",
    "date_of_birth": "1990-05-15",
    "country_of_origin": "US",
    "expires_at": 1735689600
  }
}
Response fields:
  • event - Always "identify" for successful identifications
  • data.uip_id - The user’s unique UIP identifier
  • data.audit_id - Permanent audit trail reference ID (save this for compliance)
  • data.session_id - The session ID from your original request
  • data.name - User’s full name (if requested or all data requested)
  • data.date_of_birth - User’s date of birth in YYYY-MM-DD format (if requested or all data requested)
  • data.country_of_origin - User’s country code (if requested or all data requested)
  • data.expires_at - Unix timestamp when the UIP user identity expires and must renew verification with UIP
Only the fields you requested in requested_data will be included in the response. If you omitted requested_data or passed an empty array, all three fields (name, date_of_birth, country_of_origin) will be included.

​
Implementation Flow

1

Request Authentication

Call the Identify endpoint with your intent and optional requested data fields
2

Display QR Code

Show the returned QR code to the user, or provide the deep link if they’re on mobile
3

User Authenticates

User scans the QR code with the UIP app and approves the request with biometric verification
4

Receive Webhook

Your webhook receives the authentication result with verified identity data
5

Complete Action

Use the verified identity data to complete the user’s action (sign in, verify age, etc.)

​
Best Practices

Clear Intent

Always provide a clear, user-friendly intent message explaining why you need their identity

Request Minimum Data

Only request the data you actually need. Users are more likely to approve minimal requests

Handle Expiration

Sessions expire after 5 minutes. Implement retry logic or allow users to generate a new code

Verify Webhooks

Always verify the HMAC signature on webhook requests to ensure they’re from UIP

​
Common Use Cases

Request only the name field to authenticate users and create accounts
{
  "intent": "Sign in to your account",
  "requested_data": ["name"]
}
Request only the birthdate field to verify age without exposing other identity data
{
  "intent": "Verify you're 18+ to access content",
  "requested_data": ["birthdate"]
}
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 for this endpoint:
  • 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
  • auth/verification-required - UIP account must be verified before using this endpoint
  • request/invalid-payload - Request payload is invalid or missing required fields
  • request/not-found - No such registered route in API service
  • request/webhook-missing - Webhook URL not configured in Business Dashboard
  • payment/insufficient-funds - Insufficient account balance to complete request
  • resource/not-found - Business or UIP not found
  • internal/server-error - Failed to create session record
  • data/corrupt - Corrupt key data detected

Authorizations

​
Authorization
string
header
required

Use your UIP API key as a bearer token

Body

application/json
​
intent
string
required

Description of why you're requesting identity verification. Shown to the user in the UIP app.

​
requested_data
enum<string>[]

Optional array of identity attributes to request. If omitted or empty, all data is returned. Valid values: name, birthdate, country

Available options:
name,
birthdate,
country

Response

200 - application/json

Authentication session created

​
session_id
string

Unique identifier for this authentication session

​
qr_code
string

Base64-encoded PNG image of the QR code for users to scan

​
expires_at
string<date-time>

ISO 8601 timestamp when the session expires (5 minutes from creation)