Categorisation Feedback

Yapily Data Plus is available as a BETA version.

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

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 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

Complete prerequisites

Before submitting feedback on a categorised transaction, you will first need to:

Have a Categorisation result, including the Categorisation ID and Transaction Hash you want to submit feedback for
Register a Webhook for notification events when a feedback’s status changes

Webhook Registration

Please follow our Webhook Registration Guide 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.

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.

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 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.

{
  "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:

{
  "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..."
  }
}

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.

{
  "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

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.

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 for details
Or call GET /transactions/categorisation/feedback/{feedbackId} to retrieve a single piece of feedback by its Feedback ID
- See the endpoint’s API specification for details

Feedback statusFeedback 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.

Learn

Build

Payments

Data

Hosted Pages

Resources

Categorisation Feedback

Background

How it works

Webhook Registration

Webhook Event

Submitting feedback on a transaction

Feedback Status Change Event

Next steps

​Background

​How it works

​Webhook Registration

​Webhook Event

​Submitting feedback on a transaction

​Feedback Status Change Event

​Next steps

Background

How it works

Webhook Registration

Webhook Event

Submitting feedback on a transaction

Feedback Status Change Event

Next steps