Developer API

The NumNum API lets you create documents programmatically in your own NumNum environment. Once created, you can send those documents by email, Peppol or post, exactly like documents you create manually.

The API is meant for server-to-server integrations, for example:

E-commerce: automatically create an invoice after an online sale
ERP / CRM: create invoices from your existing system
Self-billing: periodic settlements (purchase borderelles) for your suppliers, e.g. cooperatives or producers
Custom workflows: build invoice creation into your own application

What can the API do?

The API is write-only: you use it to create documents. There are three endpoints:

What	Endpoint	Documentation
Create sales invoices	`POST /api/v1/webhooks/create-invoice`	Create invoices
Create an issued purchase borderelle (self-billing)	`POST /api/v1/webhooks/create-purchase-borderelle`	Self-billing / purchase borderelle
Create a credit note on a purchase borderelle	`POST /api/v1/webhooks/create-purchase-borderelle-creditnote`	Self-billing / purchase borderelle

What is not possible via the API

To set expectations clearly:

❌ Reading, updating or deleting documents is not possible with your personal API token. The API only creates documents.
❌ Supplying your own document numbers is not possible: NumNum numbers documents automatically according to your company settings (legally required uninterrupted sequence).
❌ Idempotency is not built in: sending the same payload twice creates two documents. Track what you already submitted yourself (e.g. via the reference field or the returned IDs).

ℹ️ Sending via Peppol or email is not part of this API; it happens afterwards in the app or your usual sending flow.

Access

You generate your API token yourself on the My APIs page in your company settings (see Authentication). Don’t see that page? Contact support (help@numnum.be).

Authentication

Every API request needs two headers: your personal API token and the company you are working for.

1. Personal API token

Log in to NumNum
Go to Settings → Connections → My APIs (https://app.numnum.be/company/connection/myapi)
Click Generate API token

A few important properties:

The token is a string of exactly 64 characters (digits and letters). Always copy the full value as shown on the page; it stays visible there until you generate a new one.
The token belongs to your user, not to a single company. The same token works for every company you have access to; you pick the company per request via the X-Company-Id header.
There is no separate “revoke” button: clicking Generate API token again creates a new token and immediately invalidates the previous one.
Treat the token like a password: store it in an environment variable / secrets manager, never share it by email or chat, and never commit it to git.

2. Company ID

Your X-Company-Id determines in which company the document is created. You can find it:

next to your token on the My APIs page, or
in the NumNum URL (e.g. https://app.numnum.be/company/12345/... → Company ID = 12345).

Base URL & headers

https://app.numnum.be/api/v1

Header	Required	Example
`Authorization`	Yes	`Bearer <your-api-token>`
`X-Company-Id`	Yes	`12345`
`Content-Type`	Yes	`application/json`
`Accept`	Recommended	`application/json`

Mind the space between Bearer and the token.

Error handling

Treat only HTTP 201 as success. Any other status code means the document was not created; queue the request and retry later (with exponential back-off on 429 and 5xx).

Status	Meaning	Response body
`201 Created`	Document(s) created	`{ "invoices": [1234] }` (depending on the endpoint)
`400 Bad Request`	Headers missing	`{ "error": "Required headers are missing." }`
`400 Bad Request`	Wrong `Authorization` format	`{ "error": "Authorization header format is invalid." }`
`400 Bad Request`	Validation error in the payload	`{ "error": "invalid_body", "errors": { "0.client.email": ["..."] } }`
`401 Unauthorized`	Invalid API token	`{ "error": "Invalid API token." }`
`403 Forbidden`	Your user has no access to this company	`{ "error": "Access to this company is forbidden." }`
`404 Not Found`	Unknown Company ID	`{ "error": "Invalid company ID." }`
`429 Too Many Requests`	Rate limit or monthly limit reached	`{ "error": "Monthly API document limit reached." }`
`500`	Unexpected server error	Contact help@numnum.be

For validation errors (400 invalid_body), the key points to the array position and the field, e.g. 0.client.email = first document, field client.email.

Limits & quotas

Batch: one request contains an array of documents (max 50 per request). Processing is atomic: if one document fails, no document is created.
Rate limit (per company): 30 requests per minute and 2000 per day.
Monthly limit: a maximum number of documents per month applies (guideline ± 200/month). Exceeding it returns 429.
Keep parallel requests limited (± 5 at a time) to avoid overloading the server.

Deprecated endpoint (legacy)

An older endpoint, POST /webhooks/create-invoice (without /api/v1), still exists for existing integrations. It uses the same token but returns a bare list ([10232, 10233]) and different error codes (406, 401). This endpoint is deprecated; for new integrations always use POST /api/v1/webhooks/create-invoice.

Next steps

Questions? Contact help@numnum.be.