Add a new customer

Register a new customer in the system with an account identifier and bank account information

POST /customers

cURL

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/customers \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerType": "INDIVIDUAL",
  "platformCustomerId": "ind-9f84e0c2",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "fullName": "Jane Smith",
  "birthDate": "1990-01-15",
  "nationality": "US"
}
'

201

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$[e-mail]",
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "[e-mail]",
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "isDeleted": false,
  "kycStatus": "APPROVED",
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "address": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  }
}

Authorizations

Authorization · string · header · required

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

Body

application/json

Individual Customer Create Request

Business Customer Create Request

customerType · enum<string> · required

Whether the customer is an individual or a business entity

Available options: INDIVIDUAL

Example:

"INDIVIDUAL"

platformCustomerId · string

Platform-specific customer identifier. If not provided, one will be generated by the system.

Example:

"9f84e0c2a72c4fa"

region · string

Country code (ISO 3166-1 alpha-2) representing the customer's regional identity. This determines the regulatory jurisdiction and KYC requirements for the customer. Required if the customer will use currencies with different KYC requirements across regions. A customer with accounts in multiple regions should be registered as separate customers. This field is immutable after creation.

Example:

"US"

currencies · string[]

List of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Required if the customer will use more than one sending currency, since the correct currencies cannot always be inferred. If not provided, currencies will be inferred from the customer's region. Some currency combinations may require separate customers — if so, the request will be rejected with details.

Example:

["USD", "USDC"]

email · string<email>

Email address for the customer.

Example:

"[e-mail]"

umaAddress · string

Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer.

Example:

"$[e-mail]"

kycStatus · enum<string>

The current KYC status of a customer

Available options: UNVERIFIED, PENDING, APPROVED, REJECTED

Example:

"APPROVED"

fullName · string

Individual's full name

Example:

"John Michael Doe"

birthDate · string<date>

Date of birth in ISO 8601 format (YYYY-MM-DD)

Example:

"1990-01-15"

nationality · string

Country code (ISO 3166-1 alpha-2)

Example:

"US"

address · object

Show child attributes

Response

201

application/json

Customer created successfully

Individual Customer

Business Customer

platformCustomerId · string · required

Platform-specific customer identifier

Example:

"9f84e0c2a72c4fa"

customerType · enum<string> · required

Whether the customer is an individual or a business entity

Available options: INDIVIDUAL

Example:

"INDIVIDUAL"

umaAddress · string · required

Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.

Example:

"$[e-mail]"

id · string · read-only

System-generated unique identifier

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

region · string

Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.

Example:

"US"

currencies · string[]

List of currency codes enabled for this customer.

Example:

["USD", "USDC"]

email · string<email>

Email address for the customer.

Example:

"[e-mail]"

createdAt · string<date-time> · read-only

Creation timestamp

Example:

"2025-07-21T17:32:28Z"

updatedAt · string<date-time> · read-only

Last update timestamp

Example:

"2025-07-21T17:32:28Z"

isDeleted · boolean · read-only

Whether the customer is marked as deleted

Example:

false

kycStatus · enum<string>

The current KYC status of a customer

Available options: UNVERIFIED, PENDING, APPROVED, REJECTED

Example:

"APPROVED"

fullName · string

Individual's full name

Example:

"John Michael Doe"

birthDate · string<date>

Date of birth in ISO 8601 format (YYYY-MM-DD)

Example:

"1990-01-15"

nationality · string

Country code (ISO 3166-1 alpha-2)

Example:

"US"

address · object

Show child attributes