Upload customers via CSV file

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

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

options.body = form;

fetch('https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("multipart/form-data; boundary=---011000010111000001101001")
val body = RequestBody.create(mediaType, "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

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

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Customers

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., $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

Example CSV

umaAddress,platformCustomerId,customerType,fullName,birthDate,addressLine1,city,state,postalCode,country,platformAccountId,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

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

Upload customers via CSV file

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

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Basic <encoded-value>'}};

options.body = form;

fetch('https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("multipart/form-data; boundary=---011000010111000001101001")
val body = RequestBody.create(mediaType, "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/bulk/csv")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

val response = client.newCall(request).execute()

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

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

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

Body

multipart/form-data

file

required

CSV file containing customer information

Response

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

The status a job can have when the upload is accepted: PENDING until a worker picks it up, PROCESSING once one has. Poll the job for the later states.

Available options:

PENDING,

PROCESSING

Example:

"PENDING"

Using the API

API documentation

Upload customers via CSV file

CSV Format

Example CSV

Authorizations

Body

Response