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. If the request changes email for a customer that has one or more tied Embedded Wallet internal accounts with EMAIL_OTP credentials, or changes phoneNumber for a customer that has one or more tied Embedded Wallet internal accounts with SMS_OTP credentials, the contact update uses the two-step signed-retry flow so the customer’s wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer contact field and every tied matching OTP credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer contact field is not changed.

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

For an Embedded Wallet email or SMS auth phone update:

1. Call PATCH /customers/{customerId} with the full update body and no signature headers. Grid returns 202 with payloadToSign, requestId, and expiresAt. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet OTP credentials that must be updated.

2. Use the session API keypair of a verified authentication credential on one of the customer’s tied Embedded Wallets to build an API-key stamp over payloadToSign, then 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 retry body must carry the same update fields submitted in step 1. The signed retry returns 200 with the updated customer.

PATCH /customers/{customerId}

cURL

cURL

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"
  }
}
'

200

Example

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$[e-mail]",
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "[e-mail]",
  "phoneNumber": "[phone]",
  "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"
}

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 a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for Embedded Wallet email or SMS auth phone updates; 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 for Embedded Wallet email or SMS auth phone updates; 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"]

email · string<email>

Email address for the customer. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied EMAIL_OTP credential across all tied Embedded Wallets.

Example:

"[e-mail]"

phoneNumber · string

Phone number for the customer in strict E.164 format. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied SMS_OTP credential across all tied Embedded Wallets. Send phone number and email updates as separate PATCH calls.

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

Example:

"[phone]"

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:

"$[e-mail]"

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"

Response

200

application/json

Customer updated successfully. For Embedded Wallet email or SMS auth phone updates, this is returned only on the signed retry after the customer contact field and all tied matching OTP credentials have been updated.

Individual Customer

Business Customer

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).

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

phoneNumber · string

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

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

Example:

"[phone]"

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>

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"