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

<Note>
  Yapily Data Plus is available as a BETA version.
</Note>

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