Upload customers via CSV file

Upload a CSV file containing customer information for bulk creation. The CSV file should follow a specific format with required and optional columns based on customer type.

CSV Format

The CSV file should have the following columns:

Required columns for all customers:

• umaAddress: The customer’s UMA address (e.g., $[e-mail])
• 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

Example CSV

umaAddress,platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,platformAccountId,businessLegalName
[e-mail],customer123,INDIVIDUAL,John Doe,1990-01-15,123 Main St,San Francisco,CA,94105,US
[e-mail],biz456,BUSINESS,,,400 Commerce Way,Austin,TX,78701,US

The upload process is asynchronous and will return a job ID that can be used to track progress. You can monitor the job status using the /customers/bulk/jobs/{jobId} endpoint.

POST /customers/bulk/csv

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'

import fs from 'fs';
import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const response = await client.customers.bulk.uploadCsv({
  file: fs.createReadStream('path/to/file'),
});

console.log(response.jobId);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.bulk.BulkUploadCsvParams
import com.lightspark.grid.models.customers.bulk.BulkUploadCsvResponse
import java.io.ByteArrayInputStream

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: BulkUploadCsvParams = BulkUploadCsvParams.builder()
        .file("Example data".byteInputStream())
        .build()
    val response: BulkUploadCsvResponse = client.customers().bulk().uploadCsv(params)
}

202

{
  "jobId": "Job:019542f5-b3e7-1d02-0000-000000000006"
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Body

multipart/form-data

file · file · required

CSV file containing customer information

Response

202

application/json

CSV upload accepted for processing

jobId · string · required

Unique identifier for the bulk import job

Example:

"Job:019542f5-b3e7-1d02-0000-000000000006"

status · enum<string> · required

Available options: PENDING, PROCESSING