---
title: "Parse natural language guard transaction text using AI"
method: POST
path: "/api-regulated/v1/guard-quotes/smart-parse"
tags: ["GuardQuote"]
---

# Parse natural language guard transaction text using AI

`POST /api-regulated/v1/guard-quotes/smart-parse`

## Request

- Base URL: `https://api.currencyguard.com`
- URL: `https://api.currencyguard.com/api-regulated/v1/guard-quotes/smart-parse`
- Auth: HTTP bearer

Parses a natural language description of a guard transaction into structured fields
using LLM integration (Google Gemini).

**Example Request:**
```json
{
  "text": "Thames Trading needs to buy €650k against GBP in 45 days for supplier invoice TT-2025-443 with 25 basis points and they want to pay later"
}
```

**Example Response:**
```json
{
  "payReceive": "PAY",
  "foreignCurrency": "EUR",
  "guardCurrency": "GBP",
  "foreignAmount": 650000,
  "guardSettlementWindowTo": "2026-01-06T00:00:00Z",
  "salesMarginRate": 0.0025,
  "externalRef": "TT-2025-443",
  "companyName": "Thames Trading",
  "isPayLater": true,
  "amountInputMode": "foreign",
  "reason": "Supplier invoice TT-2025-443"
}
```

**What gets parsed:**
- Direction: "buy" → PAY
- Amount: "€650k" → 650000 (foreignAmount)
- Amount mode: "foreign" (indicates foreignAmount was specified, not targetGuardAmount)
- Currency pair: "€" → EUR, "against GBP" → GBP
- Settlement: "in 45 days" → calculated date
- Margin: "25 basis points" → 0.0025 (decimal rate)
- Reference: "invoice TT-2025-443" → TT-2025-443
- Company/Customer: Returned as strings (companyName, customerName, customerEmail) for client-side fuzzy matching
- Payment terms: "pay later" → true
- Context: "supplier invoice" → extracted to reason field

The parsed fields can then be used to pre-populate a guard quote request.
Client performs fuzzy matching against their company/customer lists.

## Request body

- SmartParseGuardQuoteRequestDTO: Request to parse natural language text into guard quote fields
  - `text` string, required: Natural language text describing the guard transaction

## Response `200`

Text successfully parsed

- SmartParseGuardQuoteResponseDTO: Parsed guard quote fields from natural language input
  - `payReceive` 'PAY' | 'RECEIVE': Indicates whether the guard will pay or receive foreign currency
  - `foreignCurrency` string: Foreign currency of this guard (ISO 4217 code)
  - `guardCurrency` string: Guard currency, typically the corporate base currency (ISO 4217 code)
  - `foreignAmount` number: Amount of the guard in the foreign currency
  - `targetGuardAmount` number: Target amount in guard currency (net of fees) - alternative to foreignAmount
  - `guardSettlementWindowTo` string: End settlement window of this guard in ISO 8601 format
  - `salesMarginRate` number: Sales margin rate as a decimal (e.g., 0.0025 = 25bps = 0.25%)
  - `salesMarginAmount` number: Sales margin as an absolute amount in guard currency
  - `guardMarginRate` number: Guard margin rate as a decimal, incorporated into the guard fee (e.g., 0.01 = 1%)
  - `paymentMarginAtInception` number: Payment margin rate inside the guard rate, applied at inception, as a decimal (e.g., 0.01 = 1%)
  - `externalRef` string: External reference such as invoice or contract number
  - `companyName` string: Parsed company name for fuzzy matching
  - `customerName` string: Parsed customer contact name
  - `customerEmail` string: Customer email address
  - `isPayLater` boolean: Whether pay-later option was requested
  - `amountInputMode` 'foreign' | 'guard': Amount input mode indicating which amount was specified
  - `reason` string: Additional context or notes about the guard transaction

## Other responses

- `400`: Invalid request data — [`http/malformed-request`](/problems/http/malformed-request/)
- `401`: Not authenticated — [`security/authentication-failed`](/problems/security/authentication-failed/)
- `403`: Not authorized — [`security/insufficient-permissions`](/problems/security/insufficient-permissions/)
- `422`: Text cannot be parsed — [`validation/validation-error`](/problems/validation/validation-error/)
- `500`: Server error — [`server/internal-error`](/problems/server/internal-error/)

---

[API](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external.md) · [All operations](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/llms.txt) · [OpenAPI document](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/revisions/a1f3f854190d?raw)