Add a new customer

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",
  "email": "jane.smith@example.com",
  "phoneNumber": "+14155551234"
}
'

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 customerOneOf = await client.customers.create({
  CreateCustomerRequest: { customerType: 'INDIVIDUAL' },
});

console.log(customerOneOf);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.CustomerOneOf
import com.lightspark.grid.models.customers.IndividualCustomerCreateRequest

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

    val params: IndividualCustomerCreateRequest = IndividualCustomerCreateRequest.builder()
        .customerType(IndividualCustomerCreateRequest.CustomerType.INDIVIDUAL)
        .build()
    val customerOneOf: CustomerOneOf = client.customers().create(params)
}

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$john.doe@uma.domain.com",
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "john.doe@example.com",
  "phoneNumber": "+14155551234",
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "isDeleted": false,
  "contactVerification": {
    "email": "VERIFIED",
    "phone": "VERIFIED"
  },
  "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"
  },
  "taxIdType": "SSN",
  "taxIdentifier": "123-45-6789",
  "taxIdCountryOfIssuance": "US",
  "sourceOfFundsCategories": [
    "SALARY"
  ],
  "sourceOfFundsOtherDescription": "Contest winnings",
  "sourceOfWealthCategories": [
    "SALARY",
    "INVESTMENTS"
  ],
  "sourceOfWealthOtherDescription": "Royalty income from published works",
  "purposeOfAccount": "CONTRACTOR_PAYOUTS",
  "purposeOfAccountOtherDescription": "Household budgeting between spouses",
  "expectedMonthlyTransactionCount": "COUNT_100_TO_500",
  "expectedMonthlyTransactionVolume": "VOLUME_100K_TO_1M",
  "annualIncomeRange": "RANGE_100K_250K",
  "netWorthRange": "RANGE_500K_1M",
  "pepStatus": "NONE"
}

{
  "status": 400,
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "taxIdentifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

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

{
  "status": 405,
  "code": "METHOD_NOT_ALLOWED",
  "message": "<string>",
  "details": {}
}

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

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

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

POST

customers

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",
  "email": "jane.smith@example.com",
  "phoneNumber": "+14155551234"
}
'

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 customerOneOf = await client.customers.create({
  CreateCustomerRequest: { customerType: 'INDIVIDUAL' },
});

console.log(customerOneOf);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.CustomerOneOf
import com.lightspark.grid.models.customers.IndividualCustomerCreateRequest

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

    val params: IndividualCustomerCreateRequest = IndividualCustomerCreateRequest.builder()
        .customerType(IndividualCustomerCreateRequest.CustomerType.INDIVIDUAL)
        .build()
    val customerOneOf: CustomerOneOf = client.customers().create(params)
}

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$john.doe@uma.domain.com",
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "john.doe@example.com",
  "phoneNumber": "+14155551234",
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "isDeleted": false,
  "contactVerification": {
    "email": "VERIFIED",
    "phone": "VERIFIED"
  },
  "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"
  },
  "taxIdType": "SSN",
  "taxIdentifier": "123-45-6789",
  "taxIdCountryOfIssuance": "US",
  "sourceOfFundsCategories": [
    "SALARY"
  ],
  "sourceOfFundsOtherDescription": "Contest winnings",
  "sourceOfWealthCategories": [
    "SALARY",
    "INVESTMENTS"
  ],
  "sourceOfWealthOtherDescription": "Royalty income from published works",
  "purposeOfAccount": "CONTRACTOR_PAYOUTS",
  "purposeOfAccountOtherDescription": "Household budgeting between spouses",
  "expectedMonthlyTransactionCount": "COUNT_100_TO_500",
  "expectedMonthlyTransactionVolume": "VOLUME_100K_TO_1M",
  "annualIncomeRange": "RANGE_100K_250K",
  "netWorthRange": "RANGE_500K_1M",
  "pepStatus": "NONE"
}

{
  "status": 400,
  "message": "<string>",
  "details": {
    "errors": [
      {
        "field": "taxIdentifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ]
  }
}

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

{
  "status": 405,
  "code": "METHOD_NOT_ALLOWED",
  "message": "<string>",
  "details": {}
}

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

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

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

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

Enhanced-due-diligence (EDD) fields available as optional patchable attributes on an individual customer. Referenced via allOf from IndividualCustomerFields, so these appear as top-level optional fields on the customer resource itself; there is no separate EDD resource. The specific set required for a given customer is driven by the KYC provider's per-jurisdiction / per-flow / per-volume-tier rules (surfaced through MISSING_FIELD errors on POST /verifications).

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"]

string<email>

Email address for the customer. Required in regions that verify the email address before identity verification (e.g. the EU); optional otherwise.

Example:

"john.doe@example.com"

phoneNumber

string

Phone number for the customer in strict E.164 format. Required in regions that verify the phone number before identity verification (e.g. the EU); optional otherwise.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155551234"

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:

"$john.doe@uma.domain.com"

kycStatus

enum<string>

The current KYC status of a customer. HOLD means the customer is placed on hold and may be required to update or provide more information.

Available options:

UNVERIFIED,

PENDING,

APPROVED,

REJECTED,

HOLD

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

taxIdType

enum<string>

Type of tax identification

Available options:

SSN,

ITIN,

EIN,

NON_US_TAX_ID

Example:

"SSN"

taxIdentifier

string

Tax-identification number. For US persons this is the SSN (format ###-##-####) or ITIN. For non-US persons this is the tax number issued by taxIdCountryOfIssuance.

Example:

"123-45-6789"

taxIdCountryOfIssuance

string

Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when taxIdType is NON_US_TAX_ID.

Example:

"US"

sourceOfFundsCategories

enum<string>[]

Structured source-of-funds categories (FLOW of funds for this account).

A structured source-of-funds category for an individual customer (FLOW of funds into this account). Distinct from SourceOfFundsCategory, which covers business customers.

Available options:

SALARY,

SELF_EMPLOYMENT_INCOME,

INVESTMENT_INCOME,

PENSION,

RENTAL_INCOME,

GIFT,

INHERITANCE,

LOAN,

SAVINGS,

SALE_OF_ASSETS,

OTHER

Example:

["SALARY"]

sourceOfFundsOtherDescription

string

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

Example:

"Contest winnings"

sourceOfWealthCategories

enum<string>[]

Structured source-of-wealth categories (STOCK — origin of accumulated wealth).

Origin of the customer's accumulated wealth (STOCK). Distinct from SourceOfFundsCategory which describes the FLOW of funds for this specific account.

Available options:

SALARY,

BUSINESS_INCOME,

INVESTMENTS,

INHERITANCE,

PROPERTY_SALE,

GIFT,

RETIREMENT,

SAVINGS,

OTHER

Example:

["SALARY", "INVESTMENTS"]

sourceOfWealthOtherDescription

string

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

Example:

"Royalty income from published works"

purposeOfAccount

enum<string>

The intended purpose for using the Grid account

Available options:

CONTRACTOR_PAYOUTS,

CREATOR_PAYOUTS,

EMPLOYEE_PAYOUTS,

MARKETPLACE_SELLER_PAYOUTS,

SUPPLIER_PAYMENTS,

CROSS_BORDER_B2B,

AR_AUTOMATION,

AP_AUTOMATION,

EMBEDDED_PAYMENTS,

PLATFORM_FEE_COLLECTION,

P2P_TRANSFERS,

CHARITABLE_DONATIONS,

OTHER

Example:

"CONTRACTOR_PAYOUTS"

purposeOfAccountOtherDescription

string

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

Example:

"Household budgeting between spouses"

expectedMonthlyTransactionCount

enum<string>

Expected number of transactions per month

Available options:

COUNT_UNDER_10,

COUNT_10_TO_100,

COUNT_100_TO_500,

COUNT_500_TO_1000,

COUNT_OVER_1000

Example:

"COUNT_100_TO_500"

expectedMonthlyTransactionVolume

enum<string>

Expected total transaction volume per month in USD equivalent

Available options:

VOLUME_UNDER_10K,

VOLUME_10K_TO_100K,

VOLUME_100K_TO_1M,

VOLUME_1M_TO_10M,

VOLUME_OVER_10M

Example:

"VOLUME_100K_TO_1M"

annualIncomeRange

enum<string>

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

Available options:

UNDER_50K,

RANGE_50K_100K,

RANGE_100K_250K,

RANGE_250K_1M,

OVER_1M

Example:

"RANGE_100K_250K"

netWorthRange

enum<string>

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

Available options:

UNDER_100K,

RANGE_100K_500K,

RANGE_500K_1M,

RANGE_1M_5M,

RANGE_5M_25M,

OVER_25M

Example:

"RANGE_500K_1M"

pepStatus

enum<string>

Political exposure declaration (Politically Exposed Person status). HIO = head of an international organization. FAMILY_OR_ASSOCIATE covers close family members and known close associates of a PEP.

Available options:

NONE,

DOMESTIC,

FOREIGN,

HIO,

FAMILY_OR_ASSOCIATE

Example:

"NONE"

idType

enum<string>

Type of tax identification

Available options:

SSN,

ITIN,

EIN,

NON_US_TAX_ID

Example:

"SSN"

identifier

string

write-only

The individual's tax identification number. Required to onboard the individual as a US account holder. Only SSN and ITIN are currently accepted for an individual account holder; other identification types are rejected. Write-only — never returned in customer responses.

Example:

"123-45-6789"

Response

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:

"$john.doe@uma.domain.com"

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"]

string<email>

Email address for the customer.

Example:

"john.doe@example.com"

phoneNumber

string

Phone number for the customer in strict E.164 format.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155551234"

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

contactVerification

object

Email and phone verification state. Only present when the customer's payment provider requires it (e.g. EU customers); omitted otherwise.

Show child attributes

kycStatus

enum<string>

The current KYC status of a customer. HOLD means the customer is placed on hold and may be required to update or provide more information.

Available options:

UNVERIFIED,

PENDING,

APPROVED,

REJECTED,

HOLD

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

taxIdType

enum<string>

Type of tax identification

Available options:

SSN,

ITIN,

EIN,

NON_US_TAX_ID

Example:

"SSN"

taxIdentifier

string

Tax-identification number. For US persons this is the SSN (format ###-##-####) or ITIN. For non-US persons this is the tax number issued by taxIdCountryOfIssuance.

Example:

"123-45-6789"

taxIdCountryOfIssuance

string

Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when taxIdType is NON_US_TAX_ID.

Example:

"US"

sourceOfFundsCategories

enum<string>[]

Structured source-of-funds categories (FLOW of funds for this account).

A structured source-of-funds category for an individual customer (FLOW of funds into this account). Distinct from SourceOfFundsCategory, which covers business customers.

Available options:

SALARY,

SELF_EMPLOYMENT_INCOME,

INVESTMENT_INCOME,

PENSION,

RENTAL_INCOME,

GIFT,

INHERITANCE,

LOAN,

SAVINGS,

SALE_OF_ASSETS,

OTHER

Example:

["SALARY"]

sourceOfFundsOtherDescription

string

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

Example:

"Contest winnings"

sourceOfWealthCategories

enum<string>[]

Structured source-of-wealth categories (STOCK — origin of accumulated wealth).

Origin of the customer's accumulated wealth (STOCK). Distinct from SourceOfFundsCategory which describes the FLOW of funds for this specific account.

Available options:

SALARY,

BUSINESS_INCOME,

INVESTMENTS,

INHERITANCE,

PROPERTY_SALE,

GIFT,

RETIREMENT,

SAVINGS,

OTHER

Example:

["SALARY", "INVESTMENTS"]

sourceOfWealthOtherDescription

string

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

Example:

"Royalty income from published works"

purposeOfAccount

enum<string>

The intended purpose for using the Grid account

Available options:

CONTRACTOR_PAYOUTS,

CREATOR_PAYOUTS,

EMPLOYEE_PAYOUTS,

MARKETPLACE_SELLER_PAYOUTS,

SUPPLIER_PAYMENTS,

CROSS_BORDER_B2B,

AR_AUTOMATION,

AP_AUTOMATION,

EMBEDDED_PAYMENTS,

PLATFORM_FEE_COLLECTION,

P2P_TRANSFERS,

CHARITABLE_DONATIONS,

OTHER

Example:

"CONTRACTOR_PAYOUTS"

purposeOfAccountOtherDescription

string

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

Example:

"Household budgeting between spouses"

expectedMonthlyTransactionCount

enum<string>

Expected number of transactions per month

Available options:

COUNT_UNDER_10,

COUNT_10_TO_100,

COUNT_100_TO_500,

COUNT_500_TO_1000,

COUNT_OVER_1000

Example:

"COUNT_100_TO_500"

expectedMonthlyTransactionVolume

enum<string>

Expected total transaction volume per month in USD equivalent

Available options:

VOLUME_UNDER_10K,

VOLUME_10K_TO_100K,

VOLUME_100K_TO_1M,

VOLUME_1M_TO_10M,

VOLUME_OVER_10M

Example:

"VOLUME_100K_TO_1M"

annualIncomeRange

enum<string>

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

Available options:

UNDER_50K,

RANGE_50K_100K,

RANGE_100K_250K,

RANGE_250K_1M,

OVER_1M

Example:

"RANGE_100K_250K"

netWorthRange

enum<string>

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

Available options:

UNDER_100K,

RANGE_100K_500K,

RANGE_500K_1M,

RANGE_1M_5M,

RANGE_5M_25M,

OVER_25M

Example:

"RANGE_500K_1M"

pepStatus

enum<string>

Available options:

NONE,

DOMESTIC,

FOREIGN,

HIO,

FAMILY_OR_ASSOCIATE

Example:

"NONE"

List customers

Get customer by ID

⌘I

Using the API

API documentation

Authorizations

Body

Response