Skip to main content

The HTTP API

uninvoice.app exposes an HTTP API so you can create entities (clients and suppliers), draft and issue invoices, download their PDFs, and read your company configuration from your own tools and integrations. The same API powers the web app.

This section covers authentication and the conventions shared by every endpoint. The full list of endpoints is in the Endpoint reference. If you drive the API from an AI agent, see the MCP server, which exposes the same operations over the Model Context Protocol.

Base URL​

The API is versioned under /v1:

EnvironmentBase URL
Productionhttps://api.uninvoice.app

Every path in the reference is relative to this base, for example GET /v1/invoices.

Authentication​

All API requests authenticate with a Bearer token in the Authorization header:

Authorization: Bearer <token>

The token is an API token: a long-lived UUID that identifies a user acting within a company. API tokens do not expire; they stay valid until you delete them. Use one for anything running outside a browser: integrations, scripts, and MCP clients.

Requests with no token, an unknown token, or a deleted token receive 401 Unauthorized.

Creating an API token​

Create and manage your API tokens from the Company section of your settings in the web app. There you can issue a new token, give it a description, see the tokens already active, and revoke any you no longer need.

A token's value is shown once, at creation: copy it then and store it securely; treat it like a password. It looks like 3f2b1c9a-...-a1b2c3d4e5f6; send it as the Bearer credential on every request.

A token is scoped to one user within one company. Every call it makes acts as that user in that company; there is no way to switch company on an API token.

Acting as a human or as an AI​

By default an API token is treated as an AI: its mutating requests (creating or issuing an invoice, deleting a proforma, …) don't run immediately: they are held for a person to approve through AI Audit, and the API replies 202 pending_approval.

When you create a standard token you also receive a one-time human proof secret (humanProof). Presenting it in the X-Human-Proof header asserts that a human is driving the request, so it runs immediately and is not audited. Use it for automations a person genuinely supervises. A token created for an MCP client is AI-driven and gets no human proof, so it is always gated. See AI Audit for the full flow.

Conventions every endpoint follows​

These conventions apply across all endpoints.

JSON​

Requests and responses are JSON. Field names use snake_case (e.g. recipient_id, unit_price), except for a small number of metadata fields that are explicitly camelCased (e.g. createdAt).

Money​

Monetary amounts are integers in the currency's minor unit (cents), never floats. unit_price, subtotal, tax_amount, and invoice total are all in cents. For example, €1,250.00 is 125000. Currencies are ISO 4217 codes (currency_code, e.g. EUR).

Dates and times​

Timestamps are RFC 3339 / ISO 8601 in UTC (e.g. 2026-07-03T10:00:00Z).

Errors​

Errors use standard HTTP status codes. Most carry a plain-text message body:

StatusMeaning
400 Bad RequestThe request is malformed or fails a business rule. The body describes what to fix.
401 UnauthorizedMissing, invalid, or revoked token.
403 ForbiddenAuthenticated, but not allowed to perform this action.
404 Not FoundThe resource does not exist, or is not visible to your company.
500 Internal Server ErrorUnexpected server error.

Some 403 responses that require a specific follow-up action return a JSON body with a machine-readable error code and a human message, for example:

{
  "error": "verifactu_authorization_required",
  "message": "You must authorize uninvoice.app to report on your behalf before issuing invoices.",
  "requiresAuthorizationUrl": "/verifactu/authorization"
}

Codes you may encounter: company_not_settled (finish company onboarding first), agreement_required (accept the current legal terms first), verifactu_authorization_required (grant the Veri*Factu authorization first).

What a token can and cannot do​

An API token can read and write the resources of its company: entities, invoices, proformas, taxes, company configuration, and the Veri*Factu authorization status.

Continue to the Endpoint reference.