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 (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

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"
}

Update a Customer

Required Permissions: update_customer

Updates an existing customer record. Use this to add or modify customer details such as name, email address, or address information. This is particularly useful when you need to add missing data before creating a KYC-enabled onboard session.

Parameters

Request Body

Example Request

PUT /v1/customers/3kTp9j2mN5xR
Authorization: HMAC-SHA256 Credential=YOUR_KEY_ID, Signature=...
Content-Type: application/json

{
  "firstName": "Sarah",
  "lastName": "Johnson",
  "emailAddress": "[email protected]"
}

Example Response

{
  "id": "3kTp9j2mN5xR",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "emailAddress": "[email protected]",
  "dateOfBirth": "1985-03-15",
  "address": {
    "addressLine1": "123 High Street",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  },
  "created": "2025-01-21T14:30:00Z",
  "lastUpdated": "2025-01-21T15:45: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. Required for KYC-enabled onboard sessions.

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