Trulioo Getting Started: Account, Keys, & First API Call (2026)

Getting started overview

Integrating with Trulioo involves a series of steps designed to onboard developers efficiently, from account creation to submitting your first identity verification request. The process begins with setting up a Trulioo account, which grants access to the developer portal and the necessary tools for integration. This portal is where you will manage your API credentials and configure services.

Trulioo's GlobalGateway API is the primary interface for its identity verification services, including Identity Document Verification, Business Verification, and Watchlist Screening. The API utilizes a RESTful architecture, accepting JSON payloads and returning JSON responses. Authentication is handled via Basic Authentication, requiring an API Key (username) and password generated within your Trulioo account.

A key aspect of the getting started process is utilizing the sandbox environment. This dedicated testing environment allows developers to simulate various verification scenarios without impacting live data or incurring charges. It is crucial for validating API calls, understanding response structures, and debugging integration logic before deploying to a production environment. Trulioo provides SDKs for Python, Java, Node.js, and .NET to streamline development in these languages.

Quick Reference: Trulioo Getting Started Steps

Create an account and get keys

To begin using Trulioo, the first step is to establish an account. Trulioo's services are primarily geared towards enterprise clients, so the account creation process typically involves contacting their sales team to discuss your specific business needs and use cases. This consultation ensures that your account is provisioned with access to the appropriate services and configurations relevant for global identity verification and compliance requirements, such as Anti-Money Laundering (AML) and Know Your Customer (KYC) protocols.

Once your account is set up, you will gain access to the Trulioo Portal. Within this portal, you can navigate to the account settings or API access section to generate your API credentials. Trulioo uses a form of Basic Authentication, where your API Key acts as the username and a corresponding password is generated. It is critical to secure these credentials, as they grant programmatic access to your Trulioo services. Best practices for API key management, such as storing them in environment variables rather than hardcoding, should be followed to prevent unauthorized access, as recommended by security guidelines for HTTP authentication.

The Trulioo Portal also allows you to manage your environments, specifically differentiating between sandbox and production access. For initial development and testing, ensure you are using the sandbox environment endpoints and credentials. This isolation prevents accidental live transactions and allows for iterative testing of your integration logic. The credentials generated will be specific to either your sandbox or production environment, maintaining a clear separation of concerns.

Your first request

After obtaining your API Key and password, you can proceed to make your first request to the Trulioo GlobalGateway API. This initial request is typically directed at a sandbox environment endpoint to test connectivity and authentication without processing live data. The Trulioo API Reference provides detailed information on available endpoints and required parameters for various verification services, such as Identity Verification.

A common first request is an identity verification call. This involves sending a JSON payload containing applicant details (e.g., name, address, date of birth) to the Trulioo API. The API will then process this information against various data sources to return a verification result. Below is an example of how to construct and send a basic identity verification request using curl, assuming you have your API Key and password:

export TRULIOO_API_KEY="your_api_key_here"
export TRULIOO_PASSWORD="your_api_password_here"

curl -X POST \
  'https://gateway.trulioo.com/sandbox/api/v1/verify' \
  -H 'Content-Type: application/json' \
  -u "$TRULIOO_API_KEY:$TRULIOO_PASSWORD" \
  -d '{ 
    "AcceptTruliooTermsAndConditions": true,
    "CleansedAddress": false,
    "ConfigurationName": "Identity Verification",
    "ConsentForDataSources": [
      "DriverLicence",
      "UtilityBill"
    ],
    "CountryCode": "US",
    "DataFields": {
      "PersonInfo": {
        "FirstGivenName": "John",
        "FirstSurName": "Doe",
        "DayOfBirth": 1,
        "MonthOfBirth": 1,
        "YearOfBirth": 1990,
        "Gender": "M"
      },
      "Location": {
        "BuildingNumber": "100",
        "StreetName": "Main St",
        "Suburb": "Anytown",
        "StateProvinceCode": "CA",
        "PostalCode": "90210",
        "City": "Beverly Hills"
      }
    }
  }'

Replace your_api_key_here and your_api_password_here with your actual sandbox credentials. The CountryCode and DataFields should be populated with test data relevant to the country you are targeting for verification. The ConfigurationName parameter specifies which Trulioo verification workflow to use. For a first call, ensure that AcceptTruliooTermsAndConditions is set to true and that ConsentForDataSources includes appropriate data sources if required by your configuration.

A successful response from the sandbox environment will return a JSON object containing a TransactionID and a Record object with verification results. This response will indicate whether the identity was verified, partially verified, or unverified, along with details on specific data source outcomes.

Common next steps

After successfully making your first identity verification request in the sandbox, several common next steps will help you further integrate Trulioo into your application:

1. Explore Additional Services: Trulioo offers a range of services beyond basic identity verification, including Business Verification, Identity Document Verification, and Watchlist Screening. Investigate these to see how they align with your compliance and fraud prevention needs.
2. Implement Webhooks: For asynchronous processes, such as document verification or ongoing monitoring, Trulioo supports webhooks. Configuring webhooks allows Trulioo to notify your application of status changes or completed verifications, reducing the need for polling and improving real-time responsiveness. Detailed documentation on Trulioo webhooks is available.
3. Integrate with SDKs: If you are developing in Python, Java, Node.js, or .NET, consider utilizing Trulioo's official SDKs. These libraries abstract away much of the HTTP request boilerplate, making it easier to interact with the API and handle authentication.
4. Error Handling and Retries: Develop robust error handling mechanisms for API responses. Understand the various error codes and messages Trulioo can return and implement appropriate retry logic for transient errors.
5. Transition to Production: Once your integration is thoroughly tested in the sandbox, you will need to switch to Trulioo's production environment. This involves obtaining production API keys and updating your application's endpoints to point to the live Trulioo API.
6. Monitor Usage and Reporting: Familiarize yourself with the usage reports and analytics available in the Trulioo Portal. This helps in understanding transaction volumes, success rates, and identifying potential areas for optimization.
7. Review Compliance Requirements: Regularly review and ensure your integration complies with relevant regulations such as GDPR, CCPA, and industry-specific mandates, which Trulioo helps address through its various services and certifications like SOC 2 Type II.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for Trulioo integrations:

• Authentication Errors (401 Unauthorized):
  • Incorrect API Key/Password: Double-check that your API Key and password are precisely what you generated in the Trulioo Portal.
  • Environment Mismatch: Ensure you are using sandbox credentials with sandbox endpoints, and production credentials with production endpoints. They are not interchangeable.
  • Incorrect Encoding: Basic Authentication requires the API Key and password to be base64-encoded. While curl -u handles this automatically, ensure your client library or custom code is doing so correctly.
• Bad Request Errors (400 Bad Request):
  • Missing Required Fields: Verify that your JSON request body includes all mandatory fields as specified in the Trulioo API Reference for the specific endpoint you are calling.
  • Invalid Data Format: Check that data types (e.g., integer for DayOfBirth, string for names) and formats (e.g., date formats) match Trulioo's expectations.
  • AcceptTruliooTermsAndConditions: Ensure this field is set to true in your request payload for identity verification calls.
  • ConfigurationName: Confirm that the ConfigurationName provided in your request matches an active configuration in your Trulioo account.
• Server Errors (5xx):
  • These typically indicate an issue on Trulioo's side. Check the Trulioo Status Page for any reported outages or maintenance. If no issues are reported, contact Trulioo support with your TransactionID (if available) or the exact request and timestamp.
• Network Connectivity Issues:
  • Verify that your application can reach Trulioo's API endpoints. Firewall rules or proxy settings might be blocking outgoing requests.
• Reviewing Response Details: Always examine the full JSON response, including any error messages within the payload, for specific clues about what went wrong. Trulioo's error messages are often descriptive.