> ## 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.
# Tutorial: Get Transactions and Enrichment
> This tutorial walks you through each of the steps required to obtain Categorisation.
The Yapily Plus categorisation product is available as a BETA version.
***
Before retrieving data from the **Categorised Transactions** endpoints, you will first need to:
1. [Obtain a Consent](/api-reference/authorisations/create-account-authorisation) from the user
2. [Get Accounts](/api-reference/financial-data/get-accounts) for the user
3. [Register a Webhook](/tools-and-services/webhooks/introduction) for notification events when categorisation is done or failed
### Webhook Registration
Please follow our [Webhook Registration Guide](/tools-and-services/webhooks/introduction) 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.
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](/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.
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`
```json theme={null}
{
"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"
}
}
}
```
| Property | Value Type | Description |
| ---------------------- | ---------- | ----------------------------------------------------------- |
| id | String | The Webhook ID used for delivering the event |
| applicationId | String | The Application ID that registered this webhook |
| type | String | The triggered event's type |
| event.categorisationId | String | The Categorisation ID the event was triggered for |
| metadata.tracingId | String | The Tracing ID of the event |
| metadata.user | String | **Optional.** 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`
```json theme={null}
{
"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"
}
}
}
```
| Property | Value Type | Description |
| ----------------------- | ---------- | ----------------------------------------------------------- |
| id | String | The Webhook ID used for delivering the event |
| applicationId | String | The Application ID that registered this webhook |
| type | String | The triggered event's type |
| event.categorisationId | String | The Categorisation ID the event was triggered for |
| error.issues\[].code | Integer | A 5-digit error code pointing to the source of the problem |
| error.issues\[].message | String | The error message describing the issue |
| metadata.tracingId | String | The Tracing ID of the event |
| metadata.user | String | **Optional.** The metadata provided at Webhook registration |
### How to Handle Failure Event
We recommend that you build your app's error handling around [Error Codes](/resources/errors#enhanced-error-format-documentation), which would give you the best explanation of why your request has failed.
In order to retrieve categorised data call `GET /transactions/categorisation/{categorisationId}` endpoint.
Please check [API Reference](/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](/data/data-plus/categorisation-list)
Where the model cannot identify a merchant, the merchant field will be returned as **\{null}**.