Skip to main content
This tutorial demonstrates how to use Yapily’s categorisation feature to enrich your own transaction data. You can provide transaction data from any source, not just data retrieved via Yapily.
1

Verify prerequisites

Before you start, make sure you have:
  • A Yapily application with valid credentials
  • Transaction data to categorise (in the correct format)
  • Register a Webhook for notification events when categorisation is done or failed
2

Register a webhook

Categorisation works asynchronously and therefore requires a registered webhook for your application.Please follow our Webhook Registration Guide to register a webhook endpoint.
curl --request POST \
  --url https://api.yapily.com/webhooks/event-subscriptions \
  --header 'Authorization: Basic [APPLICATION_SECRET_BASIC_AUTHENTICATION]' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventTypeId": "transactions.categorisation.completed",
    "url": "https://yourapp.com/webhooks/categorisation"
  }'
You must also subscribe to the transactions.categorisation.failed event to be notified of failures.
3

Submit transactions for categorisation

Send your transaction data to Yapily for categorisation. Each transaction should include:
  • id: Unique identifier for the transaction
  • date: Transaction date
  • description: Transaction description (used for categorisation)
  • amount: Transaction amount
  • currency: Currency code (e.g., GBP, EUR)
  • type: Transaction type (DEBIT or CREDIT)
curl --request POST \
  --url https://api.yapily.com/accounts/{accountId}/transactions/categorisation \
  --header 'Authorization: Basic [APPLICATION_SECRET_BASIC_AUTHENTICATION]' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactions": [
      {
        "id": "txn-001",
        "date": "2021-07-20T10:30:00Z",
        "description": "TESCO STORES 3297",
        "amount": -45.67,
        "currency": "GBP",
        "type": "DEBIT"
      },
      {
        "id": "txn-002",
        "date": "2021-07-21T14:22:00Z",
        "description": "AMAZON UK MARKETPLACE",
        "amount": -23.99,
        "currency": "GBP",
        "type": "DEBIT"
      },
      {
        "id": "txn-003",
        "date": "2021-07-22T09:15:00Z",
        "description": "SPOTIFY P1234567",
        "amount": -9.99,
        "currency": "GBP",
        "type": "DEBIT"
      },
      {
        "id": "txn-004",
        "date": "2021-07-23T08:00:00Z",
        "description": "SALARY PAYMENT",
        "amount": 2500.00,
        "currency": "GBP",
        "type": "CREDIT"
      }
    ]
  }'
Note the categorisationId - you’ll need this to retrieve the results.
4

Wait for webhook notification

Once the categorisation is submitted, Yapily will send a webhook notification when processing is complete.

​
Success event

{
  "type": "transactions.categorisation.completed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259"
  },
  "timestamp": "2021-07-27T09:36:00Z"
}

​
Failure event

{
  "type": "transactions.categorisation.failed",
  "event": {
    "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
    "reason": "Invalid transaction format"
  },
  "timestamp": "2021-07-27T09:36:00Z"
}
Categorisation typically completes within a few seconds, but can take up to a few minutes for large batches. Make sure to retrieve the results within 30 minutes, as they are only available for a limited time.
5

Retrieve categorised transactions

Use the categorisationId to retrieve the enriched transaction data with categories.
curl --request GET \
  --url 'https://api.yapily.com/transactions/categorisation/fae419fc-9cd4-4221-8a7a-72d4bc7a7259' \
  --header 'Authorization: Basic [APPLICATION_SECRET_BASIC_AUTHENTICATION]'

​
Understanding the enrichment data

Each categorised transaction includes an enrichment object with:
  • categorisation.category: The primary category assigned to the transaction
  • categorisation.categories: An array of all applicable categories (ordered by relevance)
  • merchant.name: The clean merchant name (if identified)
  • merchant.businessName: The full business name (if identified)

​
Available categories

Yapily categorises transactions into the following categories:
  • GROCERIES
  • SHOPPING
  • ENTERTAINMENT
  • BILLS
  • TRANSPORT
  • EATING_OUT
  • INCOME
  • SALARY
  • CASH
  • TRANSFERS
  • GENERAL
  • And more…
For a complete list of categories, see the Categorisation documentation.

​
Data retention

Categorised transaction data is available for 30 minutes after completion. Make sure to retrieve the results within this time window. After 30 minutes, the data will be automatically deleted.

​
Next steps