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, the email change 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 email and every tied EMAIL_OTP credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer email is not changed.

For an Embedded Wallet email 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 email 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": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US"
  }
}
'

200

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

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

Request body for PATCH /customers/{customerId}. When email changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied EMAIL_OTP credential across all tied Embedded Wallets through the endpoint's signed-retry flow.

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

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

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

200

application/json

Customer updated successfully. For Embedded Wallet email updates, this is returned only on the signed retry after the customer email and all tied email OTP credentials have been updated.

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