The Recon Output Envelope
The canonical JSON output of every TransactIG reconciliation run. One endpoint, one document, every figure delivered as an exact decimal string. Section-by-section reference with a full worked example — the contract you can build against.
The endpoint
The envelope has one endpoint. It returns the envelope for a completed reconciliation run.
GET /runs/{run_id}/envelope
Returns the envelope for a completed reconciliation run. The run_id
is the identifier surfaced in the dashboard and returned by the run-creation path. Only completed
runs return an envelope — a run still in progress returns a state indication, not a partial envelope.
Tenant-scoped, always
Every request is scoped to your organisation's API key; you can only ever see your own runs. Tenant isolation is absolute.
The isolation is structural, not policy. There is no configuration knob to widen visibility across
organisations, no support-side "impersonate another tenant" mode, and no aggregation surface that
spans tenants. If you present a key belonging to organisation A, you cannot fetch a run belonging to
organisation B — irrespective of whether you know its run_id.
Error semantics — the two deliberate 404s
The endpoint returns two error shapes. Both are 404s. Neither is accidental — the shape is the contract.
The identical shape between "unknown" and "cross-tenant" is deliberate. If the two responses differed, an attacker with any valid API key could probe the id space and learn which run identifiers belong to other organisations — a tenant-boundary leak by side-channel. Returning the same 404 for both cases removes the side-channel entirely.
File artifact — one contract, two transports
The same envelope can be written as a per-run file artifact to your organisation's secure file area — for SFTP-style consumers who prefer files to APIs. One contract, two transports.
The file is byte-identical to the API response for the same run: same JSON, same field ordering,
same money strings, same schema_version.
An integrator can start with SFTP pickup, graduate to the API without any downstream parser change,
or run both transports side-by-side during a migration.
Envelope structure
schema_version: "1.0".
Each section carries a specific class of information; the table below is the map, and each section
has a worked example immediately after.
One complete envelope, top to bottom
A full envelope for organisation "Example Traders Pvt Ltd", financial year 2025-26, month of
January 2026 — with two active modules: bank reconciliation and GSTR-2B versus purchase register.
All figures are illustrative synthetic data. Money values are decimal strings; input files carry
SHA-256 fingerprints; the placeholder posting_proposals
section returns the "next release" reason.
View the complete worked-example envelope (JSON)
{
// All figures illustrative — synthetic data for documentation.
"schema_version": "1.0",
"manifest": {
"run_id": "run_2026_01_ex_00042",
"organisation": {
"id": "org_example_traders",
"name": "Example Traders Pvt Ltd"
},
"period": {
"financial_year": "2025-26",
"month": "2026-01",
"from": "2026-01-01",
"to": "2026-01-31"
},
"input_files": [
{
"role": "bank_statement",
"filename": "hdfc_current_202601.mt940",
"sha256": "b1f4c9e2a7d3f5b8c1e0a2d4f6b8a1c3e5d7f9b2c4a6e8d0f2b4c6e8a0d2f4b6",
"row_count": 1247
},
{
"role": "book_ledger",
"filename": "tally_bank_ledger_202601.xlsx",
"sha256": "c9e2a7d3f5b8c1e0a2d4f6b8a1c3e5d7f9b2c4a6e8d0f2b4c6e8a0d2f4b6b1f4",
"row_count": 1189
},
{
"role": "gstr_2b",
"filename": "GSTR2B_29XXXXX1234X1ZX_012026.json",
"sha256": "e2a7d3f5b8c1e0a2d4f6b8a1c3e5d7f9b2c4a6e8d0f2b4c6e8a0d2f4b6b1f4c9",
"row_count": 342
},
{
"role": "purchase_register",
"filename": "purchase_register_202601.xlsx",
"sha256": "a7d3f5b8c1e0a2d4f6b8a1c3e5d7f9b2c4a6e8d0f2b4c6e8a0d2f4b6b1f4c9e2",
"row_count": 358
}
],
"configuration_version": "cfg-example",
"engine_version": "eng-example",
"generated_at": "2026-02-03T07:45:00+05:30"
},
"integrity": {
"identities": [
{
"name": "bank_vs_book_totals",
"description": "Sum of bank statement debits and credits reconciles to book ledger",
"figures": {
"bank_debits_total": "8420350.00",
"bank_credits_total": "12680000.00",
"book_debits_total": "8420350.00",
"book_credits_total": "12680000.00",
"difference": "0.00"
},
"status": "pass"
},
{
"name": "opening_plus_movement_equals_closing",
"description": "Opening balance + net movement equals closing balance on both sides",
"figures": {
"opening_balance": "3250000.00",
"net_movement": "4259650.00",
"expected_closing": "7509650.00",
"actual_closing": "7509650.00",
"difference": "0.00"
},
"status": "pass"
}
]
},
"discovered_money": {
"headline_total": "1425000.50",
"currency": "INR",
"buckets": {
"recoverable": {
"total": "612500.00",
"item_count": 14
},
"stuck": {
"total": "525000.00",
"item_count": 9
},
"at_risk": {
"total": "202500.50",
"item_count": 6
},
"compliance": {
"total": "85000.00",
"item_count": 3
}
},
"by_stream": [
{
"stream": "bank-reconciliation",
"total": "737500.50",
"buckets": {
"recoverable": "412500.00",
"stuck": "325000.00",
"at_risk": "0.00",
"compliance": "0.00"
}
},
{
"stream": "gst-2b",
"total": "687500.00",
"buckets": {
"recoverable": "200000.00",
"stuck": "200000.00",
"at_risk": "202500.00",
"compliance": "85000.00"
}
}
]
},
"modules": [
{
"stream": "bank-reconciliation",
"kpis": {
"bank_rows_processed": 1247,
"book_rows_processed": 1189,
"matched_rows": 1156,
"unmatched_bank_rows": 91,
"unmatched_book_rows": 33
},
"result_rows": [
{
"row_id": "br-0001",
"row_type": "matched",
"bank_ref": "UTR HDFC0026012600123456",
"book_ref": "V-JAN-00312",
"amount": "84500.50",
"date": "2026-01-14",
"counterparty": "Sundar Enterprises"
},
{
"row_id": "br-0002",
"row_type": "unmatched_bank",
"bank_ref": "NEFT SBIN2026010800789",
"amount": "125000.00",
"date": "2026-01-08",
"narration": "NEFT CR-SBIN0000001-INDIRA TEXTILES-INV JAN2026"
}
],
"exceptions": [
{
"exception_id": "br-ex-0007",
"amount": "125000.00",
"narrative": "Bank credit of ₹1,25,000.00 on 2026-01-08 from Indira Textiles has no matching entry in the book ledger for January. The customer name in the narration matches an active vendor; likely an unbooked receipt awaiting AR posting.",
"bucket": "stuck",
"suggested_action": "Book the receipt against invoice INV-JAN-2026-119 (matches on amount and counterparty)."
}
]
},
{
"stream": "gst-2b",
"kpis": {
"gstr2b_invoices": 342,
"purchase_register_invoices": 358,
"matched_invoices": 328,
"gstr2b_only": 14,
"purchase_only": 30
},
"result_rows": [
{
"row_id": "gst-0001",
"row_type": "matched",
"gstin": "29XXXXX1234X1ZX",
"supplier": "Bharat Steel Traders",
"invoice_no": "BST/2025-26/1047",
"invoice_date": "2026-01-12",
"taxable_value": "450000.00",
"cgst": "40500.00",
"sgst": "40500.00",
"igst": "0.00"
},
{
"row_id": "gst-0044",
"row_type": "purchase_only",
"supplier": "Silverline Components",
"invoice_no": "SL/25-26/0782",
"invoice_date": "2025-08-10",
"taxable_value": "125000.00",
"igst": "22500.00"
}
],
"exceptions": [
{
"exception_id": "gst-ex-0031",
"amount": "22500.00",
"narrative": "Invoice SL/25-26/0782 from Silverline Components (₹1,25,000 + ₹22,500 IGST) is present in the purchase register but has not yet appeared in the corresponding GSTR-2B. The exception is flagged for finance-team review against your organisation's ITC policy.",
"bucket": "at_risk",
"suggested_action": "Confirm the supplier's GSTR-1 filing status with the vendor."
},
{
"exception_id": "gst-ex-0044",
"amount": "85000.00",
"narrative": "Two invoices from Newvision Distributors carry a trade-discount treatment inconsistent with the return already filed. The exception surfaces the amount and the affected supplier so your finance team can decide the remediation path with your CA.",
"bucket": "compliance",
"suggested_action": "Review with your CA and remediate per your organisation's filing policy."
}
]
}
],
"drawer_payloads": [],
"posting_proposals": {
"items": [],
"reason": "Write-back is scheduled for the next release. This section is a placeholder to preserve contract stability."
},
"provenance": {
"figures": [
{
"path": "discovered_money.by_stream[0].total",
"sources": [
{
"input_file": "hdfc_current_202601.mt940",
"reference": "MT940 lines 4–1250"
},
{
"input_file": "tally_bank_ledger_202601.xlsx",
"reference": "Sheet 'Bank_Ledger' rows 2–1190"
}
]
},
{
"path": "modules[1].exceptions[0].amount",
"sources": [
{
"input_file": "purchase_register_202601.xlsx",
"reference": "Sheet 'Purchases' row 217"
},
{
"input_file": "GSTR2B_29XXXXX1234X1ZX_012026.json",
"reference": "b2b invoices — supplier GSTIN not present"
}
]
}
]
}
}The illustrative header comment at the top of the block is repeated verbatim in every published example on the site — envelopes shown in documentation are never derived from real client data. When your organisation runs its first reconciliation, the shape of the envelope you receive is the same as this one; the values are yours.
Money precision — the parsing contract
Every money value in the envelope is a JSON string, never a JSON number. The contract exists so that no downstream system can silently corrupt figures through floating-point rounding.
If you're parsing this envelope, never coerce money through binary floating point.
"1250000.00"
is safe; 1250000
(parsed as a JavaScript number) is not.
Read every money field as a string and hand it directly to a decimal library —
decimal.Decimal
in Python, BigDecimal
in Java or Kotlin, decimal.js
in JavaScript, or the platform equivalent. Every field named as a monetary amount in this
envelope obeys the same rule, including nested figures inside module rows and provenance
references.
ERP/CRM write-back
Posting proposals will flow to SAP/Oracle/Salesforce-class targets under an approval workflow that is held-by-default — nothing posts to your ERP without an explicit human approval.
Each delivery returns a per-delivery acknowledgement recording accept/reject and the approver identity.
The full write-back contract ships in the next release.
The rest of the developer documentation
Getting data in
The file formats TransactIG ingests, delivery mechanisms (upload, SFTP, API), and how the onboarding process maps your file shapes once.
The integration process
Six stages from discovery to go-live. What we ask you for, and what you receive at each stage.
Versioning, determinism & audit
Schema versioning is additive-only. Same inputs plus same configuration always produce a byte-identical envelope. The audit-grade property, stated plainly.
Ready to receive the envelope on your own reconciliation?
Envelope delivery is enabled per-tenant during onboarding. ISO 27001:2022 certified. Configured, not coded — no application development required on your side.