Notice This app is in Beta Testing We are still testing Taxesfiler, so features may change.

Developer platform

Tax compliance, as an API your product calls.

The same deterministic engine, the same versioned rules and the same audit trail that the application uses — reachable from your own software, under your own interface. Every response carries the rule version that produced it, so a figure you render to your users can be explained later.

REST API

Versioned, scoped, and honest about failure.

Every endpoint returns the rule versions its answer depended on. An endpoint that cannot reach what it needs returns a 503 naming what is unavailable rather than a plausible answer computed from less — a tax figure derived from a partial corpus is worse than no figure, because nothing downstream can tell the difference.

Method Path What it does Scope
GET /api/v1/jurisdictions The jurisdiction tree, with authorities. read
GET /api/v1/jurisdictions/:code One jurisdiction, its children and its authorities. read
GET /api/v1/rules Search the rule corpus.

Filter by jurisdiction, tax type and free text.

read
GET /api/v1/rules/:code/at/:date The version of a rule in force on a date.

There is no endpoint that returns 'the current rule' without a date. Every caller that wanted one would be computing last year's return with this year's law. Every version carries `quotable`: false means no tax professional has checked it against the authority's own publication, and it may not produce a filed figure.

read
GET /api/v1/rules/:code/versions A rule's full version history. read
POST /api/v1/tax/classify Determine a transaction's tax treatment from its facts.

Returns the rule versions the treatment depended on. When the engine cannot determine a treatment it answers 200 with `treatment: "unknown"` and the facts that would settle it — there is nothing to retry.

calculate
POST /api/v1/tax/calculate Compute a liability from a set of facts.

Deterministic. No model is involved in the arithmetic.

calculate
POST /api/v1/tax/suggest-category Suggest taxonomy categories for a description.

Keyword matching over the taxonomy's own hints — free, instant and identical every time. Returns the facts and evidence each category will need, so an integrator can collect them at capture time.

calculate
GET /api/v1/tax/requirements/:category What evidence a category's treatment requires.

Documents and facts, because a receipt cannot answer 'who was at the lunch'.

read
POST /api/v1/tax/scenario Compare the tax consequences of alternatives.

Stores nothing. `comparable` is false when any alternative could not be computed — half an answer is not a comparison.

calculate
GET /api/v1/taxpayers/:id A taxpayer's profile, registrations and residencies. read
GET /api/v1/taxpayers/:id/position The computed position for a tax year.

`taxable_profit` is null whenever anything could not be determined, with the gaps in `undetermined`. Treating null as zero would file the wrong number.

read
GET /api/v1/taxpayers/:id/obligations Derived obligations with their deadlines.

`undatable` counts the obligations Taxesfiler is confident exist and cannot date. Their `due_on` is null and their state is `uncertain`.

read
POST /api/v1/documents Submit a document for classification and extraction.

Raw body, or base64 in `content_base64`. Returns 202 immediately — nothing has been read yet, and an extraction returned synchronously would be a partial one.

edit
GET /api/v1/documents/:id A document's state, extraction and matched transactions. read
POST /api/v1/transactions Record a transaction, with or without a supporting document. edit
GET /api/v1/transactions/:id/trace The full chain from a figure back to its source document.

The transaction, the documents matched to it, every evidence requirement and whether it is discharged, and the determination with its rule version.

read
POST /api/v1/returns Create a return for a taxpayer, jurisdiction and period. edit
GET /api/v1/taxpayers/:taxpayer_id/returns A taxpayer's returns, newest first.

Exists so a client does not have to guess which returns exist. Guessing which return covers a period is how somebody ends up looking at last year's while this year's deadline passes.

read
GET /api/v1/returns/:id A return, its state, its figures and whether it can be filed. read
POST /api/v1/returns/:id/compute Set a return's figures and fill its form.

Returns both `values` and `unresolved`. A client reading only the first would show a form with holes in it as a finished one.

calculate
POST /api/v1/returns/:id/validate Check a return without submitting it. calculate
POST /api/v1/returns/:id/approve Approve a return for filing.

Requires a human actor. A machine key cannot reach this — use a delegated key.

approve
POST /api/v1/returns/:id/sign Sign a return.

The signature binds to the return's content hash. Any later change to the figures leaves it no longer covering them, and filing is refused.

sign
POST /api/v1/returns/:id/file Transmit a return to its authority, or prepare it for manual lodgement.

Requires an `Idempotency-Key` header. Refused without one rather than risking a double submission. For an authority with no route the response is a prepared submission whose status line begins NOT YET FILED.

file
POST /api/v1/returns/:id/amend Create a new version of a filed return, with a stated reason. amend
GET /api/v1/returns/:id/graph The version graph for a period, as a tree. read
GET /api/v1/filings/:id A return's submissions, their status lines and any confirmations. read
POST /api/v1/submissions/:submission_id/confirm-lodgement Record that a person lodged a prepared return themselves.

For the channels Taxesfiler cannot transmit on. `lodged_on` is the date they lodged it, not the date they told us.

file
GET /api/v1/events The tenant's event log from a sequence cursor. The sync read path.

The cursor is a bigserial, not a timestamp — two events can share a microsecond, and a resuming client would skip one or replay both.

read
GET /api/v1/audit The tenant's audit ledger, with each row's hash and its predecessor. read
GET /api/v1/webhooks The tenant's registered endpoints. read
POST /api/v1/webhooks Register an endpoint and choose the events it receives.

HTTPS only, and a private address is refused. The signing secret is returned once — verify every delivery's signature including its timestamp, or a captured request can be replayed against you.

edit
GET /api/v1/contract The UI contract: domain shapes, states, error codes, design tokens.

What the native clients generate from, so web, iOS, Android and desktop are one product rather than four. ETag is the contract's content hash.

public
GET /api/v1/health Liveness, and which partner integrations are configured.

The only endpoint that needs no credential.

public

Scopes

The same ladder the application uses.

An API key holds a subset of these. The rungs above approve carry legal consequences, so a key can only hold them if the tenant has explicitly enabled machine filing and named a human signer — and even then, never through MCP.

view

See that something exists, without its contents.

read

Read records, documents and the rule corpus.

calculate

Run classification, calculation and validation. Writes nothing.

edit

Create and change records, upload documents, record transactions.

approve Human only

Assert that a return has been reviewed and is correct.

sign Human only

Sign a return, with the personal liability that carries.

file Human only

Transmit a return to a revenue authority.

amend Human only

Restate a filed position.

withdraw Human only

Withdraw a filing.

access_tax_authority Human only

Use a credential held with an authority directly.