Update agent customer

Update identity information for the individual customer associated with the authenticated agent. Requires the MANAGE_IDENTITY permission in the agent’s policy. The customer is inferred from the agent and cannot be selected by the request. Agents may update only identity fields: fullName, birthDate, nationality, address, idType, identifier, countryOfIssuance and the enhanced-due-diligence fields, plus a phoneNumber when the customer has none on file. Any other field, including email and a change to a phone number on file (sign-in credentials the customer changes through PATCH /customers/{customerId}), returns 400.

PATCH /agents/me/customer

Update agent customer

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "idType": "SSN",
  "identifier": "123-45-6789",
  "countryOfIssuance": "US",
  "phoneNumber": "[phone]",
  "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"
}
'

200

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "umaAddress": "$[e-mail]",
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "endUserTermsConsent": {
    "acceptedAt": "2023-11-07T05:31:56Z",
    "ipAddress": "198.51.100.24",
    "termsVersion": "V1",
    "acceptanceMethod": "CHECKBOX"
  },
  "agreementConsents": [
    {
      "type": "LIGHTSPARK_END_USER_TERMS",
      "acceptedAt": "2023-11-07T05:31:56Z",
      "ipAddress": "198.51.100.24",
      "termsVersion": "2025-10-13",
      "acceptanceMethod": "CHECKBOX"
    }
  ],
  "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"
  },
  "idType": "SSN",
  "countryOfIssuance": "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

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

Request body for PATCH /agents/me/customer: the identity fields an agent may update on its customer. Any other field, including email and currencies, returns 400.

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

phoneNumber · string

The customer's phone number in strict E.164 format. Like the other fields, accepted only while the customer's identity can still be edited, and only when no phone number is on file; repeating the number on file changes nothing, and changing it returns 400.

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

Example:

"[phone]"

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

200

application/json

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:

"$[e-mail]"

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.

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

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>

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

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"