Skip to main content
The Yapily Plus categorisation product is available as a BETA version.
1

Complete prerequisites

Before retrieving data from the Categorised Transactions endpoints, you will first need to:
  1. Obtain a Consent from the user
  2. Get Accounts for the user
  3. Register a Webhook for notification events when categorisation is done or failed

​
Webhook Registration

Please follow our Webhook Registration Guide in order to register a webhook for your application.

​
Webhook Events

In order to get notified when a categorisation request has finished successfully or failed you will have to subscriber to the following webhook events:
  • transactions.categorisation.completed - is the event triggered when a categorisation request finishes successfully and the data is ready to be picked up.
  • transactions.categorisation.failed - is the event triggered when a categorisation request fails to categorise the data successfully.
2

Submit categorisation request

Categorisation works asynchronously and therefore the flow requires you to have a registered webhook on for your application.In order to trigger a categorisation process follow the steps:
  • Call POST /accounts/{accountId}/transactions/categorisation endpoint.
    • Define categorisationType (consumer or business) according to your use case.
  • The response of the endpoint will return a categorisationId parameter.
  • Store the categorisationId since all further API calls will require it.
Please check API Reference for an up to date specification of the API.

​
Setting Boundaries for Efficient Data Categorization

To enhance the efficiency of data categorisation requests via the POST /accounts/{accountId}/transactions/categorisation endpoint, it is crucial to set specific time frame boundaries using the from and before query parameters. This approach helps to minimise system overloads and improve success rates by dividing extensive data requests into smaller, manageable intervals. For instance, to categorise three years of transaction data, we recommend submitting six separate requests, each covering a six-month period.
3

Wait for webhook notification

A webhook event will be sent to registered webhook in all situations, success or failure.

​
Categorisation Success Event

When categorisation has finished successfully then an event is triggered on the topic transactions.categorisation.completed
{
  "id": "41285f64-5717-4562-b3fc-2c961236afa6",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "transactions.categorisation.completed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259"
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
    "user": {
      "key": "value"
    }
  }
}
PropertyValue TypeDescription
idStringThe Webhook ID used for delivering the event
applicationIdStringThe Application ID that registered this webhook
typeStringThe triggered event’s type
event.categorisationIdStringThe Categorisation ID the event was triggered for
metadata.tracingIdStringThe Tracing ID of the event
metadata.userStringOptional. The metadata provided at Webhook registration

​
Categorisation Fail Event

When categorisation request processing failed then an event is triggered on the topic transactions.categorisation.failed
{
  "id": "41285f64-5717-4562-b3fc-2c961236afa6",
  "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "transactions.categorisation.failed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
    "error": {
      "issues": [
        {
          "code": 12345,
          "message": "error message"
        }
      ]
    }
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
    "user": {
      "key": "value"
    }
  }
}
PropertyValue TypeDescription
idStringThe Webhook ID used for delivering the event
applicationIdStringThe Application ID that registered this webhook
typeStringThe triggered event’s type
event.categorisationIdStringThe Categorisation ID the event was triggered for
error.issues[].codeIntegerA 5-digit error code pointing to the source of the problem
error.issues[].messageStringThe error message describing the issue
metadata.tracingIdStringThe Tracing ID of the event
metadata.userStringOptional. The metadata provided at Webhook registration

​
How to Handle Failure Event

We recommend that you build your app’s error handling around Error Codes, which would give you the best explanation of why your request has failed.
4

Retrieve categorised data

In order to retrieve categorised data call GET /transactions/categorisation/{categorisationId} endpoint.Please check API Reference for an up to date specification of the API.
The categorised transactions will be available for 30 mins only. If the transactions are not collected within that time, the categorisation will need to be completed again.

​
Elements

Where possible we return the following:
  • categories e.g. childcare
  • merchantName e.g. Netflix
  • recurrenceType e.g one-off, subscription, recurring
  • paymentProcessor e.g. Paypal
As with categories, the merchant and category of a transaction may change as we improve the accuracy of our merchant service and add new merchants.

​
Transaction Categories

To see the latest list of categories, use the GET /transactions/categorisation/categories/{accountType} endpoint

​
Categories definition

The definition for all the incoming and outgoing categories can be found here
Where the model cannot identify a merchant, the merchant field will be returned as {null}.