# KYC review state change

Triggered when a KYC review state has changed.
In previous versions, this event fired only when the overall KYC review state changed. In **v5.0.0**, it fires on every requirement or additional requirement state change, which may result in receiving more events. See `data.resource.prevState` and `data.resource.requirementChanges` for details on what changed.
* Event type: `kyc-reviews#state-change`
* Profile level subscriptions: Not Supported
* Application level subscriptions: Supported

See the [Webhooks guide](/guides/developer/webhooks) for setup instructions, signature verification, and best practices.

Endpoint: POST kyc-reviews#state-change

## Header parameters:

  - `X-Signature-SHA256` (string)
    RSA-SHA256 signature of the request body, Base64 encoded. Verify this against the [Wise public key](/guides/developer/webhooks/event-handling#requests) to ensure the request is authentic and has not been tampered with.

  - `X-Delivery-Id` (string)
    Unique identifier for this webhook delivery attempt.

  - `X-Test-Notification` (boolean)
    Present with the value `true` if this is a test notification sent to verify your callback URL during subscription setup.

## Request fields (application/json):

  - `schema_version` (string)
    Version of the event schema. Determined by the `schema_version` on your [webhook subscription](/api-reference/webhook).
    Enum: "5.0.0"

  - `subscription_id` (string)
    ID of the webhook subscription that triggered this event.
    Example: 8df95817-8085-40aa-9bda-e3bf46e7a21a

  - `event_type` (string)
    Event type identifier
    Example: kyc-reviews#state-change

  - `sent_at` (string)
    Timestamp when the event was sent.
    Example: 2024-09-03T16:29:42.123Z

  - `data` (object)

  - `data.resource` (object)

  - `data.resource.id` (string)
    ID of the KYC Review.
    Example: 46e1a5c4-4a9b-4563-39d3-18174d3ac0f8

  - `data.resource.state` (string)
    Status of the KYC Review. See [KYC review status](/guides/product/kyc/wise-kyc/hosted-kyc) for possible values.
    Example: WAITING_CUSTOMER_INPUT

  - `data.resource.prevState` (string)
    Previous status of the KYC review. See [KYC review status](/guides/product/kyc/wise-kyc/hosted-kyc) for possible values.
    Example: WAITING_CUSTOMER_INPUT

  - `data.resource.profileId` (integer)
    ID of the profile KYC review belongs to.
    Example: 22016766

  - `data.resource.requiredBy` (string)
    Timestamp by which the underlying requirement set needs to be verified to not block the customer.
Only relevant if the status is `PASSED_WITH_REQUIREMENTS`.
    Example: 2024-09-03T16:22:02.258Z

  - `data.resource.createdAt` (string)
    Timestamp marking the creation of the KYC review.
    Example: 2024-09-03T16:22:02.258Z

  - `data.resource.updatedAt` (string)
    Timestamp marking the last update of the KYC review.
    Example: 2024-09-03T16:29:41.148Z

  - `data.resource.triggerReferences` (array)
    List of trigger references for this KYC review.

  - `data.resource.triggerReferences.type` (string)
    Type of the underlying action/process this KYC review is for. Usually a reference to which product
this KYC review is for (like `QUOTE` or `TRANSFER`) or a reference to a KYC process on the profile
that isn't related to a specific product (like `REFRESH_CYCLE` or `REPAPERING`).
    Enum: "QUOTE", "TRANSFER", "PROACTIVE_SEND_MONEY", "ADD_MONEY", "CARD", "BANK_ACCOUNT_DETAILS", "INFO_REQUEST"

  - `data.resource.requirements` (array)
    Nested list of [KYC requirement](/api-reference/kyc-review/kyc-requirement) objects in `[[Requirement]]` format, where each inner list represents a combination of possible requirements to be provided. To fulfil the whole KYC review, at least one item from each inner list should be provided.
For example, if the requirements are `[[a, b], [c, d]]` then it should be read as `(a or b) and (c or d)`.
Please refer to the [KYC requirement](/api-reference/kyc-review/kyc-requirement) documentation for full examples of the schema.

  - `data.resource.requirements.key` (string)
    The name of the KYC requirement. A single KYC Requirement should appear in the requirements list at most once.
    Example: ID_DOCUMENT

  - `data.resource.requirements.state` (string)
    The state of the KYC requirement.
- `NOT_PROVIDED` — the information is pending. Either the Hosted KYC flow or [KYC Requirement Submit](/api-reference/kyc-review/kycreviewrequirementsubmit) endpoint should be used to fulfil the requirement.
- `IN_REVIEW` — the required information has been retrieved and the KYC requirement is being reviewed. No action is needed.
- `VERIFIED` — the required information has been received and verified on our side. No action is needed.
    Enum: "NOT_PROVIDED", "IN_REVIEW", "VERIFIED"

  - `data.resource.requirements.apiCollectionSupported` (boolean)
    Indicates if the requirement can be provided via the [KYC Requirement Submit](/api-reference/kyc-review/kycreviewrequirementsubmit) endpoint. If `false`, the requirement should be provided via the Hosted KYC flow.
    Example: true

  - `data.resource.requirements.additionalRequirements` (array | null)
    List of additional submissions that are needed to fulfill this requirement. These can appear when the originally submitted evidence is a wrong document, wrong format, incomplete or otherwise insufficient. Only provided if not empty.

  - `data.resource.requirements.additionalRequirements.additionalRequirementId` (string)
    Unique identifier for an additional requirement, generated by Wise.
    Example: 8b789c45-60ae-475d-b667-c8714db9a6a4

  - `data.resource.requirements.additionalRequirements.key` (string)
    A key outlining what type of evidence is additionally required
    Enum: "ACKNOWLEDGEMENT,", "DOCUMENT", "WRITTEN_ANSWER", "DOCUMENT_AND_WRITTEN_ANSWER", "DOCUMENT_OR_WRITTEN_ANSWER", "EMAIL", "CUSTOM_REQUEST"

  - `data.resource.requirements.additionalRequirements.state` (string)
    The state of the additional requirement. This state should be treated as independent of the parent KYC Requirement's state. They can, but don't have to, change together.
- `NOT_PROVIDED` — the information is pending. Either the Hosted KYC flow or [KYC Requirement Submit](/api-reference/kyc-review/kycreviewrequirementsubmit) endpoint should be used to fulfil the additional requirement.
- `IN_REVIEW` — the required information has been retrieved and the additional requirement is being reviewed. No action is needed.
- `VERIFIED` — the required information has been received and verified on our side. No action is needed.
    Enum: "NOT_PROVIDED", "IN_REVIEW", "VERIFIED"

  - `data.resource.requirements.additionalRequirements.reasons` (object)
    Contains information about the reason this additional requirement has been requested.

  - `data.resource.requirements.additionalRequirements.reasons.errorCode` (string)
    Code for the reason this additional requirement has been requested.
    Enum: "NEEDED", "WRONG_DOCUMENT", "EXPIRED", "INVALID_TRADING_ADDRESS", "MISSING_ONE_SIDE", "MISSING_COUNTRY_OF_RESIDENCE", "MISSING_DIRECTORS", "MISSING_UBOS", "NO_UBO_DOC_REQUIRED", "MISMATCH_NAME", "MISMATCH_DATE_OF_BIRTH", "AGENT_DETAILS_PROVIDED", "DIRECTOR_IS_BUSINESS", "UBO_IS_BUSINESS", "UNCLEAR", "WEBSITE_LINK_BROKEN", "BUSINESS_NAME_NOT_ON_WEBSITE", "DRIVING_LICENSE_NOT_ACCEPTED", "BUSINESS_NOT_REGISTERED", "OTHER"

  - `data.resource.requirements.additionalRequirements.reasons.description` (string)
    Example: The provided document or information has expired. A valid document is required.

  - `data.resource.requirements.additionalRequirements.reasons.dateTime` (string)
    Timestamp marking when this additional requirement was requested.
    Example: 2026-04-13T10:54:21.929314

  - `data.resource.requirements.additionalRequirements.attributes` (object)
    Contains metadata information about the additional requirement. Not returned if empty.

  - `data.resource.requirements.additionalRequirements.attributes.fields` (object)
    Not returned if empty

  - `data.resource.requirements.additionalRequirements.attributes.fields.name` (string)
    The name of the affected person(s) or business

  - `data.resource.requirements.additionalRequirements.attributes.fields.website` (string)
    The URL of the affected website

  - `data.resource.requirements.additionalRequirements.attributes.fields.businessName` (string)
    The name of the affected business

  - `data.resource.requirements.additionalRequirements.attributes.fields.owningBusinessName` (string)
    The name of the affected owning business

  - `data.resource.requirements.additionalRequirements.attributes.fields.markdownText` (string)
    Free format text written by a Wise Agent in markdown format.
    Example: Requirement details were unclear, *please* provide a clear scan where:

*   All information is clearly readable
*   The document is in colour

  - `data.resource.requirements.additionalRequirements.attributes.issues` (array)
    A list of issues with the previously uploaded document. Not returned if empty
    Example: ["CANNOT_BE_SCREENSHOT","NEED_COLOUR_VERSION"]

  - `data.resource.requirements.versions` (array)
    **Conditional:** Only present when `apiCollectionSupported` is `true`. Lists the available versions and their validity.

  - `data.resource.requirements.versions.version` (string)
    The version identifier.
    Example: v1

  - `data.resource.requirements.versions.validUntil` (string | null)
    If present, indicates the expiry date of this version (ISO 8601).
    Example: 2026-06-30

  - `data.resource.requirements.attributes` (object | null)
    **Conditional:** Only present for certain requirement types that provide additional contextual information. The keys within this object vary depending on the parent requirement `key`. See the [KYC requirement types](/guides/product/kyc/wise-kyc/kyc-requirement-types) guide for details on which requirement types support attributes and what keys they contain.

  - `data.resource.requirementChanges` (array)
    List of requirement changes that triggered this event.

  - `data.resource.requirementChanges.key` (string)
    The [key](/api-reference/kyc-review/kyc-requirement#path=key) of the requirement that has changed.
    Example: ID_DOCUMENT

  - `data.resource.requirementChanges.newState` (string)
    The new [state](/api-reference/kyc-review/kyc-requirement#path=state) of the requirement that has changed.
    Example: IN_REVIEW

  - `data.resource.requirementChanges.prevState` (string)
    *Not provided when requirement is new.*
The previous [state](/api-reference/kyc-review/kyc-requirement#path=state) of the requirement that has changed. In case only an [additional requirement](/api-reference/kyc-review/kyc-requirement#path=additionalRequirements) has changed, this state can be equal to `newState`.
    Example: NOT_PROVIDED

  - `data.resource.requirementChanges.additionalRequirements` (array)
    A list of additional requirements that have changed. Not shown if empty.

  - `data.resource.requirementChanges.additionalRequirements.additionalRequirementId` (string)
    The [UUID](/api-reference/kyc-review/kyc-requirement#path=additionalRequirements/additionalRequirementId) of the additional requirement that has changed.
    Example: 8b789c45-60ae-475d-b667-c8714db9a6a4

  - `data.resource.requirementChanges.additionalRequirements.newState` (string)
    The new [state](/api-reference/kyc-review/kyc-requirement#path=additionalRequirements/state) of the additional requirement that has changed.
    Example: IN_REVIEW

  - `data.resource.requirementChanges.additionalRequirements.prevState` (string)
    *Not provided when additional requirement is new.*
The previous [state](/api-reference/kyc-review/kyc-requirement#path=additionalRequirements/state) of the additional requirement that has changed.
    Example: NOT_PROVIDED

  - `subscription_id` (string)
    ID of the webhook subscription that triggered this event
    Example: 8df95817-8085-40aa-9bda-e3bf46e7a21a

  - `sent_at` (string)
    Timestamp when the event was sent
    Example: 2024-09-03T16:29:42.123Z

## Response 200 fields (application/json):

  - `status` (string)
    Example: ok