---
title: "Enrich up to 100 transactions in a single request"
method: POST
path: "/v1/enrich/bulk"
tags: ["Merchant Enrichment"]
---

# Enrich up to 100 transactions in a single request

`POST /v1/enrich/bulk`

## Request

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

Required scope: `enrich:transaction`. AI fallback is forced OFF for bulk (retrieval-grade only). Billed per successful item. Partial failures do not roll back successes. Retry failed items individually via POST /v1/enrich/transaction (which supports X-Idempotency-Key).

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

## Request body

- BulkEnrichRequest
  - `items` TransactionInput[], required
    - `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`

Per-item results and summary. Partial failures do not fail the request.

- BulkEnrichResponse
  - `results` union[], required
    - union
      - object
        - `index` integer, required
        - `status` 'ok', required
        - `result` EnrichResponse, required: 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
      - object
        - `index` integer, required
        - `status` 'error', required
        - `error_code` string, required
        - `message` string, required
  - `summary` object, required
    - `total` integer, required
    - `ok` integer, required
    - `error` integer, required

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