--- title: "Enrich transaction" method: POST path: "/v1/transactions/enrich" tags: ["Transactions"] --- # Enrich transaction `POST /v1/transactions/enrich` ## Request - Base URL: `https://api.triqai.com` - URL: `https://api.triqai.com/v1/transactions/enrich` - Auth: API key in header `X-API-Key` Enriches a transaction and returns structured transaction + entity data. ## Headers - `Idempotency-Key` string, required ## Request body - EnrichRequest - `title` string, required: Raw transaction description from the bank statement. - `country` string, required: ISO 3166-1 alpha-2 country code (e.g., US, GB, DE). Both upper and lowercase are accepted; the API normalizes to uppercase. - `type` 'expense' | 'income', required - `options` EnrichRequestOptions: Optional enrichment controls. Use `filters` to skip specific entity types, or pre-fill known entity data to improve accuracy and reduce latency. **Mutual exclusivity:** a filter flag (e.g. `noMerchant`) cannot be combined with pre-filled data for the same entity type. - `filters` EnrichmentFilterOptions: Disable extraction of specific entity types from the transaction title. - `noMerchant` boolean: When `true`, merchant extraction is skipped entirely. - `noIntermediary` boolean: When `true`, intermediary (payment processor) extraction is skipped. - `noLocation` boolean: When `true`, location extraction is skipped. - `merchant` PrefilledMerchant: Supply known merchant data to bypass or augment merchant extraction. When `id` is provided, the merchant is resolved by primary key (returns 422 if not found). `name` and `domain` perform best-effort lookups and fall through gracefully. - `id` string, uuid: Existing Triqai merchant UUID. - `name` string: Merchant display name for lookup. - `domain` string: Merchant domain (e.g. `starbucks.com`). - `location` PrefilledLocation: Supply known location context to improve enrichment accuracy. When `coordinates` are provided and `cityName` is not set, the API resolves them to a place name via reverse-geocoding and uses it as a location hint for AI title dissection. - `cityName` string: City name where the transaction occurred. - `physicalLocation` boolean: Whether the transaction happened at a physical location. - `coordinates` object: GPS coordinates of the transaction. When provided without `cityName`, coordinates are reverse-geocoded to resolve a place name. If no location is detected from transaction title text, the reverse-geocoded place becomes the fallback location. - `lat` number, required - `lng` number, required - `streetName` string: Street name of the transaction location. - `storeNumber` string: Store or branch number. - `intermediaries` PrefilledIntermediary[]: Up to 5 pre-filled intermediary entries. - union: Supply known intermediary (payment processor) data. When `id` is provided, the intermediary is resolved by primary key (returns 422 if not found). `name` and `domain` perform best-effort lookups. - object - `id` string, uuid, required: Existing Triqai intermediary UUID. - `name` string: Intermediary display name for lookup. - `domain` string: Intermediary domain (e.g. `paypal.com`). - object - `id` string, uuid: Existing Triqai intermediary UUID. - `name` string, required: Intermediary display name for lookup. - `domain` string: Intermediary domain (e.g. `paypal.com`). - object - `id` string, uuid: Existing Triqai intermediary UUID. - `name` string: Intermediary display name for lookup. - `domain` string, required: Intermediary domain (e.g. `paypal.com`). ## Response `200` Enrichment completed - EnrichSuccessResponse - `success` true, required - `partial` boolean, required - `data` EnrichmentData, required - `transaction` TransactionData, required - `category` CategoryStructure, required - `primary` Category, required - `name` string, required - `code` CategoryCode, required - `mcc` integer, required - `sic` integer, required - `naics` integer, required - `secondary` Category, required - `name` string, required - `code` CategoryCode, required - `mcc` integer, required - `sic` integer, required - `naics` integer, required - `tertiary` Category, required - `name` string, required - `code` CategoryCode, required - `mcc` integer, required - `sic` integer, required - `naics` integer, required - `confidence` ConfidenceWithReasons, required - `value` integer, required - `reasons` string[], required - `confidence` ConfidenceWithReasons, required - `value` integer, required - `reasons` string[], required - `entities` EntityResult[], required - `type` 'merchant' | 'location' | 'intermediary' | 'person', required - `role` string, required - `confidence` ConfidenceWithReasons, required - `value` integer, required - `reasons` string[], required - `data` union, required - MerchantEntityData - `id` string, uuid, required - `name` string, required - `alias` string[], required - `keywords` string[]: Search keywords associated with this merchant. May be absent. - `icon` string, uri, nullable, required - `description` string: Brief description of the merchant. May be absent. - `color` string, nullable, required - `website` string, uri, nullable, required - `domain` string, nullable, required - LocationData - `id` string, uuid, required - `name` string, required: Location display name (store/branch name). - `formatted` string, required: Human-readable formatted address string. - `phoneNumber` string, nullable, required: Phone number if available. - `website` string, uri, nullable: Location-specific website URL. May be absent. - `priceRange` string, nullable: Price range indicator (e.g. "$", "$$"). May be absent. - `rating` LocationRating - `average` number, required - `count` integer, required - `source` string, required - `structured` StructuredAddress, required - `street` string, required - `city` string, required - `state` string, required - `postalCode` string, required - `country` string, required - `countryName` string, required - `coordinates` Coordinates, required - … - `timezone` string, required - IntermediaryData - `id` string, uuid, required - `name` string, required - `icon` string, uri, nullable, required - `description` string, nullable, required - `color` string, nullable, required - `website` string, uri, nullable, required - `domain` string, nullable, required - PersonData - `displayName` string, required - `meta` EnrichMeta, required - `generatedAt` string, date-time, required - `requestId` string, required - `version` string, required - `categoryVersion` string, required - `transactionId` string, uuid, required: Identifier of the enriched transaction. - `errors` EnrichmentErrorCode[] ## Other responses - `401`: Authentication failed or missing credentials - `402`: Insufficient credits - `403`: Authenticated but not authorized - `409`: Duplicate idempotent request (completed or in-progress) - `410`: Transaction persistence refused because the transaction was erased or the organization is inactive. This response is terminal and must not be retried automatically. - `422`: Request validation failed - `429`: Rate limit exceeded - `499`: Client closed request before completion - `500`: Internal server error - `503`: Service temporarily unavailable - `504`: Upstream timeout --- [API](https://skmtc.dev/triqai/apis/triqai-transaction-enrichment-api.md) - [All operations](https://skmtc.dev/triqai/apis/triqai-transaction-enrichment-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triqai/apis/triqai-transaction-enrichment-api/revisions/da1b24723e53?raw)