> ## Documentation Index
> Fetch the complete documentation index at: https://ramps-docs-sync-20260519.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Customers

> Configuring customers for Payouts

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.

<AccordionGroup>
  <Accordion title="Regulated Platforms" icon="">
    <Check>
      **Regulated platforms** have lighter KYC requirements since they handle compliance verification internally.
    </Check>

    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:

    ```bash theme={null}
    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.

    <Tabs>
      <Tab title="Individual customer">
        ```json theme={null}
        {
          "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"
          }
        }
        ```
      </Tab>

      <Tab title="Business Customer">
        ```json theme={null}
        {
          "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"
          }
        }
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Unregulated Platforms" icon="">
    <Warning>
      **Unregulated platforms** require full KYC/KYB verification of customers through hosted flows.
    </Warning>

    Unregulated platforms must:

    * **Hosted KYC Flow**: Use the hosted KYC link for complete identity verification
    * **Extended Review**: Customers may require manual review and approval in some cases

    ### 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](/payouts-and-b2b/onboarding/configuring-customers) for the full list of optional pre-fill fields.

    ```bash theme={null}
    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

    ```bash theme={null}
    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:**

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

    <Tip>
      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.
    </Tip>

    #### Complete KYC Process

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.

        <Note>
          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.
        </Note>
      </Step>

      <Step title="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`.

        <Warning>
          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.
        </Warning>
      </Step>

      <Step title="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 `KYC_STATUS` to be notified when the customer reaches a terminal status (`APPROVED`, `REJECTED`, `EXPIRED`, or `CANCELED`).
        * **Polling:** Call `GET /customers/{customerId}` and inspect `kycStatus`.
      </Step>

      <Step title="Handle completion">
        On `APPROVED`, the customer is ready to transact — proceed with account setup and unlock funding. On `REJECTED` or `EXPIRED`, surface the appropriate next step (for example, regenerate the link or request manual review).
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Customer Management

### Retrieving Customer Information

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

<CodeGroup>
  ```bash Grid-assigned customer ID theme={null}
  curl -X GET "https://api.lightspark.com/grid/2025-10-13/customers/{customerId}" \
    -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
  ```

  ```bash List customers with a filter theme={null}
  curl -X GET "https://api.lightspark.com/grid/2025-10-13/customers?platformCustomerId={platformCustomerId}&customerType={customerType}&createdAfter={createdAfter}&createdBefore={createdBefore}&cursor={cursor}&limit={limit}" \
    -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
  ```
</CodeGroup>

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

### Updating Customer Information

To update customer information:

```bash theme={null}
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 '{
    "bankAccountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123456789",
      "routingNumber": "987654321",
      "bankName": "Chase Bank"
    }
  }'
```

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.

## 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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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:

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

    <Tip>
      Please contact us to set up FBO account for a specific currency.
    </Tip>
  </Accordion>

  <Accordion title="Mexico: CLABE">
    ```json theme={null}
    {
      "accountType": "CLABE",
      "clabeNumber": "123456789012345678",
      "bankName": "Banco de México",
      "platformAccountId": "banco_mx_primary_5678"
    }
    ```
  </Accordion>

  <Accordion title="United States: ACH (Account and Routing Number)">
    ```json theme={null}
    {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123456789",
      "routingNumber": "987654321",
      "accountCategory": "CHECKING",
      "bankName": "Chase Bank",
      "platformAccountId": "chase_checking_1234"
    }
    ```
  </Accordion>

  <Accordion title="Brazil PIX">
    ```json theme={null}
    {
      "accountType": "PIX",
      "pixKey": "12345678901",
      "pixKeyType": "CPF",
      "platformAccountId": "pix_main_9012"
    }
    ```

    PIX key types can be one of: `CPF`, `CNPJ`, `PHONE`, `EMAIL`, or `RANDOM`.
  </Accordion>

  <Accordion title="India: UPI (Unified Payments Interface)">
    ```json theme={null}
    {
      "accountType": "UPI",
      "vpa": "somecustomer@okbank",
      "platformAccountId": "upi_primary_1234"
    }
    ```
  </Accordion>

  <Accordion title="International: IBAN">
    ```json theme={null}
    {
      "accountType": "IBAN",
      "iban": "DE89370400440532013000",
      "bankName": "Deutsche Bank",
      "platformAccountId": "deutsche_primary_3456"
    }
    ```
  </Accordion>
</AccordionGroup>

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

1. **Identity Verification**: Choose a proper KYC/KYB identity verification flow as detailed in the [Quickstart Guide](/payouts-and-b2b/quickstart#choosing-your-onboarding-flow)
2. **Data Security**: Store and transmit customer data securely, following data protection regulations
3. **Regular Updates**: Keep customer information up to date, especially banking details
4. **Error Handling**: Implement proper error handling to manage validation failures gracefully
5. **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:

```bash theme={null}
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:

```csv theme={null}
platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,accountType,accountNumber,bankName,platformAccountId,businessLegalName,routingNumber,accountCategory
customer123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US,US_ACCOUNT,123456789,Chase Bank,chase_primary_1234,,222888888,SAVINGS
biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US,US_ACCOUNT,987654321,Bank of America,boa_business_5678,Acme Corp,121212121,CHECKING
```

<Tip>
  CSV Upload Best Practices

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

You can track the job status through:

1. Webhook notifications (if configured)
2. Status endpoint:

```bash theme={null}
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:

```json theme={null}
{
  "jobId": "job_123456789",
  "status": "PROCESSING",
  "progress": {
    "total": 5000,
    "processed": 2500,
    "successful": 2499,
    "failed": 1
  },
  "errors": [
    {
      "platformCustomerId": "biz456",
      "error": {
        "code": "validation_error",
        "message": "Invalid bank account number"
      }
    }
  ]
}
```

<Tip>
  Best Practices for Bulk Operations

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

### CSV Format

The CSV file should have the following columns:

Required columns for all customers:

* 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)
* accountType: Bank account type (CLABE, US\_ACCOUNT, PIX, IBAN, UPI)
* accountNumber: Bank account number
* bankName: Name of the bank

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)
* accountType: Bank account type (CLABE, US\_ACCOUNT, PIX, IBAN, UPI)
* accountNumber: Bank account number
* bankName: Name of the bank

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

Additional required columns based on account type:

For US\_ACCOUNT:

* routingNumber: ACH routing number (9 digits)
* accountCategory: Either "CHECKING" or "SAVINGS"

For CLABE:

* clabeNumber: 18-digit CLABE number

For PIX:

* pixKey: PIX key value
* pixKeyType: Type of PIX key (CPF, CNPJ, EMAIL, PHONE, RANDOM)

For UPI:

* vpa: Virtual Payment Address for UPI payments

For IBAN:

* iban: International Bank Account Number
* swiftBic: SWIFT/BIC code (8 or 11 characters)