Skip to main content
POST
/
api
/
ai
/
parse
curl -X POST https://api.example.com/api/ai/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "05/03/2026 MERCADONA SUPERMERCADOS -85,50€\n04/03/2026 REPSOL GASOLINERA -60,00€\n01/03/2026 TRANSFERENCIA NOMINA +2.500,00€"
  }'

{
  "success": true,
  "transactions": [
    {
      "date": "2026-03-05",
      "description": "MERCADONA SUPERMERCADOS",
      "amount": -85.50,
      "category": "",
      "subcategory": ""
    },
    {
      "date": "2026-03-04",
      "description": "REPSOL GASOLINERA",
      "amount": -60.00,
      "category": "",
      "subcategory": ""
    },
    {
      "date": "2026-03-01",
      "description": "TRANSFERENCIA NOMINA",
      "amount": 2500.00,
      "category": "",
      "subcategory": ""
    }
  ],
  "provider": "groq",
  "responseTime": 845
}

​
Overview

This endpoint uses AI to extract structured transaction data from unstructured text. It can parse bank statements, receipts, or any text containing financial transaction information and convert it into a structured format.
Parse requests count as 1 request toward your AI rate limit and enable a free categorization call if used immediately after.

​
Authentication

This endpoint requires authentication via JWT token and CSRF protection.
​
Authorization
string
required
Bearer token for authentication
​
X-CSRF-Token
string
required
CSRF token for request validation

​
Request Body

​
text
string
required
The unstructured text containing transaction information to parse. This can be:
  • Bank statement text
  • Receipt content
  • Manual transaction entries
  • Any text format containing transaction data
The AI will extract dates, descriptions, amounts, and categories from this text.
​
provider
string
Optionally specify which AI provider to use for this request. If not provided, uses the currently active provider.Valid values:
  • groq - Fast inference with Groq
  • ollama - Local AI (requires local installation)
  • claude - Anthropic’s Claude
  • gemini - Google’s Gemini
  • huggingface - Hugging Face models

​
Response

​
success
boolean
required
Indicates if the request was successful
​
transactions
array
required
Array of parsed transaction objects extracted from the input text
​
provider
string
required
The AI provider that was used to process the request (e.g., “groq”, “claude”)
​
responseTime
number
required
Time taken to process the request in milliseconds

​
Parsing Rules

The AI follows these rules when parsing transactions:
  • Amounts: Negative for expenses, positive for income
  • Dates: Converted to ISO format (YYYY-MM-DD)
  • Decimal separators: Commas (50,00) are converted to periods (50.00)
  • Currency symbols: €, $, and other symbols are removed from amounts
  • Missing data: If date is unclear, returns null. If category not mentioned, left empty.

​
Supported AI Providers

This endpoint works with the following AI providers:
  • Groq - Fast inference with llama-3.3-70b-versatile model
  • Ollama - Local AI with llama3:latest (requires local Ollama installation at http://localhost:11434)
  • Claude - Anthropic’s claude-sonnet-4-20250514 model
  • Gemini - Google’s gemini-2.0-flash model
  • Hugging Face - Qwen/Qwen2.5-72B-Instruct via router.huggingface.co
Each provider requires appropriate API keys configured in environment variables (except Ollama which runs locally).

​
Rate Limiting

This endpoint is subject to rate limiting:
  • Each parse request counts as 1 request toward your rate limit
  • Enables a free /api/ai/categorize call if used immediately after
  • Check /api/ai/status for your current rate limit status and provider limits

​
Security

All input text is sanitized and checked for security issues:
  • Input is wrapped with security instructions to prevent prompt injection
  • Anti-jailbreak suffixes prevent malicious prompt manipulation
  • Malicious patterns are detected and blocked
  • Suspicious requests may be rejected with a 403 error
curl -X POST https://api.example.com/api/ai/parse \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-CSRF-Token: YOUR_CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "05/03/2026 MERCADONA SUPERMERCADOS -85,50€\n04/03/2026 REPSOL GASOLINERA -60,00€\n01/03/2026 TRANSFERENCIA NOMINA +2.500,00€"
  }'

{
  "success": true,
  "transactions": [
    {
      "date": "2026-03-05",
      "description": "MERCADONA SUPERMERCADOS",
      "amount": -85.50,
      "category": "",
      "subcategory": ""
    },
    {
      "date": "2026-03-04",
      "description": "REPSOL GASOLINERA",
      "amount": -60.00,
      "category": "",
      "subcategory": ""
    },
    {
      "date": "2026-03-01",
      "description": "TRANSFERENCIA NOMINA",
      "amount": 2500.00,
      "category": "",
      "subcategory": ""
    }
  ],
  "provider": "groq",
  "responseTime": 845
}

​
Error Codes

Status CodeDescription
200Success - transactions parsed
400Bad request - missing text, invalid provider, or AI not available
401Unauthorized - missing or invalid token
403Forbidden - CSRF validation failed or security check blocked request
429Too many requests - rate limit exceeded
500Internal server error

​
Example Use Cases

​
Parsing Bank Statement

Input Text
Fecha       Concepto                    Importe
05/03/26    MERCADONA S.A.             -45,30 EUR
05/03/26    SHELL GASOLINERA           -55,00 EUR  
04/03/26    AMAZON EU S.A.R.L          -29,99 EUR
01/03/26    NOMINA EMPRESA XYZ      +2.450,00 EUR
This would extract 4 transactions with proper dates, descriptions, and amounts.

​
Parsing Receipt

Input Text
STARBUCKS CAFE
123 MAIN STREET
Date: March 5, 2026

Latte            4.50
Croissant        3.25
Total           7.75 EUR
This would extract a single transaction for 7.75 EUR on 2026-03-05.

​
Parsing Manual Entry

Input Text
Bought groceries at Walmart for $85.50 yesterday
Paid gym membership $50 on March 1st
This would extract 2 transactions, attempting to parse relative dates.

Build docs developers (and LLMs) love

Get started for freeTalk to us