Tally2AI / Documentation

Build with the REST API

An authenticated local JSON interface to the running Tally XML service.

Find your local base URL

Open Tally connection → Advanced: connection settings in the installed bridge for its actual REST URL. The installer selects and saves an available loopback port. At that base URL, /docs is the local explorer and /openapi.json is the exact OpenAPI contract for your installed version. The public website does not expose your accounting API.

Pair your client

Send POST /auth/pairings with the JSON below. Retain the returned id, private pollSecret and expiry; show the user the userCode.
The owner opens Advanced connections → Connection requests, matches the code, and approves the intended companies, requested scopes and expiry.
Send POST /auth/pairings/{id}/claim with {"pollSecret":"<private polling secret>"}. Pending returns 202. After approval the credential is returned once.

POST /auth/pairings
Content-Type: application/json

{"name":"My local integration","scopes":["read"]}

Pairings expire after five minutes. Store the approved credential securely and send it in the Authorization header, never a URL. If a successful claim is lost, revoke that connection and pair again deliberately.

Make a first read

GET /api/v1/companies
Authorization: Bearer <approved-app-credential>

GET /api/v1/companies/<company-guid>/masters/ledgers?limit=25&offset=0
Authorization: Bearer <approved-app-credential>

Use the exact approved native GUID returned by discovery and URL-encode path IDs. Tally must be running with that company loaded. Company names or voucher numbers are not reliable substitutes for unique record identity.

Core route families

Route	Purpose
`GET /health/live`	Bridge liveness; no data credential required.
`GET /health/ready`	Authenticated Tally readiness.
`GET /api/v1/capabilities`	Resources, report catalog and coverage limits.
`/api/v1/companies/{companyId}/masters/{kind}`	Supported masters: list/create; record routes read/alter/delete.
`/api/v1/companies/{companyId}/vouchers`	Voucher list/create; record routes read/alter/delete/cancel.
`/api/v1/companies/{companyId}/reports/{report}`	Allowlisted native report exports; validate period and selection semantics.
`/api/v1/operations/{operationId}`	Inspect a mutation; POST to its `/reconcile` route for readback.

Reads and freshness

List responses contain data and meta, including source, fetched time, pagination and staleness. Explicit consistency=cached needs a saved snapshot of the exact request. Cached reads never silently refresh. Pagination is over a bounded extraction, not a stable multi-page snapshot of a company being edited.

Before enabling writes

Use the applicable write or delete permission and an approved, durably bound company. Only the owner binds company GUIDs.
Send a unique Idempotency-Key of 8–200 characters for each intended mutation. Do not recycle it for a different payload.
For PATCH, DELETE or cancellation, fetch the current record and send its exact latest ETag as If-Match.
Check record prerequisites, company features and meaningful financial readback. The native field catalog is not universal workflow certification.

Unknown is not success. A 202 response with an unknown operation outcome requires journal inspection and reconciliation. Never blindly resend it. Tally sits outside the journal’s database transaction, so there is no exactly-once guarantee.

Coverage limits

No raw XML execution, arbitrary TDL, company creation, OAuth or statutory filing endpoint is exposed. Payroll, manufacturing, advanced inventory, report periods, alternate Tally builds and other specialized workflows need their own validation. Use the installed OpenAPI contract and capabilities for exact supported input shapes.