Quick Start Guide

This guide walks you through creating your first applicant and running identity verification using the TrustGate API. You'll have a working verification flow in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

A TrustGate account (sign up at bytrustgate.com)
Your API key (found in Settings > API)

Step 1: Get Your API Key

Log in to the TrustGate dashboard
Navigate to Settings > API
Click Generate New Key to create an API key
Copy your API key (starts with tg_live_ for production or tg_test_ for sandbox)

Keep Your API Key Secret

Never share your API key or commit it to version control. Use environment variables in your application.

Step 2: Create an Applicant

Create your first applicant using the API:

cURL

curl -X POST https://api.bytrustgate.com/api/v1/applicants \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "nationality": "USA",
    "country_of_residence": "USA"
  }'

Python

import httpx
import os

API_KEY = os.environ['TRUSTGATE_API_KEY']
BASE_URL = "https://api.bytrustgate.com/api/v1"

response = httpx.post(
    f"{BASE_URL}/applicants",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "external_id": "user_12345",
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-05-15",
        "nationality": "USA",
        "country_of_residence": "USA",
    },
)

applicant = response.json()
print(f"Created applicant: {applicant['id']}")

JavaScript (Node.js)

const API_KEY = process.env.TRUSTGATE_API_KEY;
const BASE_URL = "https://api.bytrustgate.com/api/v1";

const response = await fetch(`${BASE_URL}/applicants`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_id: "user_12345",
    email: "john.doe@example.com",
    first_name: "John",
    last_name: "Doe",
    date_of_birth: "1990-05-15",
    nationality: "USA",
    country_of_residence: "USA",
  }),
});

const applicant = await response.json();
console.log(`Created applicant: ${applicant.id}`);

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "user_12345",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "nationality": "USA",
  "country_of_residence": "USA",
  "status": "pending",
  "risk_score": null,
  "flags": [],
  "created_at": "2025-01-20T10:30:00Z"
}

Save the id from the response - you'll need it for the next steps.

Step 3: Run Screening

Run an AML/sanctions screening check against the applicant:

cURL

curl -X POST https://api.bytrustgate.com/api/v1/screening/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "check_types": ["sanctions", "pep"]
  }'

Python

response = httpx.post(
    f"{BASE_URL}/screening/check",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "applicant_id": applicant["id"],
        "check_types": ["sanctions", "pep"],
    },
)

screening_result = response.json()
print(f"Screening status: {screening_result['status']}")
print(f"Hits found: {screening_result['hit_count']}")

JavaScript

const screeningResponse = await fetch(`${BASE_URL}/screening/check`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    applicant_id: applicant.id,
    check_types: ["sanctions", "pep"],
  }),
});

const screeningResult = await screeningResponse.json();
console.log(`Screening status: ${screeningResult.status}`);
console.log(`Hits found: ${screeningResult.hit_count}`);

Response

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "entity_type": "individual",
  "screened_name": "John Doe",
  "screened_dob": "1990-05-15",
  "screened_country": "USA",
  "check_types": ["sanctions", "pep"],
  "status": "clear",
  "hit_count": 0,
  "started_at": "2025-01-20T10:31:00Z",
  "completed_at": "2025-01-20T10:31:02Z",
  "hits": []
}

Status Values:

clear - No matches found
hit - Potential matches require review
error - Check failed (retry recommended)

Step 4: Add User-Facing Verification (SDK)

If you need to collect documents and biometrics from your users, use the SDK:

Create an Access Token

// Server-side: Create access token for your user
const response = await fetch(`${BASE_URL}/sdk/access-token`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: "user_12345",  // Your user ID
    email: "john.doe@example.com",
    flow_name: "default",            // Or your custom workflow name
    redirect_url: "https://yourapp.com/verification-complete",
  }),
});

const { access_token, sdk_url, applicant_id } = await response.json();

Option A: Redirect to Hosted SDK

// Send user to our hosted verification page
window.location.href = sdk_url;

Option B: Embed in Your React App

import VerificationSDK from './VerificationSDK';

function VerificationPage({ accessToken }) {
  return (
    <VerificationSDK
      accessToken={accessToken}
      baseUrl="https://api.bytrustgate.com/api/v1/sdk"
      onComplete={(result) => console.log('Done!', result)}
      onError={(error) => console.error(error)}
    />
  );
}

See the SDK Integration Guide for complete details.

Step 5: Review the Applicant

After verification, review and approve or reject the applicant:

cURL

curl -X POST https://api.bytrustgate.com/api/v1/applicants/550e8400-e29b-41d4-a716-446655440000/review \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved"
  }'

Python

response = httpx.post(
    f"{BASE_URL}/applicants/{applicant['id']}/review",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "decision": "approved",
    },
)

result = response.json()
print(f"Applicant status: {result['status']}")

JavaScript

const reviewResponse = await fetch(
  `${BASE_URL}/applicants/${applicant.id}/review`,
  {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      decision: "approved",
    }),
  }
);

const result = await reviewResponse.json();
console.log(`Applicant status: ${result.status}`);

Step 6: Set Up Webhooks (Recommended)

Receive real-time notifications when verification events occur:

Go to Settings > Webhooks in the dashboard
Click Add Webhook
Enter your webhook URL (e.g., https://yourapp.com/webhooks/trustgate)
Select the events you want to receive:
- applicant.submitted
- applicant.verification_complete
- applicant.approved
- applicant.rejected
- screening.completed

Example Webhook Payload

{
  "event_type": "applicant.approved",
  "timestamp": "2025-01-20T10:32:00Z",
  "data": {
    "applicant_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user_12345",
    "status": "approved",
    "risk_score": 15,
    "risk_level": "low"
  }
}

Step 7: Use Primitives for Granular Control

Primitives let you invoke individual verification steps directly — useful for custom flows or composing your own logic:

curl -X POST https://api.bytrustgate.com/api/v1/primitives/screening.individual/invoke \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "name": "John Doe",
      "birth_date": "1990-05-15"
    }
  }'

Each primitive is metered individually. Check available primitives and your usage:

# List all primitives
curl https://api.bytrustgate.com/api/v1/primitives/ \
  -H "X-API-Key: YOUR_API_KEY"

# Check usage this month
curl https://api.bytrustgate.com/api/v1/primitives/usage/summary \
  -H "X-API-Key: YOUR_API_KEY"

See the Primitives API Reference for all 14 available primitives.

Complete Example

Here's a complete Python script that creates an applicant, runs screening, and reviews them:

import httpx
import os

API_KEY = os.environ['TRUSTGATE_API_KEY']
BASE_URL = "https://api.bytrustgate.com/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

# 1. Create applicant
applicant_response = httpx.post(
    f"{BASE_URL}/applicants",
    headers=headers,
    json={
        "external_id": "user_12345",
        "email": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-05-15",
        "nationality": "USA",
    },
)
applicant = applicant_response.json()
applicant_id = applicant["id"]
print(f"Created applicant: {applicant_id}")

# 2. Run screening
screening_response = httpx.post(
    f"{BASE_URL}/screening/check",
    headers=headers,
    json={
        "applicant_id": applicant_id,
        "check_types": ["sanctions", "pep"],
    },
)
screening = screening_response.json()
print(f"Screening complete: {screening['status']} ({screening['hit_count']} hits)")

# 3. Review applicant (if screening is clear)
if screening["status"] == "clear":
    review_response = httpx.post(
        f"{BASE_URL}/applicants/{applicant_id}/review",
        headers=headers,
        json={"decision": "approved"},
    )
    result = review_response.json()
    print(f"Applicant {result['status']}")
else:
    print(f"Review required: {screening['hit_count']} hits to investigate")

What's Next?

Now that you've completed your first verification:

Dashboard Tour - Explore the TrustGate interface
Test in Sandbox - Test edge cases before going live
SDK Integration - Add document & biometric verification
Document Verification - ID document verification details
API Reference - Full API documentation

Troubleshooting

401 Unauthorized

Your API key is invalid or expired. Check that:

The API key is correct (no extra spaces)
The key has not been revoked
You're using the X-API-Key header (not Authorization: Bearer)

404 Applicant Not Found

The applicant ID doesn't exist or belongs to a different tenant. Verify:

The ID is a valid UUID
The applicant was created under your account

429 Too Many Requests

You've exceeded the rate limit. Default limits:

100 requests per minute for standard plans
1000 requests per minute for enterprise plans

Wait 60 seconds and retry, or contact support to increase your limits.

Prerequisites​

Step 1: Get Your API Key​

Step 2: Create an Applicant​

cURL​

Python​

JavaScript (Node.js)​

Response​

Step 3: Run Screening​

cURL​

Python​

JavaScript​

Response​

Step 4: Add User-Facing Verification (SDK)​

Create an Access Token​

Option A: Redirect to Hosted SDK​

Option B: Embed in Your React App​

Step 5: Review the Applicant​

cURL​

Python​

JavaScript​

Step 6: Set Up Webhooks (Recommended)​

Example Webhook Payload​

Step 7: Use Primitives for Granular Control​

Complete Example​

What's Next?​

Troubleshooting​

401 Unauthorized​

404 Applicant Not Found​

429 Too Many Requests​

Prerequisites

Step 1: Get Your API Key

Step 2: Create an Applicant

cURL

Python

JavaScript (Node.js)

Response

Step 3: Run Screening

cURL

Python

JavaScript

Response

Step 4: Add User-Facing Verification (SDK)

Create an Access Token

Option A: Redirect to Hosted SDK

Option B: Embed in Your React App

Step 5: Review the Applicant

cURL

Python

JavaScript

Step 6: Set Up Webhooks (Recommended)

Example Webhook Payload

Step 7: Use Primitives for Granular Control

Complete Example

What's Next?

Troubleshooting

401 Unauthorized

404 Applicant Not Found

429 Too Many Requests