# KYC review state change

Triggered when a KYC review state has changed.

{% admonition type="info" %}
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.
{% /admonition %}

* Event type: kyc-reviews#state-change
* Profile level subscriptions: Not Supported
* Application level subscriptions: Supported

See the Webhooks guide 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 to ensure the request is authentic and has not been tampered with.
    Example: "t7FMhk3OARMgwqz0LJXO..."

  - `X-Delivery-Id` (string)
    Unique identifier for this webhook delivery attempt.
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

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

## Request fields (application/json):

  - `body` (any) — one of (discriminator: schema_version):
    - 5.0.0:
      - `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/kyc-review-status.md) 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/kyc-review-status.md) 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.triggerReferences.triggerData` (object)
        Key-value Object containing metadata of the underlying product object that triggered the KYC review.
For QUOTE, TRANSFER and ADD_MONEY types, triggerData contains an id field that refers to their respective IDs.
For BANK_ACCOUNT_DETAILS, triggerData has a field called currencies that contains a list of currencies (ex: USD, SGD, EUR)
the bank details have been created for.

| triggerReference.type | Field       | Type           |
|-----------------------|-------------|----------------|
| QUOTE                 | id          | uuid           |
| TRANSFER              | id          | long           |
| ADD_MONEY             | id          | long           |
| BANK_ACCOUNT_DETAILS  | currencies  | list of string |

This ID might be null if underlying action is a process like REPAPERING.
        Example: {"id":"ba83s43a-f623-46f0-956d-196c13e2ab01"}
      - `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: same as `data.resource.requirements.state` in "5.0.0" (3 values)
      - `data.resource.requirements.additionalRequirements.reasons` (object)
        Contains information about the reason this additional requirement has been requested.
      - `data.resource.requirements.additionalRequirements.attributes` (object)
        Contains metadata information about the additional requirement. Not returned if empty.
      - `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"
    - 4.0.0:
      - `schema_version` (string)
        Version of the event schema. Determined by the schema_version on your [webhook subscription](/api-reference/webhook).
        Enum: "4.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/kyc-review-status.md) 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"
      - `data.resource.triggerReferences.triggerData` (object)
        Key-value Object containing metadata of the underlying product object that triggered the KYC Review.
For "QUOTE", "TRANSFER" and "ADD_MONEY" types, triggerData contains an "id" field that refers to their respective IDs.
For "BANK_ACCOUNT_DETAILS", triggerData has a field called "currencies" which contains a list of currencies (i.e USD, SGD, EUR) that
the bank details have been created for.

| triggerReference.type | field       | type           |
|-----------------------|-------------|----------------|
| QUOTE                 | id          | uuid           |
| TRANSFER              | id          | long           |
| ADD_MONEY             | id          | long           |
| BANK_ACCOUNT_DETAILS  | currencies  | list of string |

This ID might be null if underlying action is a process like REPAPERING.
        Example: {"id":"ba83s43a-f623-46f0-956d-196c13e2ab01"}
      - `data.resource.requirements` (array)
        Nested list of KYC requirement objects.
      - `data.resource.requirements.key` (string)
        The unique identifier of the KYC requirement.
        Example: "BUSINESS_USE_CASES"
      - `data.resource.requirements.state` (string)
        The status of the KYC requirement. Either

NOT_PROVIDED: requires information

IN_REVIEW: requires internal review of the requirement
        Example: "NOT_PROVIDED"
      - `data.resource.requirements.apiCollectionSupported` (boolean)
        A boolean value to indicate if the API collection is available for this evidence. To submit the evidence, refer to
[KYC Requirement Submit endpoint](/api-reference/kyc-review/kycreviewrequirementsubmit).
        Example: true
      - `data.resource.requirements.versions` (array)
        Available versions to be submitted for the requirement.
      - `data.resource.requirements.versions.version` (string)
        Available version identifier to be submitted for the requirement.
        Example: "V1"
      - `data.resource.requirements.versions.validUntil` (string)
        An optional field that indicates a valid until date.
    - 2.0.0:
      - `schema_version` (string)
        Version of the event schema. Determined by the schema_version on your [webhook subscription](/api-reference/webhook).
        Enum: "2.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:42Z"
      - `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/kyc-review-status.md) 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.257725"
      - `data.resource.createdAt` (string)
        Timestamp marking the creation of the KYC Review.
        Example: "2024-09-03T16:22:02.257725"
      - `data.resource.updatedAt` (string)
        Timestamp marking the last update of the KYC Review.
        Example: "2024-09-03T16:29:41.147522"
      - `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: same as `data.resource.triggerReferences.type` in "4.0.0" (6 values)
      - `data.resource.triggerReferences.triggerData` (object)
        Key-value Object containing metadata of the underlying product object that triggered the KYC Review.
For "QUOTE", "TRANSFER" and "ADD_MONEY" types, triggerData contains an "id" field that refers to their respective IDs.
For "BANK_ACCOUNT_DETAILS", triggerData has a field called "currencies" which contains a list of currencies (i.e USD, SGD, EUR) that
the bank details have been created for.

| triggerReference.type | field       | type           |
|-----------------------|-------------|----------------|
| QUOTE                 | id          | uuid           |
| TRANSFER              | id          | long           |
| ADD_MONEY             | id          | long           |
| BANK_ACCOUNT_DETAILS  | currencies  | list of string |

This ID might be null if underlying action is a process like REPAPERING.
        Example: {"id":"ba83s43a-f623-46f0-956d-196c13e2ab01"}
      - `data.resource.requirements` (array)
        Nested list of KYC requirement objects.
      - `data.resource.requirements.key` (string)
        The unique identifier of the KYC requirement.
        Example: "BUSINESS_USE_CASES"
      - `data.resource.requirements.state` (string)
        The status of the KYC requirement. Either

NOT_PROVIDED: requires information

IN_REVIEW: requires internal review of the requirement
        Example: "NOT_PROVIDED"
      - `data.resource.requirements.apiCollectionSupported` (boolean)
        A boolean value to indicate if the API collection is available for this evidence. To submit the evidence, refer to
[KYC Requirement Submit endpoint](/api-reference/kyc-review/kycreviewrequirementsubmit).
        Example: true
      - `data.resource.requirements.versions` (array)
        Available versions to be submitted for the requirement.
      - `data.resource.requirements.versions.version` (string)
        Available version identifier to be submitted for the requirement.
        Example: "V1"
      - `data.resource.requirements.versions.validUntil` (string)
        An optional field that indicates a valid until date.

## Response 200 fields (application/json):

  - `status` (string)
    Example: "ok"