LIlightsparkdev
Agent Operations

Update agent customer

Changed on

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

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/agents/me/customer
  • Auth
    HTTP bearer

Request body

fullNamestring

Individual's full name

birthDatestring date

Date of birth in ISO 8601 format (YYYY-MM-DD)

nationalitystring

Country code (ISO 3166-1 alpha-2)

idType'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID'

Type of tax identification

identifierstring

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.

countryOfIssuancestring

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.

phoneNumberstring

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.

sourceOfFundsCategoriesIndividualSourceOfFundsCategory[]

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

sourceOfFundsOtherDescriptionstring

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

sourceOfWealthCategoriesSourceOfWealthCategory[]

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

sourceOfWealthOtherDescriptionstring

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

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

The intended purpose for using the Grid account

purposeOfAccountOtherDescriptionstring

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

expectedMonthlyTransactionCount'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000'

Expected number of transactions per month

expectedMonthlyTransactionVolume'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M'

Expected total transaction volume per month in USD equivalent

annualIncomeRange'UNDER_50K' | 'RANGE_50K_100K' | 'RANGE_100K_250K' | 'RANGE_250K_1M' | 'OVER_1M'

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

netWorthRange'UNDER_100K' | 'RANGE_100K_500K' | 'RANGE_500K_1M' | 'RANGE_1M_5M' | 'RANGE_5M_25M' | 'OVER_25M'

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

pepStatus'NONE' | 'DOMESTIC' | 'FOREIGN' | 'HIO' | 'FAMILY_OR_ASSOCIATE'

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.

Example request

{
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "idType": "SSN",
  "identifier": "123-45-6789",
  "countryOfIssuance": "US",
  "phoneNumber": "+14155551234",
  "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"
}

Response

Customer updated successfully

idstring

System-generated unique identifier

platformCustomerIdstring required

Platform-specific customer identifier

customerType'INDIVIDUAL' required

Whether the customer is an individual or a business entity

regionstring

Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.

currenciesstring[]

List of currency codes enabled for this customer.

emailstring email

Email address for the customer.

phoneNumberstring

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

umaAddressstring required

Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.

createdAtstring date-time

Creation timestamp

updatedAtstring date-time

Last update timestamp

isDeletedboolean

Whether the customer is marked as deleted

kycStatus'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD'

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.

fullNamestring

Individual's full name

birthDatestring date

Date of birth in ISO 8601 format (YYYY-MM-DD)

nationalitystring

Country code (ISO 3166-1 alpha-2)

idType'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID'

Type of tax identification

identifierstring

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.

countryOfIssuancestring

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.

sourceOfFundsCategoriesIndividualSourceOfFundsCategory[]

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

sourceOfFundsOtherDescriptionstring

Free-form description of the customer's source of funds. Required when sourceOfFundsCategories includes OTHER; otherwise omitted.

sourceOfWealthCategoriesSourceOfWealthCategory[]

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

sourceOfWealthOtherDescriptionstring

Free-form description of the customer's source of wealth. Required when sourceOfWealthCategories includes OTHER; otherwise omitted.

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

The intended purpose for using the Grid account

purposeOfAccountOtherDescriptionstring

Free-form description of the customer's intended purpose for the Grid account. Required when purposeOfAccount is OTHER; otherwise omitted.

expectedMonthlyTransactionCount'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000'

Expected number of transactions per month

expectedMonthlyTransactionVolume'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M'

Expected total transaction volume per month in USD equivalent

annualIncomeRange'UNDER_50K' | 'RANGE_50K_100K' | 'RANGE_100K_250K' | 'RANGE_250K_1M' | 'OVER_1M'

Bucketed annual income (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

netWorthRange'UNDER_100K' | 'RANGE_100K_500K' | 'RANGE_500K_1M' | 'RANGE_1M_5M' | 'RANGE_5M_25M' | 'OVER_25M'

Bucketed total net worth (USD equivalent). Used for enhanced due diligence on higher-risk profiles.

pepStatus'NONE' | 'DOMESTIC' | 'FOREIGN' | 'HIO' | 'FAMILY_OR_ASSOCIATE'

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.

Example response

{
  "id": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "endUserTermsConsent": {
    "ipAddress": "198.51.100.24",
    "termsVersion": "V1",
    "acceptanceMethod": "CHECKBOX"
  },
  "agreementConsents": [
    {
      "type": "LIGHTSPARK_END_USER_TERMS",
      "ipAddress": "198.51.100.24",
      "termsVersion": "2025-10-13",
      "acceptanceMethod": "CHECKBOX"
    }
  ],
  "region": "US",
  "currencies": [
    "USD",
    "USDC"
  ],
  "email": "john.doe@example.com",
  "phoneNumber": "+14155551234",
  "umaAddress": "$john.doe@uma.domain.com",
  "createdAt": "2025-07-21T17:32:28Z",
  "updatedAt": "2025-07-21T17:32:28Z",
  "contactVerification": {
    "email": "VERIFIED",
    "phone": "VERIFIED"
  },
  "kycStatus": "APPROVED",
  "fullName": "John Michael Doe",
  "birthDate": "1990-01-15",
  "nationality": "US",
  "address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "idType": "SSN",
  "identifier": "123-45-6789",
  "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"
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5abf2bb56bcbRevision changes
    • warning

      added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status