curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerType": "INDIVIDUAL",
  "fullName": "John Smith",
  "birthDate": "1985-06-15",
  "currencies": [
    "USD",
    "EUR",
    "USDC"
  ],
  "address": {
    "line1": "456 Market St",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US"
  }
}
'

{
  "status": "PROCESSING",
  "message": "This contact change is still being processed. Retry the same request in a moment."
}

Customers

Update customer by ID

Update a customer’s metadata by their system-generated ID.

Most customer updates complete synchronously and return 200 with the updated customer.

Changing email for a customer whose Embedded Wallet signs in with an EMAIL_OTP credential, or phoneNumber for one that signs in with an SMS_OTP credential, changes how the customer signs in. The customer must first prove they control the new contact:

Register the new contact with POST /auth/credentials, passing email or phoneNumber. Grid sends a one-time code to it and returns the replacement credential.
Verify that code with POST /auth/credentials/{id}/verify. Grid answers 204. A replacement that is not verified within 24 hours expires.
Call PATCH /customers/{customerId} with only customerType and the new contact. Grid returns 202 with payloadToSign, requestId, and expiresAt. Send this soon after verifying: if the verification would lapse before the challenge does, Grid returns AUTH_CREDENTIAL_VERIFICATION_EXPIRED instead, and the customer must verify again.
Use the session API keypair of an active session on the same Embedded Wallet to build an API-key stamp over payloadToSign. Retry the same request with that full stamp as the Grid-Wallet-Signature header and the requestId echoed back as the Request-Id header. The signed retry returns 200 with the updated customer, and the replacement becomes the wallet’s sign-in credential in place of the old one. If the change is still being applied, the retry returns 200 with a WalletOperationProcessing body; re-send the identical signed request until it returns the customer.

A change to a sign-in contact without a verified replacement returns 400 with AUTH_CREDENTIAL_VERIFICATION_REQUIRED. Customers without an Embedded Wallet credential of that type change email or phoneNumber with a plain update. A business administrator’s credentials (those with adminReference) are not tied to the customer’s contact and keep their own email.

Update email and phoneNumber in separate PATCH calls. A request that includes both fields is rejected.

PATCH

customers

{customerId}

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerType": "INDIVIDUAL",
  "fullName": "John Smith",
  "birthDate": "1985-06-15",
  "currencies": [
    "USD",
    "EUR",
    "USDC"
  ],
  "address": {
    "line1": "456 Market St",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101",
    "country": "US"
  }
}
'

{
  "status": "PROCESSING",
  "message": "This contact change is still being processed. Retry the same request in a moment."
}

Authorizations

Authorization

string

header

required

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

Headers

Grid-Wallet-Signature

string

Full API-key stamp built over the prior payloadToSign with the session API keypair of an active session on the Embedded Wallet whose sign-in contact is changing. Required on the signed retry of a sign-in contact change; ignored on the initial call and on customer updates that complete synchronously.

Request-Id

string

The requestId returned in a prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry of a sign-in contact change; must be paired with Grid-Wallet-Signature.

Path Parameters

customerId

string

required

System-generated unique customer identifier

Body

application/json

Individual Customer Update Request
Business Customer Update 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"

currencies

string[]

Updated list of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Replaces the existing list. Some currency combinations may require separate customers — if so, the request will be rejected with details.

Example:

["USD", "EUR", "USDC"]

string<email>

Email address for the customer. If the customer's Embedded Wallet signs in with an EMAIL_OTP credential, the new address must first be registered and verified as a replacement credential, and the change is sent on its own. A business administrator's credentials are not changed.

Maximum string length: 255

Example:

"john.doe@example.com"

phoneNumber

string

Phone number for the customer in strict E.164 format. If the customer's Embedded Wallet signs in with an SMS_OTP credential, the new number must first be registered and verified as a replacement credential, and the change is sent on its own. Send phone number and email updates as separate PATCH calls.

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

Example:

"+14155551234"

umaAddress

string

Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer.

Example:

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

Deprecated; send agreementConsents instead. Supplying this records acceptance of the Lightspark End User Terms, equivalent to a single agreementConsents entry of type LIGHTSPARK_END_USER_TERMS. Supplying both fields in one request is rejected.

Show child attributes

agreementConsents

object[]

Evidence that the customer accepted Grid agreements, at most one entry per type. Supplying this records additional acceptances; it never withdraws or replaces evidence already recorded for other types. Omitting the field leaves recorded consents unchanged.

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

Maximum string length: 250

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

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: an SSN (format ###-##-####) or ITIN, or a non-US tax ID (idType NON_US_TAX_ID) with its non-US countryOfIssuance. US residents must provide an SSN or ITIN. Write-only — never returned in customer responses.

Maximum string length: 100

Example:

"123-45-6789"

countryOfIssuance

string

Country that issued the identification (ISO 3166-1 alpha-2). For an SSN or ITIN this is optional, defaults to US, and is rejected if set to anything else. For a NON_US_TAX_ID, set it to the issuing non-US country; US is rejected.

Example:

"US"

sourceOfFundsCategories

enum<string>[]

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

Minimum array length: 1

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.

Maximum string length: 500

Example:

"Contest winnings"

sourceOfWealthCategories

enum<string>[]

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

Minimum array length: 1

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.

Maximum string length: 500

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.

Maximum string length: 500

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"

Response

Customer updated successfully. For a sign-in contact change, this is returned only on the signed retry: the updated customer once the change has landed, or a WalletOperationProcessing body with status: "PROCESSING" while it is still being applied. Re-send the identical signed request until it returns the customer.

Individual Customer
Business Customer
Wallet Operation Processing

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

System-generated unique identifier

Example:

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

Deprecated; read agreementConsents instead. Mirrors the customer's LIGHTSPARK_END_USER_TERMS acceptance when one is on file, and is omitted otherwise.

Show child attributes

agreementConsents

object[]

read-only

The customer's recorded agreement acceptances, one entry per accepted type holding that type's most recent acceptance. Omitted when the customer has not accepted any agreement yet.

Show child attributes

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>

Creation timestamp

Example:

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

updatedAt

string<date-time>

Last update timestamp

Example:

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

isDeleted

boolean

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

Maximum string length: 250

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

idType

enum<string>

Type of tax identification

Available options:

SSN,

ITIN,

EIN,

NON_US_TAX_ID

Example:

"SSN"

countryOfIssuance

string

Example:

"US"

sourceOfFundsCategories

enum<string>[]

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

Minimum array length: 1

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.

Maximum string length: 500

Example:

"Contest winnings"

sourceOfWealthCategories

enum<string>[]

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

Minimum array length: 1

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.

Maximum string length: 500

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.

Maximum string length: 500

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"

Using the API

API documentation

Update customer by ID

Authorizations

Headers

Path Parameters

Body

Response