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.