API documentation

One request turns a raw transaction string into a merchant, category and more.

Overview

Base URL	https://financial-core-production.up.railway.app/v1
Format	JSON over HTTPS. Send `Content-Type: application/json`.
Auth	API key in the `Authorization` header.
Current engine	3.2.0+af7d1cc4

Versioning. Everything under /v1 is additive-only: fields are never removed, renamed or re-typed, so an integration written today keeps working while the matching engine improves behind it. Treat unknown response fields as ignorable. Breaking changes ship as /v2, side by side. Every response carries X-Tanzim-Engine-Version so you can tell which build answered.

Quickstart

1. Get a test key (instant, free): create one here, or curl -X POST https://financial-core-production.up.railway.app/v1/keys -H "Content-Type: application/json" -d '{}'.
2. Send a transaction — if you created a key in this browser it is already filled into the snippets below:

curl -X POST https://financial-core-production.up.railway.app/v1/enrich \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "NETFLIX.COM 4029357689"}'

import requests

resp = requests.post(
    "https://financial-core-production.up.railway.app/v1/enrich",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"description": "NETFLIX.COM 4029357689"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["merchant_name"])

const res = await fetch("https://financial-core-production.up.railway.app/v1/enrich", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ description: "NETFLIX.COM 4029357689" }),
});
const data = await res.json();
console.log(data.merchant_name);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := bytes.NewBufferString(`{"description": "NETFLIX.COM 4029357689"}`)
	req, _ := http.NewRequest("POST", "https://financial-core-production.up.railway.app/v1/enrich", body)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}

require "net/http"
require "json"

uri = URI("https://financial-core-production.up.railway.app/v1/enrich")
req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer YOUR_API_KEY", "Content-Type" => "application/json")
req.body = { description: "NETFLIX.COM 4029357689" }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(req) }
puts JSON.parse(res.body)["merchant_name"]

<?php
$ch = curl_init("https://financial-core-production.up.railway.app/v1/enrich");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["description" => "NETFLIX.COM 4029357689"]),
]);
$data = json_decode(curl_exec($ch), true);
echo $data["merchant_name"];

import java.net.URI;
import java.net.http.*;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpRequest req = HttpRequest.newBuilder(URI.create("https://financial-core-production.up.railway.app/v1/enrich"))
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("{\"description\": \"NETFLIX.COM 4029357689\"}"))
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
var content = new StringContent("{\"description\": \"NETFLIX.COM 4029357689\"}", Encoding.UTF8, "application/json");
var res = await client.PostAsync("https://financial-core-production.up.railway.app/v1/enrich", content);
Console.WriteLine(await res.Content.ReadAsStringAsync());

3. Read the result:

{
  "input": "NETFLIX.COM 4029357689",
  "matched": true,
  "merchant_name": "Netflix",
  "category": "Subscriptions & OTT",
  "subcategory": "OTT - International",
  "country": null,
  "logo_url": "https://www.google.com/s2/favicons?domain=netflix.com&sz=128",
  "website": "https://netflix.com",
  "domain": "netflix.com",
  "mcc": "5968",
  "confidence": 0.99,
  "match": {
    "method": "substring",
    "matched_on": "NETFLIX COM"
  },
  "counterparty": null,
  "request_id": "req_…",
  "engine_version": "3.2.0+af7d1cc4"
}

Always check matched before using merchant_name. When it is false (for example a person-to-person transfer) the fields are null — see the live examples at the playground.

Analyse a bank statement

Upload a statement and get every transaction parsed, classified and enriched, plus spending insights. PDF (with selectable text), CSV and Excel (.xlsx) are supported, up to 8 MB. The file is processed in memory and never stored.

curl -X POST https://financial-core-production.up.railway.app/v1/statements/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@statement.pdf"

import requests

with open("statement.pdf", "rb") as f:
    r = requests.post("https://financial-core-production.up.railway.app/v1/statements/analyze",
                      headers={"Authorization": "Bearer YOUR_API_KEY"}, files={"file": f}, timeout=60)
r.raise_for_status()
result = r.json()
print(result["statement"]["confidence"], result["insights"]["summary"]["spending"])

The response has three parts: statement (what was read, with a confidence grade and a reconciliation self-check against the statement's own balances), transactions (each with direction, kind and a full enrichment), and insights (summary, categories, top merchants, monthly trend, recurring payments, transfers, and how much spending could be identified). Show statement.warnings to your user. If you already have the transactions as data, send them to POST /v1/transactions/analyze instead. Statements are limited to 20 per hour per key.

Privacy. Statement contents are not stored. Only merchant narrations Tanzim could not identify are kept to improve matching, with long digit runs and e-mail addresses masked and person-to-person transfers excluded.

Authentication

Send your key as Authorization: Bearer tz_test_…, or as X-API-Key: tz_test_… if your tooling can't set that header. Verify a key with GET /v1/me. Rotate by creating a new key, switching over, then DELETE /v1/keys/current with the old one. Keep keys out of public front-end code.

Endpoints

GET/v1/health

Liveness check · No authentication

Responses

Status	Meaning
200	Successful Response Health

GET/v1/meta

Engine and data summary · No authentication

Responses

Status	Meaning
200	Successful Response Meta

GET/v1/examples

Live example inputs and outputs · No authentication

Sample transactions run through the engine right now, so the output is always what the current build really returns. The docs pages are generated from this.

Responses

Status	Meaning
200	Successful Response ExamplesResponse

POST/v1/keys

Create a test API key · No authentication

Self-serve and instant: no approval step. Returns the key once. Limited per IP address.

Request body · KeyRequest

Field	Type	Description
name	string \| null	What you're building (shown only to you). e.g. `"My budgeting app"`
email	string \| null	Optional, but lets us tell you about breaking changes and quota.
source	string \| null	Free-form label for where the key was requested from.

Responses

Status	Meaning
201	Successful Response KeyCreated
400	The request body or a parameter is missing or malformed. `details` lists the offending fields. ErrorResponse
429	Too many requests. Wait `Retry-After` seconds, then retry. ErrorResponse

Example request

{
  "name": "My budgeting app",
  "email": "dev@example.com"
}

Example response

{
  "key": "tz_test_Xk3…",
  "id": "key_0a1b2c3d4e5f6a7b",
  "prefix": "tz_test_Xk3d",
  "environment": "test",
  "created_at": "2026-01-01T12:00:00+00:00",
  "rate_limits": {
    "per_minute": 120,
    "per_day": 10000
  },
  "message": "Store this key now; it cannot be shown again."
}

GET/v1/me

Check your API key · API key required

The quickest way to verify an integration: returns 200 if your key works.

Responses

Status	Meaning
200	Successful Response Me
401	`missing_api_key` or `invalid_api_key`. ErrorResponse

DELETE/v1/keys/current

Revoke the key you are using · API key required

Use to rotate: create a new key, switch over, then revoke the old one. Irreversible.

Responses

Status	Meaning
200	Successful Response Revoked
401	`missing_api_key` or `invalid_api_key`. ErrorResponse

POST/v1/enrich

Enrich one transaction · API key required

Identify the merchant behind a raw transaction string and return structured details.

Request body · EnrichRequest

Field	Type	Description
descriptionrequired	string	The raw transaction string exactly as it appears on the statement or card feed. e.g. `"NETFLIX.COM 4029357689"`
mcc	string \| null	Optional 4-digit Merchant Category Code from the card network. Used only as a fallback category when the merchant cannot be identified. `mcc_code` is accepted as an alias. e.g. `"5968"`

Responses

Status	Meaning
200	Successful Response EnrichResponse
400	The request body or a parameter is missing or malformed. `details` lists the offending fields. ErrorResponse
401	`missing_api_key` or `invalid_api_key`. ErrorResponse
429	Too many requests. Wait `Retry-After` seconds, then retry. ErrorResponse

Example request

{
  "description": "NETFLIX.COM 4029357689"
}

Example response

{
  "input": "NETFLIX.COM 4029357689",
  "matched": true,
  "merchant_name": "Netflix",
  "category": "Subscriptions & OTT",
  "subcategory": "OTT - International",
  "country": null,
  "logo_url": "https://www.google.com/s2/favicons?domain=netflix.com&sz=128",
  "website": "https://netflix.com",
  "domain": "netflix.com",
  "mcc": "5968",
  "confidence": 0.99,
  "match": {
    "method": "substring",
    "matched_on": "NETFLIX COM"
  },
  "counterparty": null,
  "request_id": "req_9f2c41d07a3b5e6c8d10",
  "engine_version": "3.2.0+af7d1cc4"
}

POST/v1/enrich/batch

Enrich many transactions · API key required

Up to 100 transactions per call. Each item counts once toward your rate limit. Results are in input order; one unmatched item never fails the whole batch.

Request body · BatchRequest

Field	Type	Description
itemsrequired	array of EnrichRequest	1 to 100 transactions. Results come back in the same order.

Responses

Status	Meaning
200	Successful Response BatchResponse
400	The request body or a parameter is missing or malformed. `details` lists the offending fields. ErrorResponse
401	`missing_api_key` or `invalid_api_key`. ErrorResponse
429	Too many requests. Wait `Retry-After` seconds, then retry. ErrorResponse

Example request

{
  "items": [
    {
      "description": "NETFLIX.COM 4029357689"
    },
    {
      "description": "From Ali Raza (SadaPay) (Incoming transfer)"
    }
  ]
}

Example response

{
  "request_id": "req_9f2c41d07a3b5e6c8d10",
  "engine_version": "3.2.0+af7d1cc4",
  "results": [
    {
      "input": "NETFLIX.COM 4029357689",
      "matched": true,
      "merchant_name": "Netflix",
      "category": "Subscriptions & OTT",
      "subcategory": "OTT - International",
      "country": null,
      "logo_url": "https://www.google.com/s2/favicons?domain=netflix.com&sz=128",
      "website": "https://netflix.com",
      "domain": "netflix.com",
      "mcc": "5968",
      "confidence": 0.99,
      "match": {
        "method": "substring",
        "matched_on": "NETFLIX COM"
      },
      "counterparty": null
    },
    {
      "input": "From Ali Raza (SadaPay) (Incoming transfer)",
      "matched": false,
      "merchant_name": null,
      "category": null,
      "subcategory": null,
      "country": null,
      "logo_url": null,
      "website": null,
      "domain": null,
      "mcc": null,
      "confidence": 0.0,
      "match": {
        "method": "none",
        "matched_on": null
      },
      "counterparty": {
        "name": "Ali Raza",
        "raw_name": "Ali Raza",
        "bank": "SadaPay",
        "channel": "wallet",
        "direction": "in",
        "confidence": "high"
      }
    }
  ]
}

POST/v1/statements/analyze

Analyse a bank or card statement · API key required

Upload a statement (PDF, CSV or Excel) and get back every transaction parsed, dated, classified and enriched with merchant details, plus insights: spending by category and merchant, monthly trend, recurring payments and subscriptions, transfers, fees and cash. The file is processed in memory and never stored. statement.confidence and statement.reconciliation tell you whether the parse can be trusted: if the statement has a balance column, every row is checked against it.

Responses

Status	Meaning
200	Successful Response AnalysisResponse
400	The request body or a parameter is missing or malformed. `details` lists the offending fields. ErrorResponse
401	`missing_api_key` or `invalid_api_key`. ErrorResponse
429	Too many requests. Wait `Retry-After` seconds, then retry. ErrorResponse
413	The request body is too large (1 MB for most endpoints; statements may be larger, see /v1/meta). ErrorResponse
415	That file type isn't supported. Upload a PDF, CSV or Excel (.xlsx) statement. ErrorResponse
422	The file was read but no transactions could be extracted (for example a scanned PDF, a password-protected PDF, or a file that isn't a statement). `details[].reason` says which. ErrorResponse

POST/v1/transactions/analyze

Analyse a list of transactions · API key required

Same enrichment and insights as /statements/analyze, for transactions you already have as structured data (up to 5000). Include balance when you can: it makes direction detection and the self-check reliable.

Request body · TransactionsRequest

Field	Type	Description
transactionsrequired	array of TransactionIn
currency	string \| null	ISO currency code, used for labelling only.

Responses

Status	Meaning
200	Successful Response AnalysisResponse
400	The request body or a parameter is missing or malformed. `details` lists the offending fields. ErrorResponse
401	`missing_api_key` or `invalid_api_key`. ErrorResponse
429	Too many requests. Wait `Retry-After` seconds, then retry. ErrorResponse
413	The request body is too large (1 MB for most endpoints; statements may be larger, see /v1/meta). ErrorResponse
422	The file was read but no transactions could be extracted (for example a scanned PDF, a password-protected PDF, or a file that isn't a statement). `details[].reason` says which. ErrorResponse

Objects

Generated from the live OpenAPI document, so it always matches what the API really returns.

AnalysisResponse

Field	Type	Description
request_idrequired	string
engine_versionrequired	string
statementrequired	StatementInfo
transactionsrequired	array of StatementTransaction
insightsrequired	Insights

BatchRequest

Field	Type	Description
itemsrequired	array of EnrichRequest	1 to 100 transactions. Results come back in the same order.

BatchResponse

Field	Type	Description
request_idrequired	string
engine_versionrequired	string
resultsrequired	array of EnrichResult

Body_analyze_statement_file_statements_analyze_post

Field	Type	Description
filerequired	string	The statement file: PDF (with selectable text), CSV or Excel (.xlsx).

CategoryCount

Field	Type	Description
namerequired	string
merchantsrequired	integer

CategoryInsight

Field	Type	Description
categoryrequired	string	Merchant category; unidentified spending is grouped as `Unidentified`.
amountrequired	number
countrequired	integer
sharerequired	number	Share of total spending, 0 to 1.
top_merchantsrequired	array of string

CounterpartyInfo

Field	Type	Description
namerequired	string	The other person's name with sensible capitalisation ("RAO EHTISHAM ALI KHAN" -> "Rao Ehtisham Ali Khan"). e.g. `"Ali Raza"`
raw_namerequired	string	Exactly as printed on the statement (the account title returned by the bank's title fetch). e.g. `"ALI RAZA"`
bank	string \| null	The other party's bank or wallet, when the narration shows it. e.g. `"HBL"`
channel	string \| null	`ibft`, `raast`, `wallet`, `transfer`, or `card` (a card payment made to a person's name).
direction	string \| null	`in` or `out`, from the wording of the narration. A statement's debit/credit is more reliable when you have it.
confidencerequired	string	`high` (two or more words) or `low` (a single word).

CounterpartyInsight

Field	Type	Description
namerequired	string
sentrequired	number
receivedrequired	number
countrequired	integer

EnrichRequest

Field	Type	Description
descriptionrequired	string	The raw transaction string exactly as it appears on the statement or card feed. e.g. `"NETFLIX.COM 4029357689"`
mcc	string \| null	Optional 4-digit Merchant Category Code from the card network. Used only as a fallback category when the merchant cannot be identified. `mcc_code` is accepted as an alias. e.g. `"5968"`

EnrichResponse

Field	Type	Description
inputrequired	string	The description you sent, echoed back (handy for batches).
matchedrequired	boolean	True when a specific merchant was identified. Check this before using `merchant_name`.
merchant_name	string \| null	Canonical merchant name. null when `matched` is false. e.g. `"Netflix"`
category	string \| null	Spending category. When `matched` is false this is only set if you sent an `mcc`. e.g. `"Subscriptions & OTT"`
subcategory	string \| null	e.g. `"OTT - International"`
country	string \| null	ISO 3166-1 alpha-2 country the merchant operates in, where known; otherwise null. e.g. `"PK"`
logo_url	string \| null	Logo/icon image URL. Checked to load when last verified; null when no working logo is known, so show your own placeholder (e.g. the merchant's initial).
website	string \| null	e.g. `"https://netflix.com"`
domain	string \| null	e.g. `"netflix.com"`
mcc	string \| null	The merchant's usual Merchant Category Code, where known. e.g. `"5968"`
confidencerequired	number	How sure Tanzim is that `merchant_name` is right, 0 to 1. It is derived from the match method and similarity score, not a calibrated probability: treat >= 0.9 as reliable and anything lower as worth a human glance. Always 0 when `matched` is false. e.g. `0.99`
matchrequired	Match
counterparty	CounterpartyInfo \| null	For person-to-person transfers whose narration names the other person (IBFT / Raast / wallet title fetch): who it is. When present, `matched` is false unless a real merchant was identified.
request_idrequired	string	Unique id for this request; also sent as the `X-Request-Id` header.
engine_versionrequired	string	Version of the matching engine + merchant data that produced this result. e.g. `"3.1.0+18b095da"`

EnrichResult

Field	Type	Description
inputrequired	string	The description you sent, echoed back (handy for batches).
matchedrequired	boolean	True when a specific merchant was identified. Check this before using `merchant_name`.
merchant_name	string \| null	Canonical merchant name. null when `matched` is false. e.g. `"Netflix"`
category	string \| null	Spending category. When `matched` is false this is only set if you sent an `mcc`. e.g. `"Subscriptions & OTT"`
subcategory	string \| null	e.g. `"OTT - International"`
country	string \| null	ISO 3166-1 alpha-2 country the merchant operates in, where known; otherwise null. e.g. `"PK"`
logo_url	string \| null	Logo/icon image URL. Checked to load when last verified; null when no working logo is known, so show your own placeholder (e.g. the merchant's initial).
website	string \| null	e.g. `"https://netflix.com"`
domain	string \| null	e.g. `"netflix.com"`
mcc	string \| null	The merchant's usual Merchant Category Code, where known. e.g. `"5968"`
confidencerequired	number	How sure Tanzim is that `merchant_name` is right, 0 to 1. It is derived from the match method and similarity score, not a calibrated probability: treat >= 0.9 as reliable and anything lower as worth a human glance. Always 0 when `matched` is false. e.g. `0.99`
matchrequired	Match
counterparty	CounterpartyInfo \| null	For person-to-person transfers whose narration names the other person (IBFT / Raast / wallet title fetch): who it is. When present, `matched` is false unless a real merchant was identified.

ErrorBody

Field	Type	Description
coderequired	string	e.g. `"invalid_api_key"`
messagerequired	string
request_idrequired	string
details	array of map of string \| null	Per-field problems for `invalid_request`.

ErrorResponse

Field	Type	Description
errorrequired	ErrorBody

ExampleItem

Field	Type	Description
descriptionrequired	string
mcc	string \| null
noterequired	string
resultrequired	EnrichResult

ExamplesResponse

Field	Type	Description
engine_versionrequired	string
examplesrequired	array of ExampleItem

Identification

Field	Type	Description
spending_transactionsrequired	integer
identified_transactionsrequired	integer
identified_share_of_transactionsrequired	number
identified_share_of_spendingrequired	number	How much of the spending was matched to a known merchant, 0 to 1.
unidentified_toprequired	array of UnidentifiedItem	The biggest spending items Tanzim could not identify.

Insights

Field	Type	Description
summaryrequired	Summary
by_kindrequired	array of KindTotal
categoriesrequired	array of CategoryInsight
top_merchantsrequired	array of MerchantInsight
monthlyrequired	array of MonthInsight
recurringrequired	array of RecurringInsight	Repeating payments (subscriptions, bills) detected from the dates and amounts.
monthly_recurring_totalrequired	number
largest_transactionsrequired	array of LargeTransaction
counterpartiesrequired	array of CounterpartyInsight
payeesrequired	array of PayeeInsight	People you transact with, grouped across spellings, biggest first.
regular_unnamed_transfersrequired	array of RegularTransfer	Repeating transfers with the same amount whose statement line names nobody: likely the same person or account. A pattern, not an identified payee.
transfer_summaryrequired	TransferSummary
identificationrequired	Identification

KeyCreated

Field	Type	Description
keyrequired	string	The API key. Shown ONCE — store it now. e.g. `"tz_test_..."`
idrequired	string
prefixrequired	string	First characters of the key, to recognise it later.
environmentrequired	string	`test` for now. Test keys are rate limited and their inputs are logged to improve Tanzim.
created_atrequired	string
rate_limitsrequired	RateLimits
messagerequired	string

KeyRequest

Field	Type	Description
name	string \| null	What you're building (shown only to you). e.g. `"My budgeting app"`
email	string \| null	Optional, but lets us tell you about breaking changes and quota.
source	string \| null	Free-form label for where the key was requested from.

KindTotal

Field	Type	Description
kindrequired	string
countrequired	integer
debit_amountrequired	number
credit_amountrequired	number

LargeTransaction

Field	Type	Description
daterequired	string
descriptionrequired	string
amountrequired	number
merchant	string \| null
kindrequired	string

Match

Field	Type	Description
methodrequired	string	How the merchant was identified: `exact` (the whole string is a known name), `substring` (a known name appears inside it), `fuzzy` (a close misspelling/partial match), `mcc_fallback` (merchant unknown, category taken from the MCC you sent) or `none`. e.g. `"substring"`
matched_on	string \| null	The known name/alias that matched, normalised. Useful for debugging. e.g. `"NETFLIX COM"`

Me

Field	Type	Description
key_idrequired	string
prefixrequired	string
environmentrequired	string
name	string \| null
created_atrequired	string
rate_limitsrequired	RateLimits
usagerequired	Usage

MerchantInsight

Field	Type	Description
namerequired	string
category	string \| null
logo_url	string \| null
domain	string \| null
countrequired	integer
amountrequired	number
averagerequired	number
sharerequired	number
first_daterequired	string
last_daterequired	string

Field	Type	Description
api_versionrequired	string
contract_versionrequired	string
engine_versionrequired	string
environmentrequired	string
merchant_countrequired	integer	Merchants with a full profile.
alias_countrequired	integer	Distinct name variants the engine recognises.
categoriesrequired	array of CategoryCount
rate_limitsrequired	RateLimits
max_batch_sizerequired	integer

MonthInsight

Field	Type	Description
monthrequired	string	YYYY-MM
countrequired	integer
spendingrequired	number
transfers_outrequired	number
creditsrequired	number
netrequired	number

PayeeInsight

Field	Type	Description
payee_idrequired	string
namerequired	string	The fullest spelling seen, capitalisation normalised.
aliasesrequired	array of string	Other spellings of the same person seen on the statement.
banksrequired	array of string
channelsrequired	array of string
sentrequired	number	Total you sent them.
receivedrequired	number	Total they sent you.
sent_countrequired	integer
received_countrequired	integer
first_daterequired	string
last_daterequired	string
typical_sent	number \| null	Median amount you send them.
typical_interval_days	number \| null	Median days between transactions with them (needs 3 or more).
regularrequired	boolean	Three or more transactions across at least two months.
relationshiprequired	string	`you pay them`, `they pay you` or `two-way`.

RateLimits

Field	Type	Description
per_minuterequired	integer
per_dayrequired	integer
statements_per_hour	integer	Statement analyses (file uploads or /transactions/analyze calls) per hour.

Reconciliation

Field	Type	Description
method	string \| null	`running_balance`: every row was checked against the statement's balance column.
checked	integer	Rows that could be checked against the running balance.
matched	integer	Rows whose amount and direction agree with the running balance.
match_rate	number \| null	matched / checked. At or above 0.98 the parse is almost certainly right.
opening_to_closing_difference	number \| null	opening balance + credits - debits - closing balance. 0 when the statement adds up.
totals_match	boolean \| null	True when opening + credits - debits equals the closing balance.

RecurringInsight

Field	Type	Description
namerequired	string
category	string \| null
logo_url	string \| null
frequencyrequired	string	`weekly`, `fortnightly`, `monthly`, `quarterly` or `yearly`.
occurrencesrequired	integer
typical_amountrequired	number
amount_variesrequired	boolean	True for bills whose amount changes month to month (electricity, phone).
totalrequired	number
first_daterequired	string
last_daterequired	string
next_expectedrequired	string
monthly_costrequired	number	Typical amount converted to a per-month figure.
confidencerequired	string
likely_subscriptionrequired	boolean

RegularTransfer

Field	Type	Description
directionrequired	string	`debit` (you send) or `credit` (you receive).
amountrequired	number
countrequired	integer
totalrequired	number
first_daterequired	string
last_daterequired	string
typical_interval_days	number \| null
share_of_transfersrequired	number	Share of that direction's transfers that have this exact amount.

Revoked

Field	Type	Description
revokedrequired	boolean

StatementInfo

Field	Type	Description
formatrequired	string	`csv`, `xlsx`, `pdf` or `json`.
filename	string \| null
currencyrequired	string
transactionsrequired	integer	Transactions extracted.
rows_readrequired	integer
rows_skippedrequired	integer	Rows that were not transactions (totals, headers, notes) or could not be read.
confidencerequired	string	How much to trust the parse: `high`, `medium` or `low`. `high` means the statement's own balances check out.
warningsrequired	array of string	Human-readable problems found while parsing. Show them to the user.
period_start	string \| null
period_end	string \| null
reconciliation	Reconciliation \| null	Self-check against the statement's balances. null when the statement has no balance column.

StatementTransaction

Field	Type	Description
indexrequired	integer	Position in the statement, starting at 0.
date	string \| null
descriptionrequired	string
amountrequired	number	Always positive; see `direction`.
directionrequired	string	`debit` (money out), `credit` (money in) or `unknown`.
balance	number \| null
kindrequired	string	What sort of transaction this is: `merchant`, `transfer_in`, `transfer_out` (person-to-person), `cash`, `fee`, `income`, `interest`, `refund`, `bill_payment` or `unknown`.
counterparty	string \| null	The other person in a transfer, when the narration names them (capitalisation normalised).
payee_id	string \| null	Stable id of that person within this statement: different spellings of one name share it.
counterparty_bank	string \| null	The other person's bank or wallet, when shown.
channel	string \| null	`ibft`, `raast`, `wallet`, `transfer` or `card`.
identifiedrequired	boolean	True when the merchant was identified with confidence of at least 0.9. Weaker guesses stay in `enrichment` (show them as "possibly ...") but are not used for categories, merchants or kinds.
enrichmentrequired	EnrichResult	The same result `POST /v1/enrich` returns for this narration.

Summary

Field	Type	Description
currencyrequired	string
transaction_countrequired	integer
period_start	string \| null
period_end	string \| null
daysrequired	integer
total_debitsrequired	number	All money out, including transfers.
total_creditsrequired	number
netrequired	number	total_credits - total_debits.
spendingrequired	number	Money out excluding person-to-person transfers.
transfers_outrequired	number
transfers_inrequired	number
incomerequired	number	Credits recognised as salary/payroll.
average_daily_spendingrequired	number
average_transactionrequired	number	Average spending transaction.

TransactionIn

Field	Type	Description
daterequired	string	Transaction date: 2026-01-31, 31/01/2026 (day first), 31-Jan-2026 and similar are understood. e.g. `"2026-01-31"`
descriptionrequired	string	The narration exactly as the statement shows it. e.g. `"POS/KHAADI PKG MALL LHR PK"`
amountrequired	number \| string	Amount. A number (negative = debit when `direction` is omitted) or text such as "1,250.00 Dr" or "(1,250.00)". e.g. `1250.0`
direction	string \| null	If you know it. Otherwise it is inferred from the sign, a Dr/Cr marker or the balance.
balance	number \| string \| null	Running balance after this transaction, if you have it. It makes direction detection and the self-check far more reliable.

TransactionsRequest

Field	Type	Description
transactionsrequired	array of TransactionIn
currency	string \| null	ISO currency code, used for labelling only.

TransferSummary

Field	Type	Description
transfersrequired	integer
namedrequired	integer	Transfers where the statement names the other person.
named_sharerequired	number	Many statements print only a reference, not a name: when this is low, `regular_unnamed_transfers` is the useful view.

UnidentifiedItem

Field	Type	Description
descriptionrequired	string
countrequired	integer
amountrequired	number

Usage

Field	Type	Description
last_24hrequired	integer	Transactions enriched with this key in the last 24 hours.

Errors

Every error has the same shape and an X-Request-Id header:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is unknown or has been revoked.",
    "request_id": "req_…"
  }
}

code	HTTP	Meaning
invalid_request	400	The request body or a parameter is missing or malformed. `details` lists the offending fields.
missing_api_key	401	No API key was sent. Use `Authorization: Bearer <key>` or `X-API-Key: <key>`.
invalid_api_key	401	The API key is unknown or has been revoked.
not_found	404	No such endpoint.
method_not_allowed	405	That endpoint does not support this HTTP method.
payload_too_large	413	The request body is too large (1 MB for most endpoints; statements may be larger, see /v1/meta).
rate_limited	429	Too many requests. Wait `Retry-After` seconds, then retry.
unsupported_file	415	That file type isn't supported. Upload a PDF, CSV or Excel (.xlsx) statement.
statement_unreadable	422	The file was read but no transactions could be extracted (for example a scanned PDF, a password-protected PDF, or a file that isn't a statement). `details[].reason` says which.
internal_error	500	Something went wrong on our side. Quote the `request_id` if you contact us.

Branch on error.code, not on the message text.

Rate limits

Test keys: 120 transactions per minute and 10000 per day (a batch of N counts as N). Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds); a 429 includes Retry-After. Batches take up to 100 items.

Integration tips

Any language works. It is plain REST + JSON. For a typed client, generate one from /v1/openapi.json (e.g. openapi-generator, openapi-typescript, oapi-codegen) or import that URL into Postman/Insomnia. Minimal dependency-free clients for Python and JavaScript are in backend/sdk/.
Retries are safe. Enrichment is read-only and idempotent: retry 429 (after Retry-After) and 5xx with backoff.
Batch when you can. One request for 100 transactions beats 100 requests.
Use confidence. ≥ 0.9 is reliable; lower deserves a human glance or a "suggested" label in your UI.
Send the whole string exactly as the bank gave it, noise and all. Don't pre-clean it; the engine does that.
Send mcc when you have it. It gives a category even for merchants we don't know yet.
Ignore unknown fields in responses so additive improvements never break you.

Data & privacy

Test-key requests are logged with their input so we can improve matching; live keys never store your inputs. Don't send real personal data from test keys. Failed and low-confidence enrichments are reviewed to add missing merchants, which is how coverage improves over time.

Machine-readable

/v1/openapi.json — OpenAPI 3 contract (drives these docs)
/docs/swagger — interactive Swagger UI
/v1/meta — engine version, merchant counts, categories, limits
/v1/examples — live sample inputs and outputs

API documentation

Overview

Quickstart

Analyse a bank statement

Authentication

Endpoints

GET/v1/health

GET/v1/meta

GET/v1/examples

POST/v1/keys

GET/v1/me

DELETE/v1/keys/current

POST/v1/enrich

POST/v1/enrich/batch

POST/v1/statements/analyze

POST/v1/transactions/analyze

Objects

AnalysisResponse

BatchRequest

BatchResponse

Body_analyze_statement_file_statements_analyze_post

CategoryCount

CategoryInsight

CounterpartyInfo

CounterpartyInsight

EnrichRequest

EnrichResponse

EnrichResult

ErrorBody

ErrorResponse

ExampleItem

ExamplesResponse

Identification

Insights

KeyCreated

KeyRequest

KindTotal

LargeTransaction

Match

Me

MerchantInsight

Meta

MonthInsight

PayeeInsight

RateLimits

Reconciliation

RecurringInsight

RegularTransfer

Revoked

StatementInfo

StatementTransaction

Summary

TransactionIn

TransactionsRequest

TransferSummary

UnidentifiedItem

Usage

Errors

Rate limits

Integration tips

Categories

Data & privacy

Machine-readable