---
title: "Enrich a bank transaction descriptor"
method: POST
path: "/v1/enrich/transaction"
tags: ["Merchant Enrichment"]
---

# Enrich a bank transaction descriptor

`POST /v1/enrich/transaction`

## Request

- Base URL: `https://api.nashboard.ai`
- URL: `https://api.nashboard.ai/v1/enrich/transaction`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Required scope: `enrich:transaction`. Returns a normalized merchant identity, category, hierarchy, and rail signals. Send descriptors as-is: bank-statement scaffolding (PSP prefixes, channel markers, store numbers, trailing city/country tokens) is stripped server-side before retrieval — client-side pre-cleaning is unnecessary. Descriptors in non-Latin scripts (Arabic, Persian, Cyrillic, Turkish) are matched natively without transliteration. Use `?debug=1` with the `enrich:debug` scope to surface internal scoring fields (rank_gap, nb_extensions) — silently ignored without the scope.

## Query parameters

- `debug` '1'
- `taxonomy` 'consumer_v2026.05' | 'mcc' | 'naics_2022' | 'isic_rev5' | 'nace_rev21' | 'uk_sic_2026' | 'anzsic_2006' | 'pfc_v2'

## Headers

- `X-Nashboard-Version` '2026-06-13'
- `X-Idempotency-Key` string

## Request body

- TransactionInput
  - `raw_descriptor` string, required: Raw bank transaction descriptor string. Send it exactly as it appears on the statement — do not pre-clean. PSP prefixes (e.g. "PAYPAL *", "SQ *", "TST*"), POS channel markers ("POS DEBIT", "CHECKCARD"), store numbers, and trailing city/country tokens are unwrapped server-side before matching. Non-Latin descriptors (Arabic, Persian, Cyrillic, Turkish) are matched natively in-script — no transliteration needed.
  - `amount_minor` integer: Transaction amount in minor currency units (e.g. cents).
  - `currency_code` string: ISO 4217 currency code (e.g. USD).
  - `date_hint` string: Transaction date hint (YYYY-MM-DD).
  - `country_hint` string: ISO 3166-1 alpha-2 country hint.
  - `user_locale` string: BCP 47 locale tag (e.g. en-US).

## Response `200`

Enriched result.

- EnrichResponse: W5a flat EnrichResponse. additionalProperties:true — fields such as merchant{}, hierarchy, bin_signal, debug fields (rank_gap, nb_extensions) are present but not fully closed in this schema.
  - `request_id` string, uuid, required
  - `merchant_id` string, uuid, nullable: Matched merchant ID, or null on no-match.
  - `merchant` object, nullable: Resolved merchant object (null on no-match). Carries additional hierarchy/standards fields not all enumerated here.
    - `name` string
    - `name_localized` object, nullable: Localized display names keyed by locale (e.g. en, ar, ru).
    - `logo_url` string, nullable
    - `confidence_tier` integer
  - `match_score` number, required: Customer-facing retrieval confidence 0-1. Distinct from ai_confidence.
  - `match_method` string, required: How the match was determined (e.g. exact, fuzzy, ai_haiku, ai_sonnet, no_match).
  - `ai_generated` boolean, required: True only when the AI disambiguation step produced/altered the returned match (EU AI Act Art. 50).
  - `ai_confidence` number, nullable, required: AI self-reported confidence 0-1 when AI fired; null otherwise.
  - `counterparties` object[], required: Rail-aware counterparty provenance (e.g. BNPL chains).
  - `is_recurring` boolean, required: True when the merchant has a known subscription pattern.
  - `recurrence` object, nullable: Recurrence cadence details; null when is_recurring is false.
  - `homoglyph_detected` boolean, required: Fraud signal: true when the descriptor mixes lookalike scripts (e.g. Cyrillic+Latin).
  - `latency_ms` integer, required: Server-side pipeline latency in ms.
  - `cache_hit` boolean
  - `category` object: Taxonomy classification result.
  - `hierarchy` object, nullable: Brand → operator → location hierarchy.
  - `alternates` object[]: Top-N alternate merchant candidates.
    - `merchant_id` string, uuid
    - `name` string
    - `confidence` number

## Other responses

- `400`: Bad request (invalid JSON, invalid ID, invalid cursor, etc.)
- `401`: Missing, malformed, or invalid API key.
- `403`: Insufficient scope or scope escalation attempt.
- `404`: Resource not found.
- `409`: Conflict (e.g. email already taken).
- `413`: Request body too large.
- `415`: Unsupported media type.
- `422`: Request body failed schema validation.
- `429`: Rate limited, quota exceeded, or DP budget exhausted.
- `500`: Internal server error.
- `502`: Upstream dependency error (e.g. receipt image storage unavailable — code storage_failure).

---

[API](https://skmtc.dev/nashboard/apis/nashboard-b2b-api.md) · [All operations](https://skmtc.dev/nashboard/apis/nashboard-b2b-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nashboard/apis/nashboard-b2b-api/revisions/a51f5ab22ec5?raw)