--- title: "Update agent customer" method: PATCH path: "/agents/me/customer" tags: ["Agent Operations"] --- # Update agent customer `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 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. ## Request body - AgentCustomerUpdateRequest: 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`). - `fullName` string: Individual's full name - `birthDate` string, date: Date of birth in ISO 8601 format (YYYY-MM-DD) - `nationality` string: Country code (ISO 3166-1 alpha-2) - `address` Address - `line1` string, required: Street address line 1 - `line2` string: Street address line 2 - `city` string: City - `state` string: State/Province/Region - `postalCode` string, required: Postal/ZIP code - `country` string, required: Country code (ISO 3166-1 alpha-2) - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID': Type of tax identification - `identifier` string: 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. - `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. - `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. - `sourceOfFundsCategories` IndividualSourceOfFundsCategory[]: Structured source-of-funds categories (FLOW of funds for this account). - `sourceOfFundsOtherDescription` string: Free-form description of the customer's source of funds. Required when `sourceOfFundsCategories` includes `OTHER`; otherwise omitted. - `sourceOfWealthCategories` SourceOfWealthCategory[]: Structured source-of-wealth categories (STOCK — origin of accumulated wealth). - `sourceOfWealthOtherDescription` string: 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 - `purposeOfAccountOtherDescription` string: 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. ## Response `200` Customer updated successfully - IndividualCustomer: 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`). - `id` string: System-generated unique identifier - `platformCustomerId` string, required: Platform-specific customer identifier - `customerType` 'INDIVIDUAL', required: Whether the customer is an individual or a business entity - `endUserTermsConsent` EndUserTermsConsent: Deprecated; use `agreementConsents` instead, which records acceptance of each agreement separately. Reported only for a customer whose acceptance predates that field, and always as the `LIGHTSPARK_END_USER_TERMS` agreement. - `acceptedAt` string, date-time, required: Date and time when the customer accepted the End User Terms. - `ipAddress` string, required: IP address of the device the customer used when accepting the terms. - `termsVersion` string, required: Version identifier of the accepted Grid End User Terms. - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement. - `agreementConsents` AgreementConsent[]: 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. - `type` 'LIGHTSPARK_END_USER_TERMS' | 'LIGHTSPARK_E_SIGN_CONSENT' | 'LIGHTSPARK_PRIVACY_POLICY' | 'LEAD_E_SIGN_CONSENT' | 'LEAD_ACCOUNTHOLDER_CONSUMER_AGREEMENT' | 'LEAD_ACCOUNTHOLDER_COMMERCIAL_AGREEMENT' | 'LEAD_PRIVACY_POLICY' | 'LEAD_CARDHOLDER_CONSUMER_AGREEMENT' | 'LEAD_CARDHOLDER_COMMERCIAL_AGREEMENT', required: Identifies which Grid agreement a consent record or document refers to. Values are stable identifiers: a document's hosted URL or version may change, but its type does not. Accepting one agreement never implies acceptance of another, even when two agreements share a hosted page. The cardholder and accountholder agreements differ by customer kind: an `INDIVIDUAL` customer accepts the `_CONSUMER_` variant, and a `BUSINESS` customer accepts the `_COMMERCIAL_` one. - `acceptedAt` string, date-time, required: Date and time when the customer accepted this agreement. Must include a timezone offset and must not be in the future. - `ipAddress` string, required: IP address of the device the customer used when accepting this agreement. - `termsVersion` string, required: Version identifier of the accepted agreement, as returned for this type by the agreement documents endpoint. A version is scoped to its type; a version valid for one agreement is not valid for another. - `acceptanceMethod` 'CHECKBOX' | 'CLICK_TO_ACCEPT', required: Method the customer used to affirmatively accept an agreement. - `region` string: Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction. - `currencies` string[]: List of currency codes enabled for this customer. - `email` string, email: Email address for the customer. - `phoneNumber` string: Phone number for the customer in strict E.164 format. - `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. - `createdAt` string, date-time: Creation timestamp - `updatedAt` string, date-time: Last update timestamp - `isDeleted` boolean: Whether the customer is marked as deleted - `contactVerification` ContactVerification: Email and/or phone verification state for the customer. This object is **only present when the customer's regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed. Each channel is reported independently: only the channels the customer's provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes). - `email` 'PENDING' | 'VERIFIED': Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `phone` 'PENDING' | 'VERIFIED': Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed. - `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. - `fullName` string: Individual's full name - `birthDate` string, date: Date of birth in ISO 8601 format (YYYY-MM-DD) - `nationality` string: Country code (ISO 3166-1 alpha-2) - `address` Address - `line1` string, required: Street address line 1 - `line2` string: Street address line 2 - `city` string: City - `state` string: State/Province/Region - `postalCode` string, required: Postal/ZIP code - `country` string, required: Country code (ISO 3166-1 alpha-2) - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID': Type of tax identification - `identifier` string: 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. - `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. - `sourceOfFundsCategories` IndividualSourceOfFundsCategory[]: Structured source-of-funds categories (FLOW of funds for this account). - `sourceOfFundsOtherDescription` string: Free-form description of the customer's source of funds. Required when `sourceOfFundsCategories` includes `OTHER`; otherwise omitted. - `sourceOfWealthCategories` SourceOfWealthCategory[]: Structured source-of-wealth categories (STOCK — origin of accumulated wealth). - `sourceOfWealthOtherDescription` string: 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 - `purposeOfAccountOtherDescription` string: 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. ## Other responses - `400`: Bad request - an invalid value, a field agents may not update, or an identity that cannot change while the customer's KYC status is under review - `401`: Unauthorized - `403`: Forbidden - Agents API is not enabled for the platform or the agent does not have the MANAGE_IDENTITY permission - `500`: Internal service error ## Changes > 115 revisions in range; 2 not diffed. - **2026-10-28** `d996ddfb9d2b`: 5 info - added the optional property `details/missingFields` to the response with the `400` status - added the optional property `details/permission` to the response with the `403` status - added the optional property `details/policyDenialReason` to the response with the `403` status - added the optional property `details/refusalReason` to the response with the `400` status - …1 more - **2026-10-28** `5abf2bb56bcb`: 1 warning - added the new `CORRIDOR_UNDER_MAINTENANCE` enum value to the `code` response property for the response status `403` - **2026-10-24** `715332dcb111`: 1 warning - added the new `EXACT_AMOUNT_UNAVAILABLE` enum value to the `code` response property for the response status `400` - **2026-10-23** `e0ea32e050ba`: 1 info - added the new optional request property `allOf[subschema #1]/phoneNumber` - **2026-10-20** `761d1d030cb5`: 1 warning - added the new `CARDHOLDER_AGREEMENT_NOT_ACCEPTED` enum value to the `code` response property for the response status `400` [Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/agents/me/customer/patch.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)