# TrueGate Integration Guide # Give this file to your AI coding assistant to integrate TrueGate into your app. # URL: https://www.truegate.io/api/llms ## What is TrueGate TrueGate is an identity verification and AML compliance API. You send it a person or company, it verifies their identity and screens them against global sanctions lists. Returns a decision: approved, rejected, or review. ## Base URL https://www.truegate.io ## Authentication Every request needs a Bearer token. The API key starts with `tg_live_`. Header: `Authorization: Bearer tg_live_YOUR_API_KEY` Get an API key from the TrueGate dashboard at /dashboard/settings. --- ## Endpoints ### 1. Create a verification session ``` POST /api/v1/verification Content-Type: application/json Authorization: Bearer tg_live_YOUR_API_KEY ``` **Request body:** ```json { "vendor_data": "your-internal-user-id", "verification_type": "basic", "callback_url": "https://yourapp.com/webhooks/truegate", "redirect_url": "https://yourapp.com/onboarding/done" } ``` **verification_type options:** - `"basic"` — ID + liveness + face match + sanctions ($0.75) - `"advanced"` — Basic + 1000+ AML lists + PEP + adverse media + IP ($1.25) - `"email_verification"` — Email OTP verification ($0.25) - `"phone_verification"` — Phone OTP via WhatsApp ($0.25) - `"database_validation"` — Government database validation, 18 LATAM countries ($1.50) - `"phone_antifraud"` — Carrier lookup + identity match + SIM swap + reassigned number + SMS OTP ($0.35) - `"business_aml"` — Company sanctions + adverse media screening ($0.50) **Response:** ```json { "token": "abc123def456...", "url": "https://www.truegate.io/verify/abc123def456...", "result_url": "https://www.truegate.io/verify/abc123def456.../result", "session_id": 42, "expires_at": "2026-07-22T..." } ``` The `url` is the verification link. Send it to the user (email, SMS, embed in your app, iframe, etc). The user completes the verification there. TrueGate handles document capture, selfie, liveness, everything. The `result_url` is a public page showing the verification result. Share it with your users or embed it. Anyone with the URL can view the result and print/save as PDF. --- ### 2. Get verification result ``` GET /api/v1/verification/{token} Authorization: Bearer tg_live_YOUR_API_KEY ``` **Response:** ```json { "token": "abc123def456...", "vendor_data": "your-internal-user-id", "status": "approved", "verification_type": "basic", "final_decision": "approved", "extracted_name": "John Doe", "extracted_dob": "1990-01-15", "extracted_nationality": "Panama", "extracted_document_type": "Identity Card", "extracted_document_number": "8-123-4567", "identity_verified": true, "face_match_score": 0.95, "liveness_passed": true, "sanctions_match": false, "rejection_reasons": [], "result_url": "https://www.truegate.io/verify/abc123def456.../result", "created_at": "2026-07-21T...", "updated_at": "2026-07-21T..." } ``` The `result_url` is a public page showing the verification result. Share it with your users or embed it. Anyone with the URL can view the result and print/save as PDF. **status values:** `pending`, `processing`, `approved`, `rejected`, `review`, `expired` **final_decision values:** `approved`, `rejected`, or `null` (still processing) --- ### 3. List verifications ``` GET /api/v1/verification?page=1&pageSize=20 Authorization: Bearer tg_live_YOUR_API_KEY ``` **Response:** ```json { "sessions": [ { "token": "abc123...", "vendor_data": "user-123", "status": "approved", "verification_type": "basic", "extracted_name": "John Doe", "final_decision": "approved", "sanctions_match": false, "created_at": "2026-07-21T..." } ], "total": 150, "page": 1, "pageSize": 20, "totalPages": 8 } ``` --- ### 4. Run a compliance/sanctions check (without identity verification) ``` POST /api/compliance/check Content-Type: application/json Authorization: Bearer tg_live_YOUR_API_KEY ``` **Request body:** ```json { "full_name": "John Doe", "date_of_birth": "1990-01-15", "nationality": "PA", "check_type": "registration" } ``` **Response:** ```json { "check_id": 99, "match_found": false, "highest_match_score": 0.0, "risk_level": "low", "matches": [], "processing_time_ms": 245 } ``` --- ### 5. Screen a business (direct API, no link needed) ``` POST /api/v1/business-screening Content-Type: application/json Authorization: Bearer tg_live_YOUR_API_KEY ``` **Request body:** ```json { "company_name": "Acme Corp", "country": "PA", "registration_number": "12345", "vendor_data": "company-ref-456", "callback_url": "https://yourapp.com/webhooks/truegate" } ``` Only `company_name` is required. Everything else is optional. **Response (direct, no link — result is immediate):** ```json { "token": "abc123...", "vendor_data": "company-ref-456", "result_url": "https://www.truegate.io/verify/abc123.../result", "company_name": "Acme Corp", "country": "PA", "status": "approved", "sanctions_match": false, "aml": { "status": "Approved", "total_hits": 0, "score": null, "hits": [] }, "news": { "total_articles": 5, "risk_articles": 0, "articles": [{ "title": "...", "source": "...", "url": "...", "published_at": "..." }], "risk": [] }, "registry": [], "created_at": "2026-07-22T..." } ``` Cost: $0.50 per screening. Includes: sanctions/watchlist check (1,300+ lists), adverse media, Google News risk analysis. --- ### 6. Phone Validation & Antifraud ``` POST /api/v1/phone-validation Content-Type: application/json Authorization: Bearer tg_live_YOUR_API_KEY ``` **Request body:** ```json { "phone_number": "+15551234567", "full_name": "John Doe", "vendor_data": "user-456" } ``` Only `phone_number` is required (E.164 format). `full_name` enables identity match. Everything else is optional. **Response (direct, no link — result is immediate):** ```json { "token": "ph_abc123...", "status": "approved", "phone_number": "+15551234567", "carrier": { "name": "T-Mobile", "type": "mobile", "country": "US" }, "identity_match": { "match": true, "score": 0.95, "registered_name": "John A Doe" }, "sim_swap": { "detected": false, "last_swap_date": null, "risk": "low" }, "reassigned": { "detected": false, "last_assignment_date": "2019-03-15" }, "sms_verified": true, "risk_level": "low", "created_at": "2026-07-24T..." } ``` Cost: $0.35 per validation. Runs 5 checks in parallel: carrier lookup, identity match, SIM swap detection, reassigned number check, and SMS OTP verification. --- ## Webhook callback If you set `callback_url` when creating a verification, TrueGate will POST the result to your URL when the verification completes: ```json { "event": "verification.completed", "token": "abc123...", "vendor_data": "your-internal-user-id", "status": "approved", "final_decision": "approved", "extracted_name": "John Doe", "identity_verified": true, "sanctions_match": false, "timestamp": "2026-07-21T..." } ``` --- ## Typical integration for user onboarding ```typescript // 1. When a new user signs up, create a verification const res = await fetch("https://www.truegate.io/api/v1/verification", { method: "POST", headers: { "Authorization": "Bearer " + process.env.TRUEGATE_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ vendor_data: user.id, verification_type: "basic", callback_url: process.env.APP_URL + "/api/webhooks/truegate", redirect_url: process.env.APP_URL + "/onboarding/verified", }), }); const { url, token } = await res.json(); // 2. Send the verification URL to the user // Option A: Redirect them redirect(url); // Option B: Send by email await sendEmail(user.email, "Verify your identity", `Click here: ${url}`); // Option C: Embed in your app //