Customer Management

Create and manage customer records for your organisation. Customers are the end-users you want to perform identity verification, KYC checks, or process payments for.

Overview

Customers are the foundation of your integration with Trustist. Each customer record:

• Belongs to your tenant (organisation)
• Has a unique ID in ShortGuid format (e.g., 3kTp9j2mN5xR)
• Can be associated with multiple onboard sessions and payments
• Stores basic personal information (name, address, date of birth)
• Can be filtered by optional organisational ID for multi-branch setups

Customer Lifecycle

Endpoints

Create a Customer

Required Permissions: create_customer

Request Body

* At least one of firstName or lastName must be provided

Address Structure

Example Request

{
  "firstName": "Sarah",
  "lastName": "Johnson",
  "emailAddress": "[email protected]",
  "dateOfBirth": "1985-03-15",
  "address": {
    "addressLine1": "123 High Street",
    "addressLine2": "Flat 4B",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "orgId": "branch-001"
}

Example Response

{
  "id": "3kTp9j2mN5xR",
  "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "emailAddress": "[email protected]",
  "dateOfBirth": "1985-03-15",
  "address": {
    "addressLine1": "123 High Street",
    "addressLine2": "Flat 4B",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "orgId": "branch-001",
  "created": "2025-01-21T14:30:00Z",
  "lastUpdated": "2025-01-21T14:30:00Z"
}

Get a Customer

Required Permissions: read_customers

Parameters

Example Request

GET /v1/customers/3kTp9j2mN5xR
Authorization: HMAC-SHA256 Credential=YOUR_KEY_ID, Signature=...

Example Response

{
  "id": "3kTp9j2mN5xR",
  "tenantId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "emailAddress": "[email protected]",
  "dateOfBirth": "1985-03-15",
  "address": {
    "addressLine1": "123 High Street",
    "addressLine2": "Flat 4B",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "orgId": "branch-001",
  "created": "2025-01-21T14:30:00Z",
  "lastUpdated": "2025-01-21T14:30:00Z"
}

Common Use Cases

1. E-Commerce Customer Signup

// Customer registers for your e-commerce site
const customer = await createCustomer({
  firstName: "John",
  lastName: "Smith",
  emailAddress: "[email protected]",
  address: {
    addressLine1: "456 Main St",
    city: "Manchester",
    postalCode: "M1 1AA",
    country: "GB"
  }
});

// Store customer.id in your database linked to your user account
await db.users.update(userId, { trustistCustomerId: customer.id });

// Later, create payments for this customer
const payment = await createPayment({
  customerId: customer.id,
  amount: 99.99,
  reference: `ORDER-${orderId}`
});

2. Financial Service Onboarding

// Create customer during signup
var customerRequest = new TrustistEcommerceCustomerCreateRequest
{
    FirstName = signupForm.FirstName,
    LastName = signupForm.LastName,
    EmailAddress = signupForm.Email,
    DateOfBirth = signupForm.DateOfBirth,
    Address = new TrustistEcommerceCustomerAddress
    {
        AddressLine1 = signupForm.AddressLine1,
        City = signupForm.City,
        PostalCode = signupForm.PostalCode,
        Country = "GB"
    }
};

var customer = await teClient.Customers.CreateAsync(customerRequest);

// Immediately start identity verification
var sessionRequest = new EcommerceOnboardSessionCreateRequest
{
    CustomerId = customer.Id,
    Options = new EcommerceOnboardSessionOptions
    {
        Identity = new EcommerceIdentityOptions
        {
            IdentityCheck = true,
            AmlExtensiveScreening = true
        },
        Ais = new EcommerceAisOptions
        {
            Balances = true,
            AccountLimit = 1
        }
    }
};

var session = await CreateOnboardSessionAsync(sessionRequest);
// Redirect user to session.OnboardUrl

3. Multi-Branch Organisation

// Branch A creates customer
{
  "firstName": "Alice",
  "lastName": "Brown",
  "emailAddress": "[email protected]",
  "orgId": "branch-london"
}

// Branch B creates customer
{
  "firstName": "Bob",
  "lastName": "Green",
  "emailAddress": "[email protected]",
  "orgId": "branch-manchester"
}

// Later, query customers by orgId
GET /v1/customers?orgId=branch-london

Best Practices

• Store Customer IDs: Always store the returned id in your database linked to your user account. This allows you to reuse the customer record for multiple payments/sessions.
• Provide Complete Information: Include as much information as possible (especially address and date of birth) for better identity verification results.
• Use Org IDs for Multi-Branch: If you have multiple branches or organisations, use orgId to filter and segment customers.
• Handle Duplicates: Check your own database before creating customers to avoid duplicates. Trustist does not prevent duplicate customer records.
• Email for Notifications: Provide emailAddress to enable email notifications for verification sessions and payment receipts.

Error Responses

Next Steps

• Create Onboard Sessions to verify customer identity and link bank accounts
• Follow the Quick Start guide for a complete integration workflow
• View the API Reference for detailed endpoint documentation