Skip to main content
PATCH
Update agent customer

Authorizations

​
Authorization
string
header
required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Body

application/json

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:
​
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.

Maximum string length: 255
Example:

"john.doe@example.com"

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

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

​
endUserTermsConsent
object
deprecated

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.

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

​
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
​
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 identification number, required to onboard them as a US account holder. Only SSN (format ###-##-####) and ITIN are currently accepted; other identification types are rejected. 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). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to US and is rejected if set to anything else.

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

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:

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

​
id
string

System-generated unique identifier

Example:

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

​
endUserTermsConsent
object
deprecated

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

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

​
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:
​
email
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.

​
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
​
idType
enum<string>

Type of tax identification

Available options:
SSN,
ITIN,
EIN,
NON_US_TAX_ID
Example:

"SSN"

​
countryOfIssuance
string

Country that issued the identification (ISO 3166-1 alpha-2). Optional for an individual account holder: SSN and ITIN are US-issued, so this defaults to US and is rejected if set to anything else.

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:
​
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:
​
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"