API and MCP server
Work with invoices, estimates and clients from your own code, or connect Claude and other AI assistants with MCP.
Tidy Invoicer has a JSON API for your own scripts and integrations, and an MCP server so AI assistants such as Claude can work with your invoices for you. Both do the same things: list, read, create and change invoices, estimates and clients, mark invoices paid, download PDFs, and see what you are owed.
Billing, your team and deleting a company are not available through either. Do those in the app.
API tokens
Open the account menu and choose API tokens. Give the token a name (such as what will use it) and click Create token. Copy it straight away: it is shown once, and Tidy Invoicer keeps only a fingerprint of it, so nobody can show it to you again.
- A token works in the company you were working in when you made it, as you. It sees exactly what you see there, and nothing in your other companies.
- The list shows when each token was last used. Revoke stops one at once. Leaving a company ends your tokens for it.
- Treat a token like a password. Anyone who has it can read and change that company's documents and clients.
- An admin helping you with "Log in as" cannot make or revoke tokens for you.
Send the token in the Authorization header of every request:
curl https://tidyinvoicer.com/api/v1/documents?status=overdue \
-H "Authorization: Bearer tidy_YOUR_TOKEN"
The JSON API
The address is https://tidyinvoicer.com/api/v1. Requests and responses are JSON; send Content-Type: application/json with a body. The full description, with every field, is the OpenAPI 3.1 file at https://tidyinvoicer.com/api/v1/openapi.json, which most API tools can import.
GET /documents: invoices and estimates, newest first. Filter withkind(invoice, estimate),status(draft, sent, paid, accepted or overdue),client_id,q(search),issued_fromandissued_to.POST /documents: a new draft, withkindand any other fields. It starts from your default template for the kind, with the next number and today's date, as New invoice does. Giveclient_idto fill in a saved client's addresses and currency.GET,PATCHandDELETE /documents/{id}: read, change or delete one. APATCHchanges only the fields you send;items,custom_fieldsandbank_fieldsreplace the whole list.POST /documents/{id}/mark-paid: marks an invoice paid, with an optionalpaid_ondate.GET /documents/{id}.pdf: the PDF, exactly as the app makes it.GET,POST,PATCHandDELETEon/clientsand/clients/{id}: your saved clients.GET /money-summary: outstanding, overdue and paid this month, as on the Documents page.
curl https://tidyinvoicer.com/api/v1/documents \
-H "Authorization: Bearer tidy_YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"kind": "invoice", "client_id": 12, "due_on": "2026-12-31",
"items": [{"description": "Website redesign", "quantity": 1, "unit_price": "1200.00"}]}'
Amounts are strings with two decimals, such as "1200.00", in each document's own currency. Dates are written 2026-12-31.
Lists
Lists come a page at a time, 25 rows unless you ask for up to 100 with per_page. Ask for the next with page:
{ "data": [ ... ], "meta": { "page": 1, "per_page": 25, "total_count": 61, "total_pages": 3 } }
A single record comes as { "data": { ... } }.
Errors
Every error has the same shape. code is meant for programs and never changes; message is for people; details names each field that was wrong.
{ "error": { "code": "validation_failed", "message": "Number is already used",
"details": [ { "field": "number", "message": "is already used" } ] } }
invalid_request(400): a field is unknown or has the wrong type. Unknown fields are refused rather than ignored, so a typo does not go unnoticed.unauthorized(401): the token is missing, wrong or revoked.plan_limit_reached(402): see below.not_found(404): nothing with that id in the token's company. Records in your other companies count as not found.validation_failed(422): nothing was saved.rate_limited(429): wait for the number of seconds in theRetry-Afterheader.
Limits
Each token can make 120 requests a minute. On the Free plan the API counts toward the same 3 new documents a month as the app (see Plans and billing); past that, creating a document fails with plan_limit_reached until the next month or until you upgrade. Reading, changing and PDFs are never limited.
Connecting Claude (MCP)
The MCP server is at https://tidyinvoicer.com/mcp, using the Streamable HTTP transport. Its tools match the API: list_documents, get_document, create_document, update_document, mark_document_paid, delete_document, get_document_pdf, list_clients, get_client, create_client, update_client, delete_client, get_money_summary.
Claude
In Claude, click Add, then Connect, then Allow here.
Claude Code
claude mcp add --transport http tidy-invoicer https://tidyinvoicer.com/mcp
Then run /mcp in Claude Code, choose tidy-invoicer and sign in in the browser it opens. To use an API token instead, add --header "Authorization: Bearer tidy_YOUR_TOKEN".
The Claude API
With the MCP connector in the Messages API, pass an API token as the server's authorization_token:
"mcp_servers": [{ "type": "url", "url": "https://tidyinvoicer.com/mcp", "name": "tidy-invoicer",
"authorization_token": "tidy_YOUR_TOKEN" }],
"tools": [{ "type": "mcp_toolset", "mcp_server_name": "tidy-invoicer" }]
Send it with the anthropic-beta: mcp-client-2025-11-20 header.
An assistant can change and delete things with these tools, as you could. Most ask before using a tool; keep that on for anything that deletes.
OAuth for other apps
Any app can connect the way Claude does, with OAuth 2.1. A request without a token is refused with a WWW-Authenticate header whose resource_metadata leads to https://tidyinvoicer.com/.well-known/oauth-protected-resource and from there to https://tidyinvoicer.com/.well-known/oauth-authorization-server, which lists:
POST /oauth/register: dynamic client registration (RFC 7591). Register as a public client with"token_endpoint_auth_method": "none", or leave it out to get aclient_secret. Redirect addresses must be https, http on localhost, or the app's own scheme.GET /oauth/authorize: the authorization code flow. PKCE withS256is required. The person chooses one company, and the tokens work only there.POST /oauth/token: swaps the code, within 1 minute, for an access token that lasts 1 hour and a refresh token. Each refresh gives a new refresh token and ends the old one; using an old one again ends the connection. A connection unused for 90 days has to be allowed again.POST /oauth/revoke: ends a connection (RFC 7009).
Access tokens are sent like API tokens, as Authorization: Bearer, and work with both the JSON API and the MCP server. An admin using "Log in as" cannot connect apps for someone.