← API documentation

Facturen API

Content
GET /invoices

Retrieve invoices

Returns a paginated list of invoices. All filters are optional.

ParameterDescription
invoice_numberSearches on (part of) the invoice number.
statusdraft, sent, paid or overdue.
date_from, date_toInvoice date between two dates. Provide both.
total_amount_min, total_amount_maxTotal amount between two amounts. Provide both.
page, page_sizePagination, default 15 per page.
Request
curl "https://financial.gyvex.com/api/invoices?status=sent&page_size=25" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
GET /invoices/{invoice}

Retrieve invoice

Returns a single invoice with its invoice lines. Add ?customer to also include the customer details.

Request
curl "https://financial.gyvex.com/api/invoices/42?customer" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
Response 200 (shortened)
{
  "id": 42,
  "invoice_number": "2026-0042",
  "date": "2026-11-18",
  "due_date": "2026-12-02",
  "status": "sent",
  "customer_id": 7,
  "project_id": null,
  "total_amount": 242.00,
  "items": [
    {
      "description": "Websiteonderhoud",
      "quantity": 2,
      "unit_price": 100.00,
      "vat_percentage": 21,
      "total": 242.00
    }
  ]
}
POST /invoice/store

Create invoice

Creates an invoice with one or more lines. The total amount and the line totals are calculated automatically.

FieldRequiredDescription
invoice_numberYesInvoice number (text).
dateYesInvoice date.
due_dateYesDue date.
customer_idYesID of one of your customers.
statusYesdraft, sent, paid or overdue.
project_idNoID of a project.
itemsYesList of invoice lines (see below).
items[].descriptionYesDescription of the line.
items[].quantityYesQuantity, minimum 0.01.
items[].unit_priceYesPrice per unit, excl. VAT.
items[].vat_percentageNoVAT percentage, 0 to 100.
Request
curl -X POST "https://financial.gyvex.com/api/invoice/store" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "2026-0042",
    "date": "2026-11-18",
    "due_date": "2026-12-02",
    "customer_id": 7,
    "status": "sent",
    "items": [
      {
        "description": "Websiteonderhoud",
        "quantity": 2,
        "unit_price": 100,
        "vat_percentage": 21
      }
    ]
  }'

On success you receive status 201 with the created invoice, including id and lines.

PUT /invoice/{invoice}/update

Update invoice

Updates an existing invoice. All invoice fields are optional, but if you send items, they replace all existing lines. Therefore provide every line in full, including description, quantity, unit_price and total.

Unlike when creating, the system does not calculate the total itself when updating. So send total per line and, for changes, total_amount for the invoice yourself.

Request
curl -X PUT "https://financial.gyvex.com/api/invoice/42/update" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-12-16",
    "total_amount": 363.00,
    "items": [
      {
        "description": "Websiteonderhoud",
        "quantity": 3,
        "unit_price": 100,
        "vat_percentage": 21,
        "total": 363.00
      }
    ]
  }'
POST /invoice/{invoice}/mark-paid

Mark invoice as paid

Sets the status of an invoice to paid. Lines and amounts remain unchanged. Calling it again on a paid invoice does nothing. An invoice with status draft cannot be marked as paid (status 422).

Request
curl -X POST "https://financial.gyvex.com/api/invoice/42/mark-paid" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"
GET /invoice/{invoice}/pdf

Retrieve invoice PDF

Generates the PDF of an invoice. The PDF is in the pdf field of the JSON response as text.

Response 200
{
  "status": "success",
  "pdf": "..."
}
POST /invoice/{invoice}/send

Send invoice by email

Queues an email with the invoice PDF attached for the invoice's customer. Your email settings must be activated and the customer needs an email address, otherwise status 422 follows. On success you receive status 202.

Parameter Description
subject Subject, optional.
body Message text, optional.
Request
curl -X POST "https://financial.gyvex.com/api/invoice/42/send" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Uw factuur", "body": "Bijgaand uw factuur."}'
Response 202
{
  "status": "queued",
  "recipient": "john.doe@example.com"
}
DELETE /invoice/{invoice}

Delete invoice

Deletes an invoice. On success you receive status 204 without content.

Request
curl -X DELETE "https://financial.gyvex.com/api/invoice/42" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer UW_API_SLEUTEL"

Need help with your integration?

Create a ticket via "My Gyvex" in your dashboard. With Premium you get priority support, with a reply within 24 hours.