Introduction

Welcome to the TheNextInvoice API documentation.

Base URL

Currently, the API lives under the domain https://api.thenextinvoice.com/api/v1/. For brevity, all paths in this documentation will elide this base URL.

Response envelope

Response envelope

{
  "success": true,
  "data": {},
  "error": {
    "code": 0,
    "message": "error message"
  }
}

Our responses will always be wrapped in an envelope.

Of this envelope, some properties will be elided based on the type of response. As such, the error object will only exist when success is false.

For the brevity of the documentation, this envelope will henceforth be elided.

Authentication

General day-to-day authentication is done either through a JWT token, or an API key.

JWTs are accepted through the Authorization header.

example: Authorization: Bearer {token}.

API tokens are accepted through the X-Api-Token header.

example: X-Api-Token: {token}.

Login using JWT

No authentication needed for this request.

POST /session/jwt

The way of logging in a user directly, using email and password. Can optionally specify what company to log into.

Example curl request

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{ "email": "user@example.com", "password": "pa$$word" }' \
  https://api.thenextinvoice.com/api/v1/session/jwt

Example request

{
    "email": "user@example.com",
    "password": "pa$$word",
    "company": 1
}

Parameters

Example response

{
    "token": "jwt.auth.token",
    "status": "confirmed"
}

Responses

Switching company

POST /session/jwt/switch

After logging in, you can freely switch between the companies the user has access to. See Listing Companies for details on getting a list of companies.

Example request

{
    "company": 1
}

Parameters

Example response

{
    "token": "jwt.auth.token"
}

Responses

User preferences

GET /preferences

Returns various preferences related to the current company.

Example response

{
    "package": "premium",
    "addons": [
        "lightspeed",
        "payt"
    ],
    "language": "EN",
    "confirmed": true,
    "grace": 0,
    "user_data": {
        "name": "TNI beta user",
        "email": "tni@example.com"
    },
    "company_name": "TNI Beta"
}

Update user preferences

PUT /preferences

Updates the current user’s preferences. Returns the full preferences object (the same shape as GET /preferences).

Parameters

Example request

{
    "language": "EN"
}

Responses

Ledger

Listing ledgers

GET /settings/ledgernumbers

Retrieves a list of all ledger numbers for the current company.

Example response

[
  {
    "id": 76,
    "name": "Revenue",
    "ledgernumber": "8000",
    "costcenter": ""
  },
  {
    "id": 85,
    "name": "Management fee",
    "ledgernumber": "4010",
    "costcenter": ""
  },
  {
   "id": 76,
   "name": "Shipping",
   "ledgernumber": "4020",
   "costcenter": "KPL0001"
  }
]

Responses

Creating ledger numbers

POST /settings/ledgernumbers

Creates a new ledger number

Parameters

Example response

{
  "id": 155,
  "name": "Revenue",
  "ledgernumber": "8000",
  "costcenter": ""
}

Responses

Updating ledger numbers

PUT /settings/ledgernumbers/{id}

Updates a ledger number

Parameters

Example response

{
  "id": 155,
  "name": "Revenue",
  "ledgernumber": "8000",
  "costcenter": ""
}

Responses

Deleting ledger numbers

DELETE /settings/ledgernumbers

Removed a ledger number

Parameters

Example response

"Ledgernumber has been removed"

Responses

Invoice

Listing Invoices

GET /invoice/search

Retrieves a paginated list of all invoices in the current company.

Example query

GET /invoice/search?limit=10&reverse=true&status=&type=invoice&order=number&page=1

Parameters

Example response

{
  "current": 1,
  "first": 1,
  "previous": 1,
  "next": 1,
  "last": 1,
  "limit": 20,
  "total_items": 1,
  "items": [
    {
      "id": 45311,
      "company": 1,
      "number": "202400013",
      "status": 1,
      "type": "",
      "discount": 0,
      "includesVat": false,
      "lines": [
        {
          "description": "Product 1",
          "ledger": 11,
          "price": 100,
          "quantity": 1,
          "vat": 3
        }
      ],
      "sender": 1,
      "receiver": 2,
      "meta": {
        "currency": "EUR",
        "dueDate": "2024-05-27",
        "language": "nl",
        "sendDate": "2024-03-28"
      },
      "text": {
        "top": "This invoice is for item 1425",
        "bottom": "Thank you for your order.",
        "footer": ""
      },
      "calculated": {
        "totalExclVat": 100,
        "totalInclVat": 121,
        "discountApplied": 0,
        "vatApplied": 21,
        "vatTotals": {
          "21": 21
        }
      }
    }
  ]
}

Responses

Status of an invoice

GET /invoice/{id}/status

Retrieves the status details of an invoice

Example query

GET /invoice/12552/status

Example response

{
    "invoice": {
        "state": "paid"
    },
    "booking": {
        "status": true,
        "method": "twinfield",
        "message": "Invoice 201800013 has been booked",
        "time": "2018-04-12 18:30:45"
    },
    "mail": {
          "status": true,
          "events": [
            {
              "recipient": "debtors@example.com",
              "event": "queued",
              "time": "2019-02-28 21:30:00"
            },
            {
              "recipient": "debtors@example.com",
              "event": "delivered",
              "time": "2019-02-28 20:30:01"
            }
          ]
        },
    "comments": {
        "status": true,
        "comments": [
            {
                "user": {
                    "id": 1,
                    "name": "TNI beta user"
                },
                "message": "This is a nice comment",
                "time": "2023-12-20 11:13:37"
            }
        ]
    },
    "sepa": {
        "status": false,
        "message": null,
        "time": null
    },
    "collection": {
        "status": false,
        "date": null,
        "type": null
    },
   "payment": {
         "status": true,
         "message": "Bankoverschrijving",
         "time": "2019-01-21 00:00:00"
   }, 
    "reminder": {
        "status": false,
        "count": "0",
        "time": null
    },
    "recurring": {
        "status": false,
        "time": null
    },
    "quotation": {
        "status": false,
        "message": null,
        "time": null
    }
}

Responses

Create Invoice

POST /invoice

Create a new invoice.

Parameters

Invoice Line object

Example request

{
    "discount": 0,
    "includesVat": false,
    "lines": [
        {
            "description": "Product 1",
            "ledger": 11,
            "price": 100,
            "quantity": 1,
            "vat": 3
        },
        {
            "description": "Description-only line",
            "ledger": null,
            "price": null,
            "quantity": null,
            "vat": null
        }
    ],
    "meta": {
        "currency": "EUR",
        "dueDate": "2019-05-27",
        "language": "nl",
        "sendDate": "2019-03-28"
    },
    "receiver": 2,
    "sender": 1,
    "status": 0,
    "text": {
        "bottom": "Thank you for your order.",
        "footer": "Wij verzoeken u het factuurbedrag ter hoogte van {factuurbedrag} voor {vervaldatum} te voldoen op onze bankrekening onder vermelding van het factuurnummer {factuurnummer}. Alvast bedankt!",
        "top": "This invoice is for item 1425"
    },
    "type": ""
}

Example response

45311

Responses

Update an Invoice

PUT /invoice/{id}

Update a draft invoice. This endpoint expects a full Invoice object, as described under Create an Invoice.

Parameters

Example query

PUT /invoice/44783

Example response

44892

Responses

Convert a draft Invoice into finalized

POST /invoice/{id}/send

Finalize a draft invoice.

Example request

POST /invoice/45311/send

Example response

45311

Responses

Credit an invoice

POST /invoice/{id}/credit/

Credit an invoice marking the current invoice as ‘credited’ and creating and new invoice. In the newly created invoice, that is automatically marked as a finalized ‘credit’, all amounts are converted to the opposite signs.

Parameters

Example request

POST /invoice/44783/credit

Example response

44789

Responses

Get the invoice payment url

GET /invoice/{id}/payment-url

Get the payment url for an invoice. When a user follows this link, they reach a landing page where they can view the invoice pdf, and pay using one of the payment providers set up by the sending company.

Parameters

Example request

GET /invoice/44783/payment-url

Example response

thenextinvoice.com/t/a1b2c3d4e5f6

Responses

Register an invoice payment

POST /invoice/{id}/payment

Register a finalized invoice as paid using the provided method and transaction date.

Parameters

Example request

{
    "date": "2019-04-16", 
    "method": 8
}

Responses

Add a comment

POST /invoice/{id}/comment

Invoices support multiple comments, using this endpoint one at a time can be added.

Parameters

Example request

{
    "message": "This is a nice comment"
}

Example response

{
    "id": 123,
    "invoice_id": 44783,
    "user_id": 1,
    "time": "2023-12-20 11:13:37",
    "message": "This is a nice comment"
}

Responses

Get PDF for Invoice

GET /invoice/{id}/view

Download the PDF of a given invoice.

Parameters

Example query

GET /invoice/44783/view

Example response

binary: application/pdf;

Responses

Email Invoice

POST /invoice/{id}/send/mail

Email a single, finalized invoice. All placeholders are available and will be replaced with the values corresponding to the invoice.

When it is desired to send multiple invoices, use the /invoice/queue/ endpoint below.

Parameters

Example request

{
    "subject": "Invoice {invoicenumber}",
    "body": "<p>Dear {companyname},</p><p><br></p><p>Thank you for your order. Attached please find invoice {invoicenumber} that is due on {duedate}.</p><p>You can pay this invoice directly by following the link: {paymentlink}</p><p><br></p><p>Sincerely,</p><p><br></p><p>{companyname}</p>",
    "attachments": {
          "content": "base64 encoded binary",
          "filename": "Order confirmation.png"
    }
}

Example response

45311

Responses

Bulk operations

Several invoice actions accept a comma-separated list of ids in place of a single {id}, e.g. POST /invoice/45311,45312,45313/book. These are noted as “bulk” below.

Delete invoice(s)

DELETE /invoice/{id}

Soft-delete one or more invoices. Bulk (comma-separated ids).

Parameters

Responses

Book invoice(s)

POST /invoice/{id}/book

Queue one or more invoices to be booked into the connected accounting system. Bulk.

Responses

Remind invoice(s)

POST /invoice/{id}/remind

Register a payment reminder for one or more invoices. Bulk. Takes no body.

Responses

Approve invoice(s)

POST /invoice/{id}/approve

Approve one or more quotations. Bulk. Takes no body.

Responses

Archive invoice(s)

POST /invoice/{id}/archive

Archive one or more quotations. Bulk. Takes no body.

Responses

Queue multiple invoices for mailing

POST /invoice/{id}/queue

Queue finalized invoices to be emailed. Bulk.

Parameters

Responses

Create SEPA batch

POST /invoice/{id}/sepa

Create a SEPA direct-debit batch for one or more invoices. Bulk.

Parameters

Responses

Send invoice by SMS

POST /invoice/{id}/send/sms

Send a finalized invoice to its receiver by SMS. Requires SMS to be enabled and the receiver to have a phone number. The SMS text is generated automatically.

Responses

Send invoice over Peppol

POST /invoice/{id}/send/peppol

Send a finalized invoice over the Peppol network. Requires a Peppol-verified sender profile.

Responses

Resend an invoice

POST /invoice/{id}/resend

Resend a finalized invoice through its original send channel. Takes no body.

Responses

Set tracking number

POST /invoice/{id}/tracking-number

Set the shipment tracking number on an invoice.

Parameters

Responses

Delete invoice payment

DELETE /invoice/{id}/payment

Remove the registered payment from a paid invoice.

Responses

Get UBL for invoice

GET /invoice/{id}/ubl

Get the UBL (XML) document for a finalized invoice.

Parameters

Responses

Sync payments

POST /invoice/syncpayments

Trigger a reconciliation sync of invoice payments from connected payment providers. Takes no body.

Responses

Get an invoice

GET /invoice/{id}

Retrieves a single invoice by id, with the full invoice object (the same shape as the items returned by invoice search).

Draft invoices (status: 0) return receiver, sender and calculated as null. These are resolved and snapshotted onto the invoice only when it is finalized, so totals and embedded sender/receiver details are not yet available for drafts. To find drafts for a specific customer, filter invoice search by customer_id (the link exists even though receiver is not yet populated).

Parameters

Responses

Invoice totals

GET /invoice/totals

Returns aggregate totals for the invoices matching the given filters. Accepts the same filter parameters as invoice search (type, status, term, customer_id, date/amount ranges). Totals are keyed by currency.

Example response

{
  "EUR": {
    "amount_incl": 12100.00,
    "amount_excl": 10000.00
  }
}

Responses

Invoice downloads

These endpoints return binary/file responses rather than JSON.

Download invoice PDF

POST /invoice/{id}/send/pdf

Generates and returns the invoice PDF.

Example response

binary: application/pdf

Responses

Download invoice ZIP

GET /invoice/{id}/zip

Returns a ZIP containing the invoice PDF and any attachments. Bulk (comma-separated ids).

Example response

binary: application/zip

Responses

Download an invoice attachment

GET /invoice/{id}/attachment/{attachmentId}

Returns a single attachment file for the invoice, with its original content type.

Parameters

Responses

Download packing slip

GET /invoice/{id}/packing-slip

Returns the packing-slip PDF for an invoice.

Example response

binary: application/pdf

Responses

Export invoices as CSV

GET /invoice/csv

Exports the invoices matching the current filters as a ;-separated CSV. Accepts the same filter parameters as invoice search.

Example response

binary: text/csv

Responses

Customer

Listing Customers

GET /customer

Retrieves a list of all customers in the current company.

Parameters

Example response

[
    {
        "id": "1",
        "debnumber": "debtor number",
        "companyname": "Company name",
        "companycontact": "Contact name",
        "address": "Address Street 101",
        "postalcode": "1111AA",
        "city": "Amsterdam",
        "country": "NL",
        "vatnumber": "VAT NUMBER",
        "email": "company@example.com",
        "ccaddress": "companycc@example.com",
        "phone": "+31699999999",
        "iban": "NL73EXMPL000000000",
        "optionalfield_1": null,
        "optionalfield_2": null,
        "person": "0",
        "option_expiration": null,
        "option_extratext": null,
        "option_extratextbottom": null,
        "option_language": null,
        "option_currency": null
    },
    {
        "id": "2",
        "debnumber": null,
        "companyname": "Example Person",
        "companycontact": null,
        "address": "Somewhere Street 1",
        "postalcode": "111111",
        "city": "Amsterdammeke",
        "country": "NL",
        "vatnumber": "",
        "email": "person@example.com",
        "ccaddress": "",
        "phone": null,
        "iban": null,
        "optionalfield_1": null,
        "optionalfield_2": null,
        "person": "1",
        "option_expiration": null,
        "option_extratext": null,
        "option_extratextbottom": null,
        "option_language": null,
        "option_currency": null
    }
]

Responses

Paginated Customers

GET /customer/search

Retrieves a paginated list of all customers in the current company.

Example query

GET /customer/search?limit=10&page=1&term=Test

Parameters

Example response

{
    "current": "1",
    "first": "1",
    "items": [
        {
            "id": "1",
            "debnumber": "debtor number",
            "companyname": "Company name",
            "companycontact": "Contact name",
            "address": "Address Street 101",
            "postalcode": "1111AA",
            "city": "Amsterdam",
            "country": "NL",
            "vatnumber": "VAT NUMBER",
            "email": "company@example.com",
            "ccaddress": "companycc@example.com",
            "phone": "+31699999999",
            "iban": "NL73EXMPL000000000",
            "optionalfield_1": null,
            "optionalfield_2": null,
            "person": "0",
            "option_expiration": null,
            "option_extratext": null,
            "option_extratextbottom": null,
            "option_language": null,
            "option_currency": null
        },
        {
            "id": "2",
            "debnumber": null,
            "companyname": "Example Person",
            "companycontact": null,
            "address": "Somewhere Street 1",
            "postalcode": "111111",
            "city": "Amsterdammeke",
            "country": "NL",
            "vatnumber": "",
            "email": "person@example.com",
            "ccaddress": "",
            "phone": null,
            "iban": null,
            "optionalfield_1": null,
            "optionalfield_2": null,
            "person": "1",
            "option_expiration": null,
            "option_extratext": null,
            "option_extratextbottom": null,
            "option_language": null,
            "option_currency": null
        }
    ],
    "last": "1",
    "limit": "50",
    "next": "1",
    "previous": "1",
    "total_items": "2"
}

Responses

Get Single Customer

GET /customer/{id}

Get all details for a single customer.

Parameters

Example response

{
    "id": "1",
    "debnumber": "debtor number",
    "companyname": "Company name",
    "companycontact": "Contact name",
    "address": "Address Street 101",
    "postalcode": "1111AA",
    "city": "Amsterdam",
    "country": "NL",
    "vatnumber": "VAT NUMBER",
    "email": "company@example.com",
    "ccaddress": "companycc@example.com",
    "phone": "+31699999999",
    "iban": "NL73EXMPL000000000",
    "optionalfield_1": null,
    "optionalfield_2": null,
    "person": "0",
    "option_expiration": null,
    "option_extratext": null,
    "option_extratextbottom": null,
    "option_language": null,
    "option_currency": null
}

Responses

Create Customer

POST /customer

Create a new customer.

Example request

{
    "companyname": "Company name",
    "companycontact": "Contact name",
    "address": "Address Street 101",
    "postalcode": "1111AA",
    "city": "Amsterdam",
    "country": "NL",
    "email": "company@example.com",
    "person": false
}

Parameters

Example response

{
    "id": 1
}

Responses

Update Customer

PUT /customer/{id}

Updates an existing customer. All properties that are not set will be defaulted back to their default value.

Example request

{
    "companyname": "Company name",
    "companycontact": "Contact name",
    "address": "Address Street 101",
    "postalcode": "1111AA",
    "city": "Amsterdam",
    "country": "NL",
    "email": "company@example.com",
    "person": false
}

Parameters

Example response

{
    "id": 1
}

Responses

Delete Customer

DELETE /customer/{id}

Deletes an existing customer.

Responses

Resolving customer data through VAT number

GET /customer/checkvat

Attempts to resolve the given VAT information to a company, verifying if it exists, and if so returning some basic properties.

Example query

GET /customer/checkvat?countryCode=NL&vatNumber=857494454B01

Parameters

Example response

{
    "name": "Thenextinvoice b.v.",
    "street": "Condensatorweg 00054",
    "zip": "1014AX",
    "city": "Amsterdam"
}

Responses

Resolving customer data through Chamber of Commerce

GET /customer/checkcoc

Looks up a Dutch company in the Chamber of Commerce (KvK) register by CoC number or by name. Provide at least one of number or name.

Example query

GET /customer/checkcoc?number=12345678

Parameters

* At least one of number or name is required.

Example response

{
    "name": "Thenextinvoice b.v.",
    "street": "Condensatorweg 54",
    "zip": "1014AX",
    "city": "Amsterdam"
}

Responses

Listing duplicate customers

GET /customer/duplicates

Returns groups of customers that appear to be duplicates (matched on name / contact details), to support de-duplication.

Responses

Merging customers

PUT /customer/merge/{id}

Merges one or more duplicate customers into the master customer {id}: all invoices belonging to the listed customers are reassigned to the master, and the merged customers are removed.

Parameters

Example request

[
    12,
    34,
    56
]

Responses

Importing customers

POST /customer/import

Bulk-creates customers from a JSON array of customer objects (each object uses the same fields as Create Customer). The import is transactional: if any row fails validation the whole import is rolled back.

Example request

[
    {
        "companyname": "Company A",
        "address": "Street 1",
        "postalcode": "1111AA",
        "city": "Amsterdam",
        "country": "NL",
        "email": "a@example.com",
        "person": false
    },
    {
        "companyname": "Company B",
        "address": "Street 2",
        "postalcode": "2222BB",
        "city": "Rotterdam",
        "country": "NL",
        "email": "b@example.com",
        "person": false
    }
]

Responses

Verifying a customer for Peppol

GET /customer/verifypeppol/{id}

Checks whether a customer is a registered participant on the Peppol network. Requires Peppol to be enabled for the company.

Parameters

Responses

Product

Listing Products

GET /product/search

Lists (and optionally searches for) a list of all products in the current company. Response is paginated.

Example query

GET /product/search?order=id&page=1

Parameters

Example response

{
    "before": 1,
    "current": 1,
    "first": 1,
    "items": [
        {
            "description": "Product 1",
            "id": 1,
            "ledgernumber_id": 1,
            "price": 101,
            "vat_id": 3
        },
        {
            "description": "Product 2",
            "id": 7,
            "ledgernumber_id": null,
            "price": 10,
            "vat_id": null
        },
        {
            "description": "Product 3",
            "id": 9,
            "ledgernumber_id": 11,
            "price": 12,
            "vat_id": 2
        },
        {
            "description": "Product 4",
            "id": 10,
            "ledgernumber_id": 11,
            "price": 15,
            "vat_id": 3
        },
        {
            "description": "Product 5",
            "id": 13,
            "ledgernumber_id": 11,
            "price": 10,
            "vat_id": 1
        }
    ],
    "last": 140,
    "limit": 5,
    "next": 2,
    "total_items": 699,
    "total_pages": 140
}

Responses

Get Single Product

GET /product/{id}

Get all details for a single product.

Parameters

Example response

{
    "description": "Product 2",
    "id": 7,
    "ledgernumber_id": null,
    "price": 10,
    "vat_id": null
}

Responses

Create Product

POST /product

Create a new product.

Example request

{
  "description": "Description",
  "price": 100,
  "vat_id": null,
  "ledgernumber_id": null
}

Parameters

Example response

"Product has been created"

Responses

Update Product

PUT /product/{id}

Updates a product.

Example request

{
  "description": "Updated Description",
  "price": 1000,
  "vat_id": 4,
  "ledgernumber_id": null
}

Parameters

Example response

{
  "id": 1,
  "description": "Updated Description",
  "price": 1000,
  "vat_id": 4,
  "ledgernumber_id": null
}

Responses

Delete Product

DELETE /product/{id}

Deletes an existing product.

Parameters

Example response

"Product has been removed"

Responses

Company

Listing Companies

GET /company

Retrieves a list of all companies the current user has access to.

NOTE: See Profile Logo for usage of the logo option.

Parameters

Example response

[
  {
    "id": 1,
    "name": "Company name",
    "address": "Company address",
    "postalcode": "Company zipcode",
    "city": "Amsterdam",
    "coc": "CoC code",
    "next_number": "000001",
    "next_qnumber": "000001",
    "country": "NL",
    "logo": "1.png"
  }
]

Responses

VAT codes

Table of types:

Listing VAT codes

GET /settings/vatcodes

Retrieves a list of all vat codes for the current company.

Example response

[
  {
    "id": 155,
    "name": "6% BTW",
    "code": "VL",
    "factor": 1.06,
    "type": null
  },
  {
    "id": 156,
    "name": "21% BTW",
    "code": "VH",
    "factor": 1.21,
    "type": null
  },
  {
    "id": 154,
    "name": "Geen BTW",
    "code": "",
    "factor": 1,
    "type": "none"
  }
]

Responses

Creating VAT codes

POST /settings/vatcodes

Creates a new VAT code

Parameters

Example response

{
    "id": 155,
    "name": "6% BTW",
    "code": "VL",
    "factor": 1.06,
    "type": null
}

Responses

Updating VAT codes

PUT /settings/vatcodes/{id}

Updates a VAT code

Parameters

Example response

{
    "id": 155,
    "name": "6% BTW",
    "code": "VL",
    "factor": 1.06,
    "type": null
}

Responses

Deleting VAT codes

DELETE /settings/vatcodes/{id}

Remove a VAT code

Parameters

Example response

"Vatcode has been removed"

Responses

Listing VAT codes (percentage form)

GET /vatcodes

Like GET /settings/vatcodes, but returns the VAT rate as a percentage rather than a factor. For example a 21% code is returned as factor: 21 here, versus factor: 1.21 from /settings/vatcodes. Useful when you want the rate to display directly.

Example response

[
  {
    "id": 156,
    "name": "21% BTW",
    "code": "VH",
    "factor": 21,
    "type": null
  },
  {
    "id": 154,
    "name": "Geen BTW",
    "code": "",
    "factor": 0,
    "type": "none"
  }
]

Responses

Analytics

Turnover

GET /analytics/turnover/{interval}

Returns turnover for the current company over the last 12 periods. The response contains 12 labels and 12 corresponding values, oldest first.

Parameters

Example query

GET /analytics/turnover/month

Example response

{
  "labels": ["Jul 2025", "Aug 2025", "Sep 2025", "Oct 2025", "Nov 2025", "Dec 2025", "Jan 2026", "Feb 2026", "Mar 2026", "Apr 2026", "May 2026", "Jun 2026"],
  "values": [1200.5, 980, 0, 3400.75, 1500, 2100, 1800, 950, 2750, 3010.4, 1990, 2230]
}

Responses

Top customers

GET /analytics/customers/{limit}

Returns the top customers by turnover (within the last year), highest first.

Parameters

Example response

[
  { "customerid": 2, "companyname": "ACME B.V.", "amount": 14250.00 },
  { "customerid": 9, "companyname": "Example Person", "amount": 8800.50 }
]

Responses

Prognosis

A prognosis holds a company’s financial forecast. costs, debts and revenue are JSON arrays of monthly figures, starting from start_month/start_year.

Get prognosis

GET /prognosis

Returns the current company’s prognosis, or null if none has been set.

Example response

{
  "id": 12,
  "company_id": 1,
  "start_month": 1,
  "start_year": 2026,
  "costs": [1000, 1000, 1200],
  "debts": [0, 500, 0],
  "revenue": [3000, 3200, 4100]
}

Responses

Save prognosis

POST /prognosis or PUT /prognosis

Creates or updates the company’s prognosis (a company has at most one).

Parameters

Example request

{
  "start_month": 1,
  "start_year": 2026,
  "costs": [1000, 1000, 1200],
  "debts": [0, 500, 0],
  "revenue": [3000, 3200, 4100]
}

Responses

SEPA

SEPA direct-debit batches are created from invoices (see Create SEPA batch under Invoice). The endpoints here list and download existing batches.

Listing SEPA batches

GET /sepa/search

Retrieves a paginated list of SEPA batches for the current company. Accepts the same pagination and filter parameters as invoice search (limit, page, order, reverse, date/amount ranges, …).

Example query

GET /sepa/search?limit=10&page=1

Responses

SEPA totals

GET /sepa/totals

Returns aggregate totals for the SEPA batches matching the current filters, keyed by currency.

Example response

{
  "EUR": {
    "amount_incl": 4235.00,
    "amount_excl": 3500.00
  }
}

Responses

Download a SEPA file

GET /sepa/{id}/view

Returns the SEPA direct-debit XML (pain.008) for a batch, ready to upload to a bank.

Parameters

Example response

binary: application/xml

Responses

Payment methods

Listing payment methods

GET /settings/paymentmethods

Retrieves a list of all payment methods for the current company.

Example response

[
  {
    "id": 8,
    "name": "Bank transfer"
  },
  {
    "id": 76,
    "name": "Stripe"
  }
]

Responses

Creating payment methods

POST /settings/paymentmethods

Creates a new payment method

Parameters

Example response

{
  "id": 155,
  "name": "Mollie iDeal transfer"
}

Responses

Updating payment methods

PUT /settings/paymentmethods/{id}

Updates a payment method

Parameters

Example response

{
  "id": 155,
  "name": "iDeal transfer"
}

Responses

Deleting payment methods

DELETE /settings/paymentmethods

Remove a payment method from this company

Parameters

Example response

"Payment method has been removed"

Responses

Company settings

General per-company configuration. (VAT codes, ledger numbers and payment methods have their own pages.)

Invoice & quotation numbering

GET /settings/numbers

Returns the next invoice and quotation numbers.

Example response

{
  "invoice": "000001",
  "quotation": "00001"
}

PUT /settings/numbers

Updates the next invoice and/or quotation numbers.

Parameters

Responses

Debit ledger number

GET /settings/ledgernumberdebit

Returns the debit (accounts-receivable) ledger number used for bookkeeping (defaults to 1000).

Example response

{ "ledgerNumber": 1300 }

PUT /settings/ledgernumberdebit

Parameters

Responses

SEPA creditor settings

GET /settings/sepa

Returns the company’s SEPA creditor configuration (used when creating SEPA direct-debit batches).

Example response

{
  "id": 1,
  "company_id": 1,
  "creditor_name": "ACME B.V.",
  "iban": "NL73EXMPL000000000",
  "creditor_identifier": "NL98ZZZ999999990000"
}

PUT /settings/sepa

Updates the creditor settings. Values are validated; validation is skipped only if all three are empty.

Parameters

Responses

Payment messages

GET /settings/payment

Returns the messages shown on the payment landing page.

Example response

{
  "message": "Please pay invoice {invoicenumber}.",
  "success_message": "Thank you for your payment."
}

PUT /settings/payment

Parameters

Responses

Peppol settings

GET /settings/peppol

Returns whether Peppol is enabled for the company.

Example response

{ "id": 1, "company_id": 1, "enabled": true }

PUT /settings/peppol

Parameters

Responses

Terms & conditions

A company can store a single terms & conditions document.

HEAD /settings/termsandconditions — check whether a document exists (200 if so, 404 if not).

GET /settings/termsandconditions — download the stored document (binary).

POST /settings/termsandconditions — upload a document. Send exactly one file as multipart/form-data.

DELETE /settings/termsandconditions — remove the document.

Responses

Email settings

Sender & CC addresses

Email can be sent from verified from addresses, optionally CC’d to cc addresses. Each address is verified before it can be used.

List addresses

GET /settings/email/address

Example response

[
  { "id": 1, "type": "from", "email": "sender@example.com", "verified": true },
  { "id": 2, "type": "cc", "email": "cc@example.com", "verified": false }
]

Add an address

POST /settings/email/address

Adds an address and sends it a verification email.

Example response

{ "id": 3, "type": "from", "email": "new@example.com", "verified": false }

Verify an address

POST /settings/email/verify

Confirms an address using the key from the verification email. (This is the target of the verification link; usually not called directly.)

Remove an address

DELETE /settings/email/address/{id}/{type}

Responses

Email templates

Reusable email subject/body templates. Placeholders such as {invoicenumber}, {duedate}, {paymentlink} are substituted at send time.

List templates

GET /settings/email/text

Example response

[
  { "id": 1, "subject": "Invoice {invoicenumber}", "name": "Default", "text": "<p>Dear {companyname}...</p>" }
]

Get / create / update / delete

GET /settings/email/text/{id} — fetch one.

POST /settings/email/text — create.

PUT /settings/email/text/{id} — update.

DELETE /settings/email/text/{id} — remove.

For create and update:

Example response

{ "id": 1, "subject": "Invoice {invoicenumber}", "name": "Default", "text": "<p>Dear {companyname}...</p>" }

Responses

SMS settings

Enable / disable SMS

GET /settings/sms

Example response

{ "id": 1, "company_id": 1, "enabled": true }

PUT /settings/sms

Returns 200 on success, or 500 if the settings could not be loaded/saved.

SMS usage

GET /settings/sms/count

Returns the number of SMS segments used last month, this month, and in total.

Example response

{ "last": 150, "current": 320, "total": 5234 }

SMS templates

Reusable SMS templates. The text must contain a payment link placeholder ({paymentlink} / {betaallink}) or an invoice link placeholder ({viewinvoice} / {bekijkfactuur}).

List templates

GET /settings/sms/text

Example response

[
  { "id": 1, "name": "Payment reminder", "text": "Please pay via {paymentlink}" }
]

Get / create / update / delete

GET /settings/sms/text/{id} — fetch one.

POST /settings/sms/text — create.

PUT /settings/sms/text/{id} — update.

DELETE /settings/sms/text/{id} — remove.

For create and update:

Example response

{ "id": 1, "name": "Payment reminder", "text": "Please pay via {paymentlink}" }

Responses

Attachments

Reusable file attachments that can be attached to outgoing invoice/quotation emails (linked from an invoice profile’s send settings).

List attachments

GET /settings/attachments

Example response

[
  { "id": 1, "name": "General terms", "filename": "terms.pdf" }
]

Create an attachment

POST /settings/attachments

The file is uploaded as base64 in the content field.

Example response

{ "id": 1, "name": "General terms", "filename": "terms.pdf" }

Update an attachment

PUT /settings/attachments/{id}

Delete an attachment

DELETE /settings/attachments/{id}

Responses

Invoice profiles

A profile is a sender identity / branding template: sender details, logo, texts, layout and default email/SMS templates. A company can have multiple profiles, one of which is the default. Profiles are referenced as the sender when creating an invoice.

List profiles

GET /settings/profile

Returns all profiles. Each profile is a large object; key fields:

Example response (truncated)

[
  {
    "id": 1,
    "name": "Default Profile",
    "default": true,
    "logo": "1.png",
    "language": "nl",
    "expiration": 14,
    "companyName": "ACME B.V.",
    "address": "Condensatorweg 54",
    "postalCode": "1014AX",
    "city": "Amsterdam",
    "country": "NL",
    "vatNumber": "NL857494454B01",
    "email": "info@acme.com",
    "logo_position": "left",
    "sender_position": "right",
    "peppol_verified": false
  }
]

Get a profile

GET /settings/profile/{id}

{id} is a numeric id or the literal default. Returns the full profile object.

Create a profile

POST /settings/profile

Creates a profile with defaults. Returns the new profile id.

Example response

2

Update a profile

Profiles are updated through several focused endpoints. Each returns the profile id on success.

Name / language / expiration

PUT /settings/profile/{id}

Sender details

PUT /settings/profile/{id}/sender

When Peppol is enabled, sender details are validated more strictly.

Texts

PUT /settings/profile/{id}/text

Invoice layout

PUT /settings/profile/{id}/invoice

Default send settings

PUT /settings/profile/{id}/sending

Links the templates/addresses used when sending from this profile. All optional (integer ids or null): email_from_id, email_cc_id, email_text_id, email_text_reminder_id, email_text_quotation_id, sms_text_id, email_attachment_id, email_attachment_quotation_id.

Set default profile

POST /settings/profile/{id}/default

Makes the profile the company default.

Logo

GET /settings/profile/{id}.{type} — returns the logo as a base64 data URI (e.g. {id}.png).

POST or PUT /settings/profile/{id}/logo — upload a logo as multipart/form-data under the field file. Accepts PNG, JPEG, GIF, SVG.

DELETE /settings/profile/{id}/logo — remove the logo.

Delete a profile

DELETE /settings/profile/{id} — the default profile cannot be deleted.

Responses

Note the deliberate distinction: the read endpoints (list, get, logo) return 401 when the profile does not exist, while the mutating endpoints return 404.

Address verification

Verifies a profile’s sender address by post (required for some Peppol use). Operates per profile.

Status

GET /settings/verification

Example response

[
  {
    "id": 1,
    "profile_id": 5,
    "status": "verified",
    "verified_at": "2026-06-15 14:23:00",
    "attempts_remaining": 5,
    "sent_at": "2026-06-08 10:00:00",
    "can_resend": false,
    "cooldown_remaining": 345600,
    "address": "Condensatorweg 54",
    "postal_code": "1014 AX",
    "city": "Amsterdam",
    "country": "NL"
  }
]

status is one of pending, sent, verified, invalid.

Initiate

POST /settings/verification/{profileId}/initiate

Starts verification for a profile (uses its VAT/address data). Returns the verification object.

Confirm

POST /settings/verification/{id}/confirm

Example response

{
  "success": true,
  "message": "Address successfully verified",
  "verification": { "id": 2, "profile_id": 5, "status": "verified" }
}

Resend

POST /settings/verification/{id}/resend

Resends the verification letter (subject to a cooldown).

Responses

Integrations

Connections to external bookkeeping, payment and POS systems. Each integration is addressed by a {type}:

twinfield, exact, xero, yuki, visma, mollie, multisafepay, lightspeed, lsretail, lskseries, untill, thenextinvoice.

Many connectors (Twinfield, Exact, Xero, Mollie, Visma, Lightspeed*) use OAuth2: add returns a redirect URL, the provider then calls back to the callback endpoint.

List integrations

GET /settings/integrations

Example response

[
  { "name": "twinfield", "enabled": true, "office": "123", "option": {}, "free": true, "config": {} },
  { "name": "mollie", "enabled": false, "office": null, "option": null, "free": true, "config": {} }
]

Get one integration

GET /settings/integrations/{type}

Returns the integration’s current state (disabled state if not configured).

Active bookkeeping integration

GET /settings/integrations/check

Returns the company’s active bookkeeping integration (may be inherited from a linked accountant). 404 if none is active.

Add / connect an integration

POST /settings/integrations/{type}

Body parameters depend on the connector. For OAuth2 connectors the body is usually empty (and may take an optional option object); credential-based connectors take their own fields, e.g.:

• untill: office (POS IP), option[username], option[password]
• yuki: office, access_token
• multisafepay: api_key

Example response (OAuth2 connector)

{ "done": false, "redirect": "https://login.twinfield.com/oauth/...", "popup": true, "openConfig": true }

For credential connectors done is typically true and no redirect is needed.

OAuth2 callback

GET /settings/integrations/callback/{type}

The redirect target for OAuth2 connectors; not called directly.

Update an integration

PUT /settings/integrations/{type}

Saves connector configuration / mappings, e.g. ledger & VAT-code mappings for bookkeeping connectors (option[ledgernumbers], option[vatcodes], office), or product/category mappings for POS connectors. Returns a confirmation message or the updated integration.

Test an integration

GET /settings/integrations/{type}/test

Example response

{ "ok": true }

Remove an integration

DELETE /settings/integrations/{type}

Responses

Company users

Manage which users have access to the current company and their role.

List users

GET /settings/user

Example response

[
  { "id": 1, "email": "owner@example.com", "name": "John Owner", "role": "owner", "language": "nl" },
  { "id": 2, "email": "staff@example.com", "name": "Jane Staff", "role": "employee", "language": "en" }
]

Add a user

POST /settings/user

Grants a user access to the company. If the email does not belong to an existing user, a new account is created (then password, name and language are required).

Example response

{ "id": 3, "email": "new@example.com", "name": "New User", "language": "nl" }

Update a user’s role

PUT /settings/user/{id}

Remove a user

DELETE /settings/user/{id}

Removes the user from the company. The sole remaining owner cannot be removed.

Responses

Two-factor authentication

TOTP-based 2FA for the current user.

Status

GET /settings/2fa

Example response

{ "status": "enabled" }

status is one of disabled, connecting, enabled.

Begin enrollment

POST /settings/2fa

Generates a TOTP secret and provisioning URI to show as a QR code.

Example response

{
  "secret": "abcd efgh ijkl mnop",
  "url": "otpauth://totp/TheNextInvoice:user@example.com?secret=ABCD...&issuer=TheNextInvoice"
}

Finish enrollment

PUT /settings/2fa

Confirms enrollment with a code from the authenticator app.

Returns "Connected!" on success.

Disable

DELETE /settings/2fa

Returns "TOTP disabled".

Recovery codes

POST /settings/2fa/recovery

Generates a fresh set of one-time recovery codes (invalidating previous ones).

Example response

["abcd-efgh-ijkl", "mnop-qrst-uvwx", "yzab-cdef-ghij"]

Responses

Notifications

List Notifications

GET /notifications

Retrieves all notifications for the current company.

Example Response

[
    {
        "id": 42,
        "company_id": 1,
        "message": "Invoice 201800013 has been paid",
        "data": {
            "invoice_id": 12552
        },
        "time": "2019-02-28 21:30:00"
    }
]

Responses

Dismiss Notifications

DELETE /notifications

Dismisses all notifications for the current company.

Example Response

"Notifications have been removed"

Responses

Retrieving stream token

GET /token/lilium

Requests a token to authenticate with the notification stream service.

Example response

"thisisatoken"

Responses