NAV
Shell

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

Parameter In Type Required Description
email body string Yes Email address
password body string Yes Password
company body integer No Company ID to log in with

Example response

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

Responses

Status Description
200 Login succesful
401 The given combination of email, password (and optionally company) is not found.

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

Parameter In Type Required Description
company body integer Yes Company ID to request a token for

Example response

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

Responses

Status Description
200 Request succesful
400 Invalid request
401 You do not have access to the given company, or it does not exist

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"
}

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

Status Description
200 Request successful

Creating ledger numbers

POST /settings/ledgernumbers

Creates a new ledger number

Parameters

Parameter In Type Required Description
name body string Yes Human readable name for the new ledger number
ledgernumber body string No Code used for bookkeeping software. e.g. 4000, 8010
costcenter body string No Cost center code used for bookkeeping software, e.g. KPL0001, KP2

Example response

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

Responses

Status Description
200 Request successful
400 Request failed

Updating ledger numbers

PUT /settings/ledgernumbers/{id}

Updates a ledger number

Parameters

Parameter In Type Required Description
id query int Yes Ledger id
name body string Yes Human readable name for the new ledger number
ledgernumber body string No Code used for bookkeeping software. e.g. 4000, 8010
costcenter body string No Cost center code used for bookkeeping software, e.g. KPL0001, KP2

Example response

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

Responses

Status Description
200 Request successful
404 Ledger not found
400 Request failed

Deleting ledger numbers

DELETE /settings/ledgernumbers

Removed a ledger number

Parameters

Parameter In Type Required Description
id query int Yes Ledger id

Example response

"Ledgernumber has been removed"

Responses

Status Description
200 Request successful
404 Ledger not found
500 Request failed

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

Parameter In Type Required Default Description
order query string No id Specifies which field to order by. Options are id, description, price
reverse query boolean No false Reverses the order of the results
limit query integer No 10 Return max limit rows in the paginated response. Max 100.
page query integer No 0 What page of the pagination to return
status query string No Filter by status. Options are pastdue, open, credit, credited, paid, reminded, booked, notbooked
type query string No invoice Invoice type. Options are invoice, draft, quotation, recurring
minnumber query string No Minimum number of the invoice
maxnumber query string No Maximum number of the invoice
mindate query string No Minimum date of the invoice
maxdate query string No Maximum date of the invoice
minduedate query string No Minimum due date of the invoice
maxduedate query string No Maximum due date of the invoice
minduedate query string No Minimum total amount excluding vat of the invoice
maxduedate query string No Maximum total amount excluding vat of the invoice
minduedate query string No Minimum total amount excluding vat of the invoice
maxduedate query string No Maximum total amount excluding vat of the invoice

Example response


Responses

Status Description
200 Request successful

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"
            }
          ]
        },
    "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

Status Description
200 Invoice found
404 Invoice not found

Create Invoice

POST /invoice

Create a new invoice.

Parameters

Parameter In Type Required Default Description
creationToken body string No Optional: a client-side generated idempotency UUID
discount body float Yes 0 Discount in percentage
includesVat body boolean Yes false Amounts are including or excluding VAT
line body object Yes List of invoice lines
meta body object Yes Invoice meta object
receiver body int or object Yes Receiver id or full Receiver object
sender body int or object Yes Sender id or full Sender object
status body int No 0 Status of the invoice: 0 for drafts, 1 for finalized
text body object Yes Invoice text object
type body string No "” The type, either regular (empty string), C for Credit or I for Automatic Collection

Invoice Line object

Parameter Type Required Description
quantity float Yes Item quantity. Can be null if ledger, price, vat are all null
description string Yes Description, can span multiple lines
ledger int or object Yes Ledger id or Ledger object. Can be null if quantity, price, vat are all null
vat int or object Yes Vat id or Vat object. Can be null if quantity, ledger, price are all null
price float Yes Item price. Can be null if quantity, ledger, vat are all null

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

Status Description
200 Invoice created
400 Invoice not valid
500 Invoice saving failed

Update an Invoice

PUT /invoice/{id}

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

Parameters

Parameter In Type Required Default Description
id query int Yes Invoice id
Invoice object body json Yes Invoice data

Example query

PUT /invoice/44783

Example response

"44892"

Responses

Status Description
200 Invoice updated
400 Invoice not valid
500 Invoice saving failed, or invoice was finalized

Convert a draft Invoice into finalized

POST /invoice/{id}/send

Finalize a draft invoice.

Example request

POST /invoice/45311/send

Example response

"Invoice marked as sent!"

Responses

Status Description
200 Invoice created
400 Invoice not valid
500 Invoice saving failed

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

Parameter In Type Required Default Description
id query int Yes Invoice id

Example request

POST /invoice/44783/credit

Example response

"44789"

Responses

Status Description
201 Invoice credited, new one created
400 Invoice not valid or invalid state transition
404 Invoice to be credited not found
500 Invoice saving failed

Register an invoice payment

POST /invoice/{id}/payment

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

Parameters

Parameter In Type Required Default Description
id query int Yes Invoice id
method body int Yes Payment method id
date body string Yes Date on which the invoice was paid

Example request

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

Responses

Status Description
201 Invoice marked as paid
400 Invoice or request not valid
404 Invoice or payment method not found
409 Invoice already paid
500 Payment saving failed

Get PDF for Invoice

GET /invoice/{id}/view

Download the PDF of a given invoice.

Parameters

Parameter In Type Required Default Description
id query int Yes Invoice id

Example query

GET /invoice/44783/view

Example response

binary: application/pdf;

Responses

Status Description
200 Request successful

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

Parameter In Type Required Default Description
id query int Yes Invoice id
subject body string Yes Email subject
body body string Yes Email body
attachments body object No Optional attachments, with base64 encoded binary in content field

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

"Invoice sent"

Responses

Status Description
200 Invoice mailed
400 Invoice not valid or required field missing
404 Invoice not found
500 Invoice saving failed

Customer

Listing Customers

GET /customer

Retrieves a list of all customers in the current company.

Parameters

Parameter In Type Required Description
term query string No Search term for name or contact

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

Status Description
200 Request succesful

Get Single Customer

GET /customer/{id}

Get all details for a single customer.

Parameters

Parameter In Type Required Description
id path string Yes ID of customer

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

Status Description
200 Request succesful
404 Customer does not exist

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

Parameter In Type Required Description
companyname body string Yes Customer name
companycontact body string No Contact name (if customer is not a person)
address body string Yes Address
postalcode body string Yes Postal code
city body string Yes City
country body string Yes Country code
email body string Yes Email address
ccaddress body string No CC email address
debnumber body string No Debtor number
vatnumber body string No VAT number
phone body string No Phone number
iban body string No IBAN number
optionalfield_1 body string No optional field
optionalfield_2 body string No optional field
person body bool Yes is customer a person (true) or company (false)
option_expiration body number No custom expiration time for invoices
option_extratext body string No custom extra text for invoices
option_extratextbottom body string No custom extra text (bottom) for invoices
option_language body string No custom language for invoices
option_currency body string No custom currency for invoices

Example response

{
  "id": 1
}

Responses

Status Description
200 Request succesful
400 Invalid request

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

Parameter In Type Required Description
companyname body string Yes Customer name
companycontact body string No Contact name (if customer is not a person)
address body string Yes Address
postalcode body string Yes Postal code
city body string Yes City
country body string Yes Country code
email body string Yes Email address
ccaddress body string No CC email address
debnumber body string No Debtor number
vatnumber body string No VAT number
phone body string No Phone number
iban body string No IBAN number
optionalfield_1 body string No optional field
optionalfield_2 body string No optional field
person body bool Yes is customer a person (true) or company (false)
option_expiration body number No custom expiration time for invoices
option_extratext body string No custom extra text for invoices
option_extratextbottom body string No custom extra text (bottom) for invoices
option_language body string No custom language for invoices
option_currency body string No custom currency for invoices

Example response

{
  "id": 1
}

Responses

Status Description
200 Request succesful
400 Invalid request

Delete Customer

DELETE /customer/{id}

Deletes an existing customer.

Responses

Status Description
200 Customer deleted
404 Customer does not exist

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

Parameter In Type Required Description
countryCode query string Yes Country code for the VAT number
vatNumber query string Yes VAT number (without country code)

Example response

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

Responses

Status Description
200 Request succesful
400 Invalid request
404 VAT code not found

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

Parameter In Type Required Default Description
term query string No Search term for product description
order query string No id Specifies which field to order by. Options are id, description, price
reverse query boolean No false Reverses the order of the results
limit query integer No 10 Return max limit rows in the paginated response. Max 100.
page query integer No 0 What page of the pagination to return

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

Status Description
200 Request succesful

Get Single Product

GET /product/{id}

Get all details for a single product.

Parameters

Parameter In Type Required Description
id path string Yes ID of product

Example response

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

Responses

Status Description
200 Request succesful
404 Product does not exist

Create Product

POST /product

Create a new product.

Example request

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

Parameters

Parameter In Type Required Description
description body string Yes Product description
price body number Yes Price of the product
vat_id body number No ID of the associated VAT number
ledgernumber_id body number No ID of the associated ledger number

Example response

"Product has been created"

Responses

Status Description
200 Request succesful
400 Invalid request

Update Product

POST /product/{id}

Updates a product.

Example request

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

Parameters

Parameter In Type Required Description
id path number Yes ID of the product to update
description body string Yes Product description
price body number Yes Price of the product
vat_id body number No ID of the associated VAT number
ledgernumber_id body number No ID of the associated ledger number

Example response

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

Responses

Status Description
200 Request succesful
400 Invalid request

Delete Product

DELETE /customer/{id}

Deletes an existing product.

Parameters

Parameter In Type Required Description
id path number Yes ID of the product to delete

Example response

"Product has been removed"

Responses

Status Description
200 Product deleted
404 Product does not exist

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

Parameter In Type Required Description

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

Status Description
200 Request succesful
401 You do not have access to any companies

VAT codes

Table of types:

Type Description
high High
low Low
exempt Exempt
none No VAT
ICPS Services
ICPG Goods
EBU Export outside EU

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

Status Description
200 Request successful

Creating VAT codes

POST /settings/vatcodes

Creates a new VAT code

Parameters

Parameter In Type Required Description
name body string Yes Human readable name for the new VAT code
code body string No Code used for bookkeeping software. e.g. VL, VH
factor body number Yes Multiplier factor for the VAT. e.g. 1.21 => 21% VAT
type body string No Type of VAT code. See VAT codes for a table of options

Example response

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

Responses

Status Description
200 Request successful
400 Request failed

Updating VAT codes

PUT /settings/vatcodes/{id}

Updates a VAT code

Parameters

Parameter In Type Required Description
id query int Yes Vat id
name body string Yes Human readable name for the new VAT code
code body string No Code used for bookkeeping software. e.g. VL, VH
factor body number Yes Multiplier factor for the VAT. e.g. 1.21 => 21% VAT
type body string No Type of VAT code. See VAT codes for a table of options

Example response

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

Responses

Status Description
200 Request successful
400 Request failed
404 Vat not found

Deleting VAT codes

DELETE /settings/vatcodes/{id}

Remove a VAT code

Parameters

Parameter In Type Required Description
id query int Yes VAT id

Example response

"Vatcode has been removed"

Responses

Status Description
200 Request successful
404 VAT code not found
500 Request failed

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

Status Description
200 Request successful
404 No payment methods found

Creating payment methods

POST /settings/paymentmethods

Creates a new payment method

Parameters

Parameter In Type Required Description
name body string Yes Human readable name for the new payment method

Example response

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

Responses

Status Description
200 Request successful
400 Request failed

Updating payment methods

PUT /settings/paymentmethods/{id}

Updates a payment method

Parameters

Parameter In Type Required Description
id query int Yes Payment method id
name body string Yes Human readable name for the payment method

Example response

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

Responses

Status Description
200 Request successful
400 Request failed
404 Payment method not found

Deleting payment methods

DELETE /settings/paymentmethods

Remove a payment method from this company

Parameters

Parameter In Type Required Description
id query int Yes Payment method id

Example response

"Payment method has been removed"

Responses

Status Description
200 Request successful
404 Payment method not found
500 Request failed

Notifications

List Notifications

GET /notifications

Retrieves all notifications for the current company.

Example Response

[
    // TODO
]

Responses

Status Description
200 Request succesful

Dismiss Notifications

DELETE /notifications

Dismisses all notifications for the current company.

Example Response

"Notifications have been removed"

Responses

Status Description
200 Request succesful

Retrieving stream token

GET /token/lilium

Requests a token to authenticate with the notification stream service.

Example response

"thisisatoken"

Responses

Status Description
200 Request succesful