---
title: "Customer status change"
method: POST
path: "customer-update"
tags: ["Webhooks"]
---

# Customer status change

`POST customer-update` (webhook)

Webhook that is called when the status of a customer is updated, including KYC and KYB status changes.
This endpoint should be implemented by clients of the Grid API.

### Authentication
The webhook includes a signature in the `X-Grid-Signature` header that allows you to verify that the webhook was sent by Grid.
To verify the signature:
1. Get the Grid API public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash

If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.

## Payload

- CustomerWebhook
  - `id` string, required — Unique identifier for this webhook delivery (can be used for idempotency)
  - `type` 'CUSTOMER.KYC_APPROVED' | 'CUSTOMER.KYC_REJECTED' | 'CUSTOMER.KYC_PENDING' | 'CUSTOMER.KYB_APPROVED' | 'CUSTOMER.KYB_REJECTED' | 'CUSTOMER.KYB_PENDING', required — Type of webhook event in OBJECT.EVENT dot-notation. The part before the dot identifies the resource, the part after identifies the event. This lets consumers route purely on type without inspecting data.status.
  - `timestamp` string, date-time, required — ISO 8601 timestamp of when the webhook was sent
  - `data` union, required
    - 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

## Acknowledgement `200`

Webhook received successfully

## Other responses

- `400` — Bad request
- `401` — Unauthorized - Signature validation failed
- `409` — Conflict - Webhook has already been processed (duplicate id)

---

[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/151f2d9bad9c/schema)