---
title: "Update customer by ID"
method: PATCH
path: "/customers/{customerId}"
tags: ["Customers"]
---

# Update customer by ID

`PATCH /customers/{customerId}`

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, or changes `phoneNumber` for a customer that has one or more tied Embedded Wallet internal accounts with `SMS_OTP` credentials, the contact update 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 contact field and every tied matching OTP credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer contact field is not changed.

Update `email` and `phoneNumber` in separate PATCH calls. A request that includes both fields is rejected.

For an Embedded Wallet email or SMS auth phone 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 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.

## Headers

- `Grid-Wallet-Signature` string
- `Request-Id` string

## Request body

- union
  - IndividualCustomerUpdateRequest — 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` 'INDIVIDUAL', required — Whether the customer is an individual or a business entity
    - `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.
    - `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.
    - `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.
    - `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.
    - `endUserTermsConsent` EndUserTermsConsentRequest
      - `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 the End User Terms.
    - `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)
    - `taxIdType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID' — Type of tax identification
    - `taxIdentifier` string — Tax-identification number. For US persons this is the SSN (format `###-##-####`) or ITIN. For non-US persons this is the tax number issued by `taxIdCountryOfIssuance`.
    - `taxIdCountryOfIssuance` string — Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when `taxIdType` is `NON_US_TAX_ID`.
    - `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.
  - BusinessCustomerUpdateRequest — 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 through the endpoint's signed-retry flow. When `phoneNumber` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer phone number and every tied `SMS_OTP` credential through the same signed-retry flow. Update `email` and `phoneNumber` in separate PATCH calls.
    - `customerType` 'BUSINESS', required — Whether the customer is an individual or a business entity
    - `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.
    - `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.
    - `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.
    - `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.
    - `endUserTermsConsent` EndUserTermsConsentRequest
      - `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 the End User Terms.
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD' — The current KYB status of a business customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information.
    - `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)
    - `businessInfo` BusinessInfoUpdate — Additional information for business entities
      - `legalName` string — Legal name of the business
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'PUBLICLY_LISTED_COMPANY' | 'TRUST' | 'PRIVATE_FOUNDATION' | 'CHARITY' | 'OTHER' — Legal entity type of the business
      - `taxId` string — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `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
      - `sourceOfFunds` string — The primary source of funds for the business
      - `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
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
      - `naicsCode` string — NAICS code describing the nature of the business (2-6 digits)
      - `sourceOfFundsCategories` SourceOfFundsCategory[] — Structured source-of-funds categories for the business
      - `sourceOfFundsOtherDescription` string — Description of the source of funds when OTHER is selected
      - `purposeOfAccountOtherDescription` string — Description of the account purpose when OTHER is selected
      - `expectedCounterpartyCountries` string[] — List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2)
      - `primaryContactFirstName` string — First name of the business's primary contact — a registered director or authorised representative of the business. Required in regions where a named individual is verified against the business during onboarding (e.g. the EU). The customer's `email` and `phoneNumber` are this person's contact details.
      - `primaryContactLastName` string — Last name of the business's primary contact.

## Response `200`

Customer updated successfully. For Embedded Wallet email or SMS auth phone updates, this is returned only on the signed retry after the customer contact field and all tied matching OTP credentials have been updated.

- union
  - 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
      - `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 the End User Terms.
    - `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)
    - `taxIdType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID' — Type of tax identification
    - `taxIdentifier` string — Tax-identification number. For US persons this is the SSN (format `###-##-####`) or ITIN. For non-US persons this is the tax number issued by `taxIdCountryOfIssuance`.
    - `taxIdCountryOfIssuance` string — Country that issued the tax identifier (ISO 3166-1 alpha-2). Required when `taxIdType` is `NON_US_TAX_ID`.
    - `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.
  - BusinessCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `customerType` 'BUSINESS', required — Whether the customer is an individual or a business entity
    - `endUserTermsConsent` EndUserTermsConsent
      - `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 the End User Terms.
    - `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.
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD' — The current KYB status of a business customer. `HOLD` means the customer is placed on hold and may be required to update or provide more information.
    - `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)
    - `businessInfo` object — Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, so both are optional in responses.
      - `legalName` string, required — Legal name of the business
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'PUBLICLY_LISTED_COMPANY' | 'TRUST' | 'PRIVATE_FOUNDATION' | 'CHARITY' | 'OTHER' — Legal entity type of the business
      - `taxId` string — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `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
      - `sourceOfFunds` string — The primary source of funds for the business
      - `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
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
      - `naicsCode` string — NAICS code describing the nature of the business (2-6 digits)
      - `sourceOfFundsCategories` SourceOfFundsCategory[] — Structured source-of-funds categories for the business
      - `sourceOfFundsOtherDescription` string — Description of the source of funds when OTHER is selected
      - `purposeOfAccountOtherDescription` string — Description of the account purpose when OTHER is selected
      - `expectedCounterpartyCountries` string[] — List of countries of the business's expected transaction counterparties (ISO 3166-1 alpha-2)
      - `primaryContactFirstName` string — First name of the business's primary contact — a registered director or authorised representative of the business. Required in regions where a named individual is verified against the business during onboarding (e.g. the EU). The customer's `email` and `phoneNumber` are this person's contact details.
      - `primaryContactLastName` string — Last name of the business's primary contact.
    - `beneficialOwners` BeneficialOwner[]
      - `id` string, required — Unique identifier for this beneficial owner
      - `customerId` string, required — The ID of the business customer this beneficial owner is associated with
      - `roles` BeneficialOwnerRole[], required — Roles of this person within the business
      - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100)
      - `personalInfo` BeneficialOwnerPersonalInfo, required
        - `firstName` string, required — First name of the individual
        - `middleName` string — Middle name of the individual
        - `lastName` string, required — Last name of the individual
        - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
        - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2)
        - `email` string, email — Email address of the individual
        - `phoneNumber` string — Phone number in E.164 format
        - `address` Address, required
          - `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', required — Type of tax identification
        - `identifier` string, required — The identification number or value
        - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)
      - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' | 'HOLD', required — 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.
      - `createdAt` string, date-time, required — When this beneficial owner was created
      - `updatedAt` string, date-time — When this beneficial owner was last updated

## Other responses

- `202` — Challenge issued for an Embedded Wallet email or SMS auth phone update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`.
- `400` — Bad request
- `401` — Unauthorized. Also returned for Embedded Wallet email or SMS auth phone update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call.
- `404` — Customer not found
- `409` — Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential, or the supplied phone number is already associated with an `SMS_OTP` credential, on this or another internal account, or when the tied Embedded Wallet OTP credential set changed between the initial `202` challenge and the signed retry.
- `424` — Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet OTP credentials. The customer contact field is not changed unless all tied credentials are updated successfully.
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/versions/526036c12609/schema)