Onboard Sessions

Create identity verification and AML check sessions for your customers. Onboard sessions enable KYC compliance, fraud prevention, and bank account verification through the TrustistOnboard portal.

Overview

Onboard sessions are time-limited workflows where customers complete verification steps through a secure portal. Each session can include:

• Identity Verification: Document upload, liveness detection, facial matching
• Document Checks: Passport, driving license, national ID validation
• Proof of Address: Utility bills, bank statements
• AML Screening: Sanctions lists, PEPs (Politically Exposed Persons), adverse media
• AML Monitoring: Ongoing monitoring for changes in risk profile
• Account Information Services (AIS): Bank account verification, balances, transactions

Session Lifecycle

Endpoints

Create an Onboard Session

Required Permissions: create_onboard_session

Request Body

Options Structure

Identity Options (options.identity):

AIS Options (options.ais):

Example Request: Identity Verification Only

{
  "customerId": "3kTp9j2mN5xR",
  "options": {
    "identity": {
      "identityCheck": true,
      "documentCheck": true,
      "proofOfAddressCheck": false,
      "amlExtensiveScreening": true
    }
  }
}

Example Request: Bank Account Verification Only

{
  "customerId": "3kTp9j2mN5xR",
  "emailAddress": "[email protected]",
  "options": {
    "ais": {
      "accounts": true,
      "balances": true,
      "transactions": false,
      "accountLimit": 1
    }
  }
}

Example Request: Complete KYC + AIS

{
  "customerId": "3kTp9j2mN5xR",
  "emailAddress": "[email protected]",
  "options": {
    "identity": {
      "identityCheck": true,
      "documentCheck": true,
      "proofOfAddressCheck": true,
      "amlExtensiveScreening": true,
      "amlExtensiveMonitoring": false
    },
    "ais": {
      "balances": true,
      "transactions": false,
      "accountLimit": null
    }
  }
}

Example Response

{
  "sessionId": "7mQx4nPk8vWz",
  "onboardUrl": "https://onboard.trustist.com/session/7mQx4nPk8vWz"
}

Get Session Status

Required Permissions: read_onboard_session

Parameters

Example Request

GET /v1/onboard/sessions/7mQx4nPk8vWz
Authorization: HMAC-SHA256 Credential=YOUR_KEY_ID, Signature=...

Example Response

{
  "id": "7mQx4nPk8vWz",
  "status": "complete",
  "progress": {
    "identity": {
      "completed": true,
      "confirmed": true,
      "completedAt": "2025-01-21T15:30:00Z"
    },
    "ais": {
      "completed": true,
      "completedAt": "2025-01-21T15:35:00Z"
    }
  },
  "created": "2025-01-21T14:00:00Z",
  "updated": "2025-01-21T15:35:00Z",
  "attemptCount": 1
}

Session Statuses

Get Verification Results

Required Permissions: read_onboard_results

Retrieves comprehensive verification check results including identity verification outcomes, AML screening results, document validation, and more. Use this endpoint after receiving a session completion webhook or confirming the session status is complete.

Example Response

{
  "identity": {
    "outcome": "clear",
    "document": {
      "type": "passport",
      "number": "123456789",
      "country": "GB",
      "verified": true,
      "authentic": true,
      "expiryDate": "2030-05-15"
    },
    "facialSimilarity": 0.98,
    "livenessCheck": "passed",
    "extractedData": {
      "firstName": "Sarah",
      "lastName": "Johnson",
      "dateOfBirth": "1985-03-15",
      "nationality": "GB"
    }
  },
  "aml": {
    "outcome": "clear",
    "sanctionsMatches": 0,
    "pepStatus": "none",
    "adverseMedia": [],
    "riskScore": 12
  }
}

Check Outcomes

Working with Bank Accounts (AIS)

When AIS options are enabled in an onboard session, customers can connect their bank accounts via Open Banking. Once connected, you can retrieve account information, balances, and transactions.

AIS Behaviour Differences:

• Onboard Sessions: Always require the customer to complete AIS when options.ais is set, regardless of existing bank access.
• Payments: May skip AIS redirect if the customer already has valid bank access that satisfies the payment's aisRequirements.

See the Customer Bank Accounts (AIS) guide for detailed information on accessing bank account data.

Webhooks

Register webhooks to receive real-time notifications when onboard sessions complete. This eliminates the need for polling and enables immediate response to verification outcomes.

See the Identity Verification Webhooks guide for detailed webhook documentation.

Quick Example: Register Webhook

POST /v1/onboard/webhooks

{
  "url": "https://yourapp.com/webhooks/onboard",
  "name": "Production Onboard Webhook",
  "events": ["onboard.session.completed"]
}

Common Use Cases

1. Financial Service KYC

// Create customer and start comprehensive KYC
const customer = await teClient.customers.create({
  firstName: "Alice",
  lastName: "Brown",
  emailAddress: "[email protected]",
  dateOfBirth: "1990-06-15"
});

const session = await createOnboardSession({
  customerId: customer.id,
  options: {
    identity: {
      identityCheck: true,
      documentCheck: true,
      amlExtensiveScreening: true,
      amlExtensiveMonitoring: true
    }
  }
});

// Redirect customer to session.onboardUrl
window.location.href = session.onboardUrl;

2. Lending Affordability Check

// Request bank account access for affordability assessment
var sessionRequest = new EcommerceOnboardSessionCreateRequest
{
    CustomerId = customerId,
    Options = new EcommerceOnboardSessionOptions
    {
        Ais = new EcommerceAisOptions
        {
            Balances = true,
            Transactions = true,
            AccountLimit = 3  // Allow up to 3 accounts
        }
    }
};

var session = await CreateOnboardSessionAsync(sessionRequest);

// After completion, retrieve bank data
var accounts = await GetCustomerBankAccountsAsync(customerId);
foreach (var account in accounts)
{
    var balance = await GetBankAccountBalanceAsync(customerId, account.Id);
    var transactions = await GetBankAccountTransactionsAsync(
        customerId, account.Id, startDate, endDate);
    
    // Analyze affordability
    var affordability = CalculateAffordability(balance, transactions);
}

3. High-Value Transaction Verification

# Combined identity + bank verification for high-value purchases
session = te_client.create_onboard_session({
    'customerId': customer_id,
    'options': {
        'identity': {
            'identityCheck': True,
            'amlExtensiveScreening': True
        },
        'ais': {
            'balances': True,
            'accountLimit': 1
        }
    }
})

# After completion, verify both identity and funds
results = te_client.get_session_results(session['sessionId'])

if results['identity']['outcome'] == 'clear':
    accounts = te_client.get_customer_bank_accounts(customer_id)
    if accounts and len(accounts) > 0:
        balance = te_client.get_bank_account_balance(
            customer_id, accounts[0]['id'])
        
        if balance['available'] >= purchase_amount:
            # Proceed with transaction
            process_high_value_purchase(customer_id, purchase_amount)

Best Practices

• Request Only What You Need: Only enable verification checks required for your use case. Excessive checks increase friction and customer drop-off.
• Use Webhooks: Register webhooks instead of polling for session completion. This improves response time and reduces API calls.
• Handle Expired Sessions: Sessions expire after 7 days. Create a new session if the customer needs to re-attempt verification.
• Store Session IDs: Link session IDs to your customer records for audit trails and historical reference.
• Manual Review Queue: For consider outcomes, implement a manual review process rather than auto-rejecting customers.
• Communicate Clearly: Explain to customers why verification is required and what documents they'll need.

Error Responses

Next Steps

• Set up webhooks to receive session completion notifications
• Learn about AIS to access customer bank account data
• Create customer records before creating onboard sessions
• View the API Reference for complete endpoint documentation