Configuring Customers - Grid API Documentation

This guide provides comprehensive information about customer configuration in the Grid API, including customer types, registration processes, management, and bank account information.

Customer Types

The Grid API supports both individual and business customers. While the API schema itself makes most Personally Identifiable Information (PII) optional at the initial customer creation, specific fields may become mandatory based on the currencies the customer will transact with. Your platform’s configuration (retrieved via GET /config) includes a supportedCurrencies array. If a customer is intended to use a specific currency, any fields listed for that currency must be provided when creating or updating the customer.

Customer Registration Process

Creating a New Customer

When creating or updating customers, the customerType field must be specified as either INDIVIDUAL or BUSINESS. Depending if you are a regulated or unregulated platform your KYC/KYB requirements will vary.

Regulated Platforms

Regulated platforms have lighter KYC requirements since they handle compliance verification internally.

The KYC/KYB flow allows you to onboard customers through direct API calls.Regulated financial institutions can:

Direct API Onboarding: Create customers directly via API calls with minimal verification
Internal KYC/KYB: Handle identity verification through your own compliance systems
Reduced Documentation: Only provide essential customer information required by your payment counterparty or service provider.
Faster Onboarding: Streamlined process for known, verified customers

Creating Customers via Direct API

For regulated platforms, you can create customers directly through the API without requiring external KYC verification:To register a new customer in the system, use the POST /customers endpoint:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "customer_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Jane Doe",
    "birthDate": "1992-03-25",
    "nationality": "US",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

The examples below show a more comprehensive set of data. Not all fields are strictly required by the API for customer creation itself, but become necessary based on currency and UMA provider requirements if using UMA.

Individual customer
Business Customer

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "fullName": "John Sender",
  "birthDate": "1985-06-15",
  "address": {
    "line1": "Paseo de la Reforma 222",
    "line2": "Piso 15",
    "city": "Ciudad de México",
    "state": "Ciudad de México",
    "postalCode": "06600",
    "country": "MX"
  }
}

{
  "platformCustomerId": "b87d2e4a9c13f5b",
  "customerType": "BUSINESS",
  "businessInfo": {
    "legalName": "Acme Corporation",
    "registrationNumber": "789012345",
    "taxId": "123-45-6789"
  },
  "address": {
    "line1": "456 Oak Avenue",
    "line2": "Floor 12",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  }
}

Unregulated Platforms

Unregulated platforms rely on Grid to run KYC for individuals and KYB for businesses. You can onboard customers either through the hosted KYC/KYB link flow below, or by submitting customer data directly through the API. Both paths produce the same kycStatus transitions and emit the same CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING (and CUSTOMER.KYB_* equivalents) webhooks.

Either path works for unregulated platforms:

Hosted flow: Redirect customers to a Grid-hosted link (or embed the provider SDK) for identity verification. Best when you want Grid to handle the entire collection UX.
Direct API onboarding: Collect customer information in your own UI and submit it via the API. For INDIVIDUAL customers (KYC), personal information goes through POST /customers. For BUSINESS customers (KYB), you also register beneficial owners via POST /beneficial-owners. Submit for review with POST /verifications.

Hosted KYC Link Flow

The hosted KYC flow provides a secure, hosted interface where customers can complete their identity verification and onboarding process.The flow is two steps: create the customer with the information you have, then generate a hosted KYC link for that customer. The customer’s kycStatus stays PENDING until they complete the hosted flow.

1. Create the customer

Create the customer with POST /customers, supplying at least customerType and any fields you already have. See Configuring Customers for the full list of optional pre-fill fields.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "INDIVIDUAL",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "region": "US",
    "currencies": ["USD", "USDC"],
    "email": "jane.doe@example.com",
    "fullName": "Jane Doe"
  }'

Persist the returned id (the Grid customer ID) — you’ll need it for the next step.

2. Generate a KYC link

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers/Customer:019542f5-b3e7-1d02-0000-000000000001/kyc-link" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "redirectUri": "https://yourapp.com/onboarding-complete"
  }'

Response:

{
  "kycUrl": "https://kyc.lightspark.com/onboard/abc123def456",
  "expiresAt": "2027-01-15T14:32:00Z",
  "provider": "SUMSUB",
  "token": "_act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The response always includes kycUrl for the hosted flow. For providers that support direct SDK integration (currently SUMSUB), a token is also returned — you can pass this to the provider’s web SDK to embed verification in your own UI instead of redirecting. Both paths update the customer’s kycStatus identically.

Complete KYC Process

Create the customer

Call POST /customers with customerType and any pre-fill fields you have. The returned id is the customer’s Grid ID; their kycStatus is PENDING until verification completes.

Generate the KYC link

Call POST /customers/{customerId}/kyc-link. Each call returns a fresh single-use kycUrl and expiresAt; previously-issued links remain single-use but aren’t invalidated.

The redirectUri you pass is embedded in the generated kycUrl and is used to automatically return the customer to your application after they complete verification.

Send the customer through verification

Redirect the customer to kycUrl, or — if you want to embed the flow directly — initialize the provider’s SDK with the returned token.

The hosted URL is single-use and expires at expiresAt. If a customer needs to retry, call the endpoint again to generate a new link.

Track the decision

Reaching your redirectUri only means the customer finished the hosted flow — not that they were approved. Wait for the final decision in one of two ways:

Webhook (recommended): Subscribe to CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED for business customers) to be notified when the customer reaches a terminal status. CUSTOMER.KYC_PENDING (and the KYB_PENDING sibling) also fires when the customer is submitted for review — subscribe to it as well if you want to surface an “under review” state to the customer.
Polling: Call GET /customers/{customerId} and inspect kycStatus.

Handle completion

On APPROVED, the customer is ready to transact — proceed with account setup and unlock funding. On REJECTED, surface the appropriate next step (for example, regenerate the link or request manual review).

Direct API Onboarding

Prefer to collect identity information in your own UI and submit it to Grid yourself? Use the API directly instead of redirecting to a hosted link. The customer’s kycStatus transitions the same way and you receive the same CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING (and CUSTOMER.KYB_* equivalents) webhooks.The shape of the flow depends on the customer type:

KYC (INDIVIDUAL customers) — supply the customer’s personal information through the customer endpoint. No beneficial owners are involved.
KYB (BUSINESS customers) — create the business customer, then register its beneficial owners, directors, and officers individually.

KYC (individual)
KYB (business)

Create the customer with personal information

Call POST /customers with customerType: INDIVIDUAL and the personal information collected from the customer (legal name, date of birth, address, nationality, etc.). The returned id is the customer’s Grid ID; kycStatus starts at PENDING.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "INDIVIDUAL",
    "platformCustomerId": "9f84e0c2a72c4fa",
    "fullName": "Jane Doe",
    "birthDate": "1985-06-15",
    "nationality": "US",
    "email": "jane.doe@example.com",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

Upload supporting documents (if requested)

Some jurisdictions or currencies require an ID document or proof of address. Upload them with POST /documents using multipart/form-data, referencing the customer by customerId.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=Customer:019542f5-b3e7-1d02-0000-000000000001" \
  -F "documentType=PASSPORT" \
  -F "country=US" \
  -F "file=@./passport.jpg"

Submit for verification

Call POST /verifications to submit the customer for review. The response includes a verificationStatus. If anything is missing, verificationStatus is RESOLVE_ERRORS and the errors array describes exactly what to collect before retrying.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Blocked by missing data:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_PROOF_OF_ADDRESS_DOCUMENT",
      "acceptedDocumentTypes": ["PROOF_OF_ADDRESS"],
      "reason": "Proof of address document is required"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYC_PENDING also fires when the customer is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

Create the business customer

Call POST /customers with customerType: BUSINESS and the business information (legal name, registration number, tax ID, registered address).

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "BUSINESS",
    "platformCustomerId": "b87d2e4a9c13f5b",
    "businessInfo": {
      "legalName": "Acme Corporation",
      "registrationNumber": "789012345",
      "taxId": "123-45-6789"
    },
    "address": {
      "line1": "456 Oak Avenue",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }'

Register each beneficial owner, director, or officer with POST /beneficial-owners. Each one is verified individually with their own personal information.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/beneficial-owners" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "roles": ["DIRECTOR"],
    "ownershipPercentage": 40,
    "personalInfo": {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1985-06-15",
      "nationality": "US",
      "address": {
        "line1": "123 Pine Street",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98101",
        "country": "US"
      },
      "idType": "SSN",
      "identifier": "123-45-6789"
    }
  }'

Upload supporting documents

Upload business documents (registration, articles of incorporation) and any documents required for individual beneficial owners with POST /documents. Reference the company by customerId and each owner by beneficialOwnerId.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=BeneficialOwner:019542f5-b3e7-1d02-0000-00000000abcd" \
  -F "documentType=PASSPORT" \
  -F "country=US" \
  -F "file=@./owner-passport.jpg"

Submit for verification

Call POST /verifications to submit the business for review. The response includes a verificationStatus. If beneficial owners, fields, or documents are missing, verificationStatus is RESOLVE_ERRORS and the errors array tells you exactly what to collect — note that resourceId may point at either the customer or a specific beneficial owner.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Blocked by missing data:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_FIELD",
      "field": "customer.address.line1",
      "reason": "Business address line 1 is required"
    },
    {
      "resourceId": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002",
      "type": "MISSING_FIELD",
      "field": "personalInfo.birthDate",
      "reason": "Date of birth is required for beneficial owners"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYB_PENDING also fires when the business is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

Customer Management

Retrieving Customer Information

You can retrieve customer information using either the Grid-assigned customer ID or your platform’s customer ID:

curl -X GET "https://api.lightspark.com/grid/2025-10-13/customers/{customerId}" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Note that this example shows all available filters. You can use any combination of them.

Updating Customer Information

To update customer information:

curl -X PATCH "https://api.lightspark.com/grid/2025-10-13/customers/{customerId}" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerType": "INDIVIDUAL",
    "currencies": ["USD", "EUR", "USDC"],
    "address": {
      "line1": "456 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94103",
      "country": "US"
    }
  }'

Note that not all customer information can be updated. Particularly for non-regulated platforms, you cannot update personal information after the customer has been created. The customerType discriminator is required on PATCH so the API knows which set of optional fields to validate. To update bank-account details, use the /customers/external-accounts endpoints — bank accounts are no longer managed inline on the customer resource.

Bank Account Information

The API supports various bank account formats based on country and funding type. There are two types of funding mechanisms supported by Grid: an omnibus FBO (for benefit of) account owned by the platform, or direct customer-owned accounts. You must provide the correct format based on the customer’s region and bank account type.

Optional Platform Account ID

All bank account types support an optional platformAccountId field that allows you to link bank accounts to your internal systems. This field can be any string that helps identify the account in your platform (e.g., database IDs, custom references, etc.). Example with platform account ID:

{
  "accountType": "US_ACCOUNT",
  "accountNumber": "123456789",
  "routingNumber": "987654321",
  "bankName": "Chase Bank",
  "platformAccountId": "chase_primary_1234"
}

Common use cases for platformAccountId:

Tracking multiple bank accounts and uma addresses for the same customer
Linking accounts to internal accounting systems
Maintaining consistency between the Grid API and your platform’s account records
Facilitating account reconciliation and reporting

FBO Accounts

FBO accounts are used when the platform has a single omnibus account that is used to fund all customers. Account details must be provided manually at the platform level. For each customer, during you should simply provide:

"bankAccountInfo": {
  "accountType": "FBO",
  "currencyCode": "USD" // or any other currency code supported by the Grid API
}

Please contact us to set up FBO account for a specific currency.

Mexico: CLABE

{
  "accountType": "CLABE",
  "clabeNumber": "123456789012345678",
  "bankName": "Banco de México",
  "platformAccountId": "banco_mx_primary_5678"
}

United States: ACH (Account and Routing Number)

{
  "accountType": "US_ACCOUNT",
  "accountNumber": "123456789",
  "routingNumber": "987654321",
  "accountCategory": "CHECKING",
  "bankName": "Chase Bank",
  "platformAccountId": "chase_checking_1234"
}

Brazil PIX

{
  "accountType": "PIX",
  "pixKey": "12345678901",
  "pixKeyType": "CPF",
  "platformAccountId": "pix_main_9012"
}

PIX key types can be one of: CPF, CNPJ, PHONE, EMAIL, or RANDOM.

India: UPI (Unified Payments Interface)

{
  "accountType": "UPI",
  "vpa": "somecustomer@okbank",
  "platformAccountId": "upi_primary_1234"
}

International: IBAN

{
  "accountType": "IBAN",
  "iban": "DE89370400440532013000",
  "bankName": "Deutsche Bank",
  "platformAccountId": "deutsche_primary_3456"
}

Data Validation

The Grid API performs validation on all customer data. Common validation rules include:

All required fields must be present based on customer type
Date of birth must be in YYYY-MM-DD format and represent a valid date
Names must not contain special characters or excessive spaces
Bank account information must follow country-specific formats
Addresses must include all required fields including country code

If validation fails, the API will return a 400 Bad Request response with detailed error information.

Best Practices

Identity Verification: Choose a proper KYC/KYB identity verification flow as detailed in the Quickstart Guide
Data Security: Store and transmit customer data securely, following data protection regulations
Regular Updates: Keep customer information up to date, especially banking details
Error Handling: Implement proper error handling to manage validation failures gracefully
Idempotent Operations: Use your platformCustomerId consistently to avoid duplicate customer creation

Bulk Customer Import Operations

For scenarios where you need to add many customers to the system at once, the API provides a CSV file upload endpoint.

CSV File Upload

For large-scale customer imports, you can upload a CSV file containing customer information:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "file=@customers.csv"

The CSV file should follow a specific format with required and optional columns based on customer type. Here’s an example:

umaAddress,platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,businessLegalName
$john.doe@uma.domain.com,customer123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US,
$acme@uma.domain.com,biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US,Acme Corp

CSV Upload Best Practices

Use a spreadsheet application to prepare your CSV file
Validate data before upload (e.g., date formats, required fields)
Include a header row with column names
Use UTF-8 encoding for special characters
Keep file size under 100MB for optimal processing

You can track the job status through:

Webhook notifications (if configured)
Status endpoint:

curl -X GET "https://api.lightspark.com/grid/2025-10-13/customers/bulk/jobs/{jobId}" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Example job status response:

{
  "id": "Job:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PROCESSING",
  "progress": {
    "total": 5000,
    "processed": 2500,
    "successful": 2450,
    "failed": 50
  },
  "errors": [
    {
      "correlationId": "biz456",
      "code": "INVALID_FIELD",
      "message": "Invalid bank account number"
    }
  ]
}

Best Practices for Bulk Operations

Use platform customer IDs to track individual customers in the bulk operation
Implement proper error handling for partial successes
Consider breaking very large datasets into multiple smaller jobs
Use webhooks for real-time status updates on asynchronous jobs
For CSV uploads, validate your data before submission

CSV Format

The CSV file should have the following columns: Required columns for all customers:

umaAddress: The customer’s UMA address (e.g., $john.doe@uma.domain.com)
platformCustomerId: Your platform’s unique identifier for the customer
customerType: Either “INDIVIDUAL” or “BUSINESS”

Required columns for individual customers:

fullName: Individual’s full name
birthDate: Date of birth in YYYY-MM-DD format
addressLine1: Street address line 1
city: City
state: State/Province/Region
postalCode: Postal/ZIP code
country: Country code (ISO 3166-1 alpha-2)

Required columns for business customers:

businessLegalName: Legal name of the business
addressLine1: Street address line 1
city: City
state: State/Province/Region
postalCode: Postal/ZIP code
country: Country code (ISO 3166-1 alpha-2)

Optional columns for all customers:

addressLine2: Street address line 2
platformAccountId: Your platform’s identifier for the bank account
description: Optional description for the customer

Optional columns for individual customers:

email: Customer’s email address

Optional columns for business customers:

businessRegistrationNumber: Business registration number
businessTaxId: Tax identification number

Bank-account details are no longer part of the bulk customer CSV — manage them separately via the /customers/external-accounts endpoints.

Documentation Index

​Customer Types

​Customer Registration Process

​Creating a New Customer

​Creating Customers via Direct API

​Hosted KYC Link Flow

​1. Create the customer

​2. Generate a KYC link

​Complete KYC Process

​Direct API Onboarding

​Customer Management

​Retrieving Customer Information

​Updating Customer Information

​Bank Account Information

​Optional Platform Account ID

​Data Validation

​Best Practices

​Bulk Customer Import Operations

​CSV File Upload

​CSV Format

Customer Types

Customer Registration Process

Creating a New Customer

Creating Customers via Direct API

Hosted KYC Link Flow

1. Create the customer

2. Generate a KYC link

Complete KYC Process

Direct API Onboarding

Customer Management

Retrieving Customer Information

Updating Customer Information

Bank Account Information

Optional Platform Account ID

Data Validation

Best Practices

Bulk Customer Import Operations

CSV File Upload

CSV Format