> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Categorisation Feedback

> Submit and retrieve feedback on Yapily's Categorisation results to help improve enrichment accuracy.

<Note>
  Yapily Data Plus is available as a BETA version.
</Note>

<Info>
  The Categorisation Feedback API is currently available in the following countries: UK, France, Germany, Austria, Ireland, Italy, Spain, Denmark, Finland, and Norway.
</Info>

## Background

Yapily's Categorisation Feedback API is a complementary Data Plus service that lets you flag issues with categorised transactions and track the status of that feedback over time. This closes the loop between the [Categorisation](/data/data-plus/categorisation) engine and your application, helping improve the accuracy of categorisation results over time.

* Report incorrect or missing fields on a categorised transaction
* Retrieve previously submitted feedback, either by Categorisation ID or by Feedback ID
* Track the review status of each piece of feedback you submit, and get notified when it changes

## How it works

<Steps>
  <Step title="Complete prerequisites">
    Before submitting feedback on a categorised transaction, you will first need to:

    1. Have a [Categorisation](/data/data-plus/categorisation) result, including the **Categorisation ID** and **Transaction Hash** you want to submit feedback for
    2. [Register a Webhook](/tools-and-services/webhooks/introduction) for notification events when a feedback's status changes

    ### Webhook Registration

    Please follow our [Webhook Registration Guide](/tools-and-services/webhooks/introduction) in order to register a webhook for your application.

    #### Webhook Event

    In order to get notified when a categorisation feedback request has changed status you will have to subscriber to the following webhook event:

    * **categorisation.feedback\_status.updated.v1** - is the event triggered when the status of a categorisation feedback is updated.
  </Step>

  <Step title="Submit feedback on a categorised transaction">
    ### Submitting feedback on a transaction

    Once you have a categorised transaction, you can submit feedback against it using its **Categorisation ID** and **Transaction Hash**.

    1. Call `POST /transactions/categorisation/{categorisationId}/feedback`
       * Provide the `transactionHash` of the transaction you're submitting feedback for
       * Provide one or more `suggestions`, each describing what's wrong with the categorisation
       * Optionally, provide free-form `notes` for anything the suggestions don't cover
       * See the [endpoint's API specification](/api-reference/data-plus/create-categorisation-feedback) for details

    **Suggestion fields**

    | Field            | Description                                                                                                                             |
    | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
    | `type`           | Whether the flagged field is `INCORRECT` or `MISSING`.                                                                                  |
    | `field`          | The categorisation field the suggestion relates to: `label`, `recurrence`, `payment processor`, `merchant name`, `logo`, or `location`. |
    | `suggestedValue` | Optional. When `type` is `INCORRECT`, the value you believe should have been returned instead.                                          |

    ```json theme={null}
    {
      "transactionHash": "...",
      "suggestions": [
        {
          "type": "MISSING",
          "field": "merchant name"
        },
        {
          "type": "INCORRECT",
          "field": "label",
          "suggestedValue": "Correct Label"
        }
      ],
      "notes": "Lorem ipsum..."
    }
    ```

    A successful submission returns the created feedback, with a `status` of `RECEIVED`:

    ```json theme={null}
    {
      "meta": {
        "tracingId": "12345678901234567890123456789012"
      },
      "data": {
        "id": "00000000-0000-0000-0000-000000000000",
        "transactionHash": "...",
        "suggestions": [
          {
            "type": "MISSING",
            "field": "merchant name"
          },
          {
            "type": "INCORRECT",
            "field": "label",
            "suggestedValue": "Correct Label"
          }
        ],
        "status": "RECEIVED",
        "createdAt": "2026-01-01T00:00:00Z",
        "notes": "Lorem ipsum..."
      }
    }
    ```
  </Step>

  <Step title="Get notified once feedback status changes">
    ### Feedback Status Change Event

    An event is triggered on the topic `categorisation.feedback_status.updated.v1` whenever the status of a categorisation feedback is updated.

    ```json theme={null}
    {
      "id": "31285f64-5717-4562-b3fc-2c961236afa7",
      "type": "categorisation.feedback_status.updated.v1",
      "applicationId": "4fa85f64-5717-4562-b3fc-2c963f66afa7",
      "event": {
        "status": "RESOLVED",
        "feedbackId": "dae419fc-9cd4-4221-8a7a-72d4bc7a7258"
      },
      "metadata": {
        "tracingId": "7cf5ef06-9f96-4f24-8bab-32ab09128020"
      }
    }
    ```

    | Property           | Value Type | Description                                     |
    | ------------------ | ---------- | ----------------------------------------------- |
    | id                 | String     | The Webhook ID used for delivering the event    |
    | type               | String     | The triggered event's type                      |
    | applicationId      | String     | The Application ID that registered this webhook |
    | event.status       | String     | The feedback's updated status                   |
    | event.feedbackId   | String     | The Feedback ID the event was triggered for     |
    | metadata.tracingId | String     | The Tracing ID of the event                     |
  </Step>

  <Step title="Retrieve feedback status">
    Once feedback has been submitted, you can retrieve it either by the Categorisation ID it was submitted against, or directly by its Feedback ID.

    1. Call `GET /transactions/categorisation/{categorisationId}/feedback` to retrieve all feedback submitted against a Categorisation ID
       * Optionally filter results by `status`
       * See the [endpoint's API specification](/api-reference/data-plus/get-categorisation-feedback) for details
    2. Or call `GET /transactions/categorisation/feedback/{feedbackId}` to retrieve a single piece of feedback by its Feedback ID
       * See the [endpoint's API specification](/api-reference/data-plus/get-categorisation-feedback-by-id) for details

    **Feedback status**

    Feedback moves through the following statuses as it's reviewed:

    | Status      | Description                                                 |
    | ----------- | ----------------------------------------------------------- |
    | `RECEIVED`  | Feedback has been submitted and is queued for review.       |
    | `IN_REVIEW` | Feedback is currently being reviewed.                       |
    | `RESOLVED`  | Feedback has been reviewed and addressed.                   |
    | `DECLINED`  | Feedback has been reviewed and will not result in a change. |
  </Step>
</Steps>

***

## Next steps

* [Read more about Categorisation](/data/data-plus/categorisation)
* [See the full category reference](/data/data-plus/categorisation-list)
* [Try our tutorial to get Categorisation](/data/data-plus/tutorial-categorisation)
* [View the Data Plus APIs](/api-reference/data-plus)