> ## 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 Enrichment Only

> Step-by-step tutorial for using enrichment with your own transaction data

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.

<Steps>
  <Step title="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](/tools-and-services/webhooks/introduction) for notification events when categorisation is done or failed
  </Step>

  <Step title="Register a webhook">
    Categorisation works asynchronously and therefore requires a registered webhook for your application.

    Please follow our [Webhook Registration Guide](/tools-and-services/webhooks/introduction) to register a webhook endpoint.

    <CodeGroup>
      ```bash Request theme={null}
      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"
        }'
      ```

      ```json Response theme={null}
      {
        "data": {
          "id": "webhook-subscription-123",
          "eventTypeId": "transactions.categorisation.completed",
          "url": "https://yourapp.com/webhooks/categorisation",
          "status": "ACTIVE",
          "createdAt": "2021-07-27T09:30:00Z"
        }
      }
      ```
    </CodeGroup>

    You must also subscribe to the `transactions.categorisation.failed` event to be notified of failures.
  </Step>

  <Step title="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`)

    <CodeGroup>
      ```bash Request theme={null}
      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"
            }
          ]
        }'
      ```

      ```json Response theme={null}
      {
        "data": {
          "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
          "status": "PROCESSING",
          "transactionCount": 4,
          "createdAt": "2021-07-27T09:35:00Z"
        },
        "meta": {
          "tracingId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        }
      }
      ```
    </CodeGroup>

    Note the `categorisationId` - you'll need this to retrieve the results.
  </Step>

  <Step title="Wait for webhook notification">
    Once the categorisation is submitted, Yapily will send a webhook notification when processing is complete.

    ### Success event

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

    ### Failure event

    ```json theme={null}
    {
      "type": "transactions.categorisation.failed",
      "event": {
        "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
        "reason": "Invalid transaction format"
      },
      "timestamp": "2021-07-27T09:36:00Z"
    }
    ```

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Retrieve categorised transactions">
    Use the `categorisationId` to retrieve the enriched transaction data with categories.

    <CodeGroup>
      ```bash Request theme={null}
      curl --request GET \
        --url 'https://api.yapily.com/transactions/categorisation/fae419fc-9cd4-4221-8a7a-72d4bc7a7259' \
        --header 'Authorization: Basic [APPLICATION_SECRET_BASIC_AUTHENTICATION]'
      ```

      ```json Response theme={null}
      {
        "data": {
          "categorisationId": "fae419fc-9cd4-4221-8a7a-72d4bc7a7259",
          "status": "COMPLETED",
          "transactions": [
            {
              "id": "txn-001",
              "date": "2021-07-20T10:30:00Z",
              "description": "TESCO STORES 3297",
              "amount": -45.67,
              "currency": "GBP",
              "type": "DEBIT",
              "enrichment": {
                "categorisation": {
                  "categories": [
                    "GROCERIES",
                    "SHOPPING"
                  ],
                  "category": "GROCERIES"
                },
                "merchant": {
                  "name": "Tesco",
                  "businessName": "Tesco Stores"
                }
              }
            },
            {
              "id": "txn-002",
              "date": "2021-07-21T14:22:00Z",
              "description": "AMAZON UK MARKETPLACE",
              "amount": -23.99,
              "currency": "GBP",
              "type": "DEBIT",
              "enrichment": {
                "categorisation": {
                  "categories": [
                    "SHOPPING",
                    "GENERAL"
                  ],
                  "category": "SHOPPING"
                },
                "merchant": {
                  "name": "Amazon",
                  "businessName": "Amazon UK"
                }
              }
            },
            {
              "id": "txn-003",
              "date": "2021-07-22T09:15:00Z",
              "description": "SPOTIFY P1234567",
              "amount": -9.99,
              "currency": "GBP",
              "type": "DEBIT",
              "enrichment": {
                "categorisation": {
                  "categories": [
                    "ENTERTAINMENT",
                    "SUBSCRIPTION"
                  ],
                  "category": "ENTERTAINMENT"
                },
                "merchant": {
                  "name": "Spotify",
                  "businessName": "Spotify Limited"
                }
              }
            },
            {
              "id": "txn-004",
              "date": "2021-07-23T08:00:00Z",
              "description": "SALARY PAYMENT",
              "amount": 2500.00,
              "currency": "GBP",
              "type": "CREDIT",
              "enrichment": {
                "categorisation": {
                  "categories": [
                    "INCOME",
                    "SALARY"
                  ],
                  "category": "INCOME"
                }
              }
            }
          ],
          "completedAt": "2021-07-27T09:36:00Z"
        },
        "meta": {
          "tracingId": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
        }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## 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/data-plus/categorisation).

## Data retention

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

## Next steps

* Learn about [Transaction Categorisation](/data/data-plus/categorisation)
* Explore the [Categorisation List](/data/data-plus/categorisation-list)
* See the [Categorisation Tutorial](/data/data-plus/tutorial-categorisation) for categorising Yapily-sourced transactions