Skip to main content

​
Welcome to UIP API Reference

This section contains the complete technical documentation for integrating UIP’s biometric identity, signature, and messaging services into your application. All endpoints are REST-based with JSON payloads and responses.
New to UIP? Start with the Getting Started Guide to understand core concepts before diving into endpoint details.

​
Base URL

All API requests use the following base URL: 
https://api.uip.digital/v1
Production only: UIP doesn’t provide a sandbox environment. Use your $5 signup credit for testing with real biometric verification.

​
Core APIs

UIP provides three primary APIs that work together to deliver complete identity and signature infrastructure:

Identify API

Biometric authentication and identity verification. Request verified user information like name, age, location, and more.$0.01 per identification

Sign API

Quick biometric signatures for lightweight agreements. Perfect for TOS, policies, and attestations. 5-minute signing window.$0.03 per signature

Message API (Text)

Encrypted messaging without attachments. Supports signatures. Perfect for notifications and text agreements.$0.03 per message

Message API (with Attachment)

Document messaging with attachments up to 20MB. Supports signatures. Available up to 3 months.$0.10 per message

Audit API

Retrieve permanent audit trails for all actions. Court-admissible evidence with cryptographic proof.Always Free

​
Supporting APIs

Authorize API

Platform delegation — request scoped access to act on behalf of businesses.Always Free

Invalidate API

Cancel pending signature requests before recipients sign. Only works for unsigned messages.Always Free

Webhook Test

Test your webhook endpoint configuration before going live.Always Free

​
Authentication

All UIP API endpoints require authentication using Bearer tokens. Include your API key in the Authorization header of every request. Header format: 
Authorization: Bearer YOUR_API_KEY
UIP supports two types of Bearer tokens:

Direct API Keys

Standard UUID-format API keys for businesses making direct API calls. Full access to all endpoints.

Delegation Tokens

Platform delegation tokens (uip_at_ prefix) generated via the Authorize API. Scoped access based on granted permissions.
Keep your API keys secure. Never expose them in client-side code, public repositories, or logs. Treat them like passwords.

​
Getting API Keys

1

Create UIP Identity

Sign up at uip.digital/identify and create your identity with government ID verification
2

Receive $5 Credit

New accounts automatically receive $5 in credits — enough for testing and initial implementation
3

Generate API Key

Create your API key from the dashboard and start making requests

​
Request & Response Format

All requests and responses use JSON format with UTF-8 encoding. Required headers:
  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json

​
Session Flow

The Identify and Sign APIs use a simple create-poll-complete flow. No redirect URIs, no code exchange, no webhooks needed. Implementation flow:
1

Create Session

Call POST /v1/identify (or POST /v1/sign) with your intent. You receive a session_id, qr_code (base64 PNG), and expires_at.
2

Display QR Code or Deep Link

Desktop users see a QR code to scan. Mobile users get an “Open UIP” button linking to https://www.uip.id/{session_id}.
3

User Scans & Authenticates

User opens UIP app, scans code (or taps deep link), and authenticates with biometric
4

Poll for Result

Poll GET /v1/identify/:id (or GET /v1/sign/:id) every 2-3 seconds until status is completed. The completed response includes all verified data directly — no separate code exchange needed.
Device detection: Detect mobile vs desktop and show the appropriate UX. QR code for desktop, deep link button for mobile. See the QR Integration Guide for details.

​
Webhook Integration

Webhooks are used for the Message API and Authorize API only. The Identify and Sign APIs use polling instead.
  • Message API: message event when a user signs or declines a signature-required message
  • Authorize API: authorize.completed event when a business owner approves delegation
  • Delegation revocation: delegation.revoked event when a business revokes platform access
  • Test: test event from the webhook test endpoint
Every webhook request includes an X-UIP-Signature header containing an HMAC SHA-256 signature. Your webhook secret is a UUID v4 identifier provided when you create your API key.Verify all webhook requests to ensure they’re from UIP and haven’t been tampered with.
Use the Webhook Test endpoint to verify your webhook handler before going live. It sends a test payload to your URL and reports the response.
Identify and Sign do NOT use webhooks. Use simple polling with GET /v1/identify/:id or GET /v1/sign/:id until the status is completed.

​
Error Handling

UIP uses standard HTTP status codes and provides detailed error information in the response body. Check HTTP status code first:
  • 2xx: Success
  • 4xx: Client error (fix your request)
  • 5xx: Server error (retry with exponential backoff)
Then examine the error code: 
{
  "error": "The requested resource was not found",
  "code": "resource/not-found"
}
See the Error Handling Guide for complete error code reference.

​
Rate Limits

UIP enforces rate limits to ensure fair usage and system stability:
ScopeLimitWindow
Global (per IP)500 requests1 minute
Per API Key300 requests1 minute
Authorize endpoint100 requests1 minute
When you exceed a rate limit, the API returns HTTP 429 with:
  • X-RateLimit-Limit — Maximum requests allowed
  • X-RateLimit-Remaining — Requests remaining in the current window
  • Retry-After — Seconds until the window resets

​
Audit Trail

Every UIP action generates a permanent audit record accessible via the Audit API. These records include:
  • Complete action details (authentication, signature, message)
  • Verified identity information
  • Cryptographic proof of action
  • Precise timestamps
  • Tamper-evident storage
Audit queries are always free and unlimited. Store audit IDs from completed sessions and webhook responses to retrieve records anytime.

​
Getting Started

Getting Started Guide

Step-by-step guide to your first UIP integration

QR Integration Guide

Learn how to implement the QR code and deep link flow

Platform Delegation

Build platforms that act on behalf of businesses

Error Handling

Complete guide to handling errors effectively

​
Need Help?

Contact Support

Questions about implementation or integration? We’re here to help.

Security Architecture

Learn about UIP’s security architecture and encryption