> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triqai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Enrichment

> How Triqai transforms raw transaction data into structured information

Transaction enrichment is the core capability of Triqai. It takes raw, unstructured transaction strings from bank statements and transforms them into clean, structured data that's easy to understand and use.

## The Problem

Bank transaction data is notoriously messy. A simple coffee purchase might appear as:

```
POS 4392 STARBUCKS STORE #1234 NEW YORK NY 10001
```

This string contains useful information: merchant name, store number, location, but it's buried in noise and inconsistent formatting. Every bank formats transactions differently, making it impossible to reliably extract meaning without specialized processing.

## The Solution

Triqai analyzes transaction strings using a combination of:

* **Pattern matching** against known merchant signatures
* **Natural language processing** to extract entities
* **Extensive merchant databases** (150M+ companies)
* **Location intelligence** (10M+ places globally)
* **Machine learning models** for classification and confidence scoring

The result is structured data you can immediately use in your application.

## Enrichment Pipeline

When you submit a transaction for enrichment, it goes through several stages:

<Steps>
  <Step title="Parsing">
    The raw transaction string is tokenized and analyzed for structure.
  </Step>

  <Step title="Entity Detection">
    Potential merchants, locations, intermediaries, and other entities are
    identified.
  </Step>

  <Step title="Matching">
    Detected entities are matched against our databases of known merchants,
    locations, and intermediaries.
  </Step>

  <Step title="Classification">
    The transaction is categorized and additional metadata (such as confidence
    signals) is determined.
  </Step>

  <Step title="Scoring">
    Confidence scores with explanatory reason tags are calculated for each
    entity and field.
  </Step>
</Steps>

## What Gets Enriched

Each enrichment request returns two main sections: **transaction metadata** and an **entities array**.

### Transaction Metadata

Classification and signals about the transaction itself:

* **Category** — Hierarchical spending categories (primary, secondary, tertiary) with MCC/SIC/NAICS codes
* **Confidence** — Overall enrichment confidence with reason tags

### Entities Array

An array of identified real-world entities, each with a `type`, `role`, `confidence`, and `data`:

* **Merchant** — The business behind the transaction (name, logo, website, domain)
* **Location** — The physical place where it occurred (address, coordinates, timezone)
* **Intermediary** — Payment processors, delivery platforms, wallets, or P2P services (Stripe, Venmo, DoorDash, etc.)
* **Person** — Recipient information for P2P transfers (display name)

Only entities that are actually identified appear in the array. If no location is found, no location entity is present. There are no `"status": "no_match"` entries.

## Request Format

A basic enrichment request requires three fields:

```json theme={null}
{
  "title": "AMAZON MKTPLACE PMTS AMZN.COM/BILL WA",
  "country": "US",
  "type": "expense"
}
```

| Field     | Type   | Required | Description                                              |
| --------- | ------ | -------- | -------------------------------------------------------- |
| `title`   | string | Yes      | Raw transaction description from bank statement          |
| `country` | string | Yes      | ISO 3166-1 alpha-2 country code (e.g., "US", "NL", "GB") |
| `type`    | string | Yes      | Transaction direction: `expense` or `income`             |

## Response Structure

The enrichment response uses an **entities array** pattern. Only found entities are included:

```json theme={null}
{
  "success": true,
  "partial": false,
  "data": {
    "transaction": {
      "category": {
        "primary": {
          "name": "Coffee Shops",
          "code": { "mcc": 5814, "sic": 5812, "naics": 722515 }
        },
        "secondary": {
          "name": "Food & Dining",
          "code": { "mcc": 5812, "sic": 5812, "naics": 722511 }
        },
        "tertiary": null,
        "confidence": { "value": 95, "reasons": ["merchant_category_match"] }
      },
      "confidence": { "value": 92, "reasons": [] }
    },
    "entities": [
      {
        "type": "merchant",
        "role": "organization",
        "confidence": {
          "value": 98,
          "reasons": ["name_closely_matched", "results_consensus"]
        },
        "data": {
          "id": "...",
          "name": "Starbucks",
          "alias": ["SBUX"],
          "icon": "https://logos.triqai.com/images/starbuckscom",
          "website": "https://www.starbucks.com",
          "domain": "starbucks.com"
        }
      },
      {
        "type": "location",
        "role": "store_location",
        "confidence": {
          "value": 85,
          "reasons": ["city_match", "store_id_match"]
        },
        "data": {
          "id": "...",
          "name": "Starbucks - Times Square",
          "formatted": "1530 Broadway, New York, NY 10036, USA",
          "structured": { "city": "New York", "state": "NY", "country": "US" }
        }
      }
    ]
  },
  "meta": {
    "generatedAt": "2026-01-15T10:30:00Z",
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a123",
    "version": "1.3.13",
    "categoryVersion": "triqai-2026.01"
  }
}
```

<Note>
  Only identified entities appear in the `entities` array. If no intermediary or
  location was found, they are simply absent not present with a null status.
</Note>

## Partial Results

Sometimes not all enrichment modules succeed. For example, a transaction might have a recognized merchant but no identifiable location. In these cases:

* The response includes `partial: true`
* Successful enrichments are returned normally in the `entities` array
* The `meta.errors` array lists which enrichers failed
* No credits are deducted for partial results

```json theme={null}
{
  "success": true,
  "partial": true,
  "data": {
    "transaction": { "confidence": { "value": 75, "reasons": [] } },
    "entities": [
      {
        "type": "merchant",
        "role": "organization",
        "confidence": { "value": 95, "reasons": ["name_closely_matched"] },
        "data": { "name": "Acme Corp" }
      }
    ]
  },
  "meta": {
    "errors": ["location_timeout"]
  }
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Provide accurate country codes" icon="globe">
    The country code helps Triqai narrow down merchant and location matching. An
    incorrect country code may lead to less accurate results.
  </Accordion>

  <Accordion title="Include full transaction strings" icon="text">
    Don't pre-process or truncate transaction titles. The full string often
    contains valuable signals like store numbers and location hints.
  </Accordion>

  <Accordion title="Set the correct transaction type" icon="arrows-left-right">
    The `type` field (`expense` vs `income`) helps classify refunds, transfers,
    and income sources correctly.
  </Accordion>

  <Accordion title="Use confidence scores and reasons" icon="chart-simple">
    Check confidence scores and their reason tags before displaying data to
    users. Low-confidence results may need manual review. Reason tags explain
    *why* the score is what it is.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Categories" icon="tags" href="/concepts/categories">
    Learn about the category taxonomy
  </Card>

  <Card title="Entities" icon="building" href="/concepts/entities">
    Understand merchant, location, intermediary, and person data
  </Card>

  <Card title="Confidence Scores" icon="chart-bar" href="/concepts/confidence-scores">
    How to interpret confidence scores and reason tags
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/enrich">
    See the full API documentation
  </Card>
</CardGroup>