API Reference

Integrate TrueGate identity verification into your application.

Authentication

All API requests require a Bearer token. Get your API key from Settings in the dashboard.

curl -H "Authorization: Bearer tg_live_your_api_key" \
  https://truegate.vercel.app/api/v1/verification

Integration flow

Create a verification

Your backend calls POST /api/v1/verification with an API key. You receive a URL to redirect your user to.

Redirect user

Send your user to the url returned. They complete document capture and selfie on TrueGate.

Receive result

TrueGate sends a POST to your callback_url with the result. The user is also redirected to your redirect_url with query params.

Query anytime

You can also poll GET /api/v1/verification/{token} to check the status at any time.

Create verification

POST/api/v1/verification

Request body

Parameter	Type	Required	Description
vendor_data	string	No	Your internal reference (e.g. user ID)
callback_url	string	No	URL to receive webhook POST with result
redirect_url	string	No	URL to redirect user after verification
verification_type	string	No	"basic" (default)

Example

curl -X POST https://truegate.vercel.app/api/v1/verification \
  -H "Authorization: Bearer tg_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-456",
    "callback_url": "https://yourapp.com/api/truegate-webhook",
    "redirect_url": "https://yourapp.com/onboarding/complete"
  }'

Response

{
  "token": "a1b2c3d4e5f6...",
  "url": "https://truegate.vercel.app/verify/a1b2c3d4e5f6...",
  "session_id": 42,
  "expires_at": "2026-03-22T17:00:00.000Z"
}

Get verification result

GET/api/v1/verification/{token}

curl https://truegate.vercel.app/api/v1/verification/a1b2c3d4e5f6 \
  -H "Authorization: Bearer tg_live_your_api_key"

Response

{
  "token": "a1b2c3d4e5f6...",
  "status": "approved",
  "final_decision": "approved",
  "verification_type": "basic",
  "extracted_name": "John Doe",
  "extracted_dob": "1990-01-15",
  "extracted_nationality": "Panama",
  "identity_verified": true,
  "face_match_score": 96.37,
  "liveness_passed": true,
  "sanctions_match": false,
  "rejection_reasons": []
}

List verifications

GET/api/v1/verification?page=1&pageSize=20

curl "https://truegate.vercel.app/api/v1/verification?page=1" \
  -H "Authorization: Bearer tg_live_your_api_key"

Webhook callback

When a verification completes, TrueGate sends a POST to your callback_url:

{
  "event": "verification.completed",
  "token": "a1b2c3d4e5f6...",
  "vendor_data": "user-456",
  "status": "approved",
  "final_decision": "approved",
  "extracted_name": "John Doe",
  "identity_verified": true,
  "face_match_score": 96.37,
  "liveness_passed": true,
  "sanctions_match": false,
  "rejection_reasons": [],
  "timestamp": "2026-03-21T18:30:00.000Z"
}

User redirect

After verification, the user is automatically redirected to your redirect_url with query parameters:

https://yourapp.com/onboarding/complete?token=a1b2c3d4e5f6&status=approved&decision=approved

You can read the decision query param to immediately show the appropriate screen, then verify the result server-side via the API.

Verification statuses

Status			Description
pending			Session created, waiting for user
processing			User submitted, verification in progress
approved			All checks passed
rejected			One or more checks failed
expired			Session expired (24 hours)

Error codes

HTTP	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
402	INSUFFICIENT_BALANCE	Not enough balance. Top up in dashboard
403	FORBIDDEN	Verification belongs to another organization
404	NOT_FOUND	Verification not found
422	VALIDATION_ERROR	Invalid request parameters

Pricing

Each Basic KYC verification costs $0.75 and includes:

AML screening (OFAC, UN, EU sanctions lists)
ID verification (document OCR + authenticity)
Passive liveness detection
Face match (selfie vs document)

New accounts receive a $25.00 welcome bonus. Top up anytime in Settings.

TrueGate API v1 — truegate.vercel.app