Create invoices via the API

This endpoint creates sales invoices in NumNum. Once created, you can send them by email, Peppol or post.

ℹ️ Authentication (personal API token + X-Company-Id), limits and general error codes are in the Developer API overview. Read that first.

Endpoint

POST https://app.numnum.be/api/v1/webhooks/create-invoice

Headers:

Authorization: Bearer <your-api-token>
X-Company-Id: <your-company-id>
Content-Type: application/json
Accept: application/json

Request body

The body is a JSON array of invoice objects. You can create one or more invoices at once (max 50, processed atomically).

Invoice fields

payment_info

vat_shifted

VAT reverse-charge regime:

⚠️ For any value other than 0, all invoice lines must have vat_percentage: 0. The customer usually needs a valid VAT number (e.g. for intra-Community supplies).

Client object

ℹ️ The type field is only required for companies (company / bedrijf), not for individuals.

Invoice lines (invoice_lines)

Totals are calculated automatically:

• net = unit_price × amount
• vat = net × (vat_percentage / 100)
• total = net + vat

Example: invoice for a company

curl -X POST https://app.numnum.be/api/v1/webhooks/create-invoice \
  -H "Authorization: Bearer <your-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "en",
      "invoice_date": "2026-02-15",
      "expire_days": 30,
      "reference": "ORDER-2026-001",
      "intro": "Thank you for your order!",
      "remarks": "Please pay within 30 days.",
      "payment_info": "yes",
      "vat_shifted": 0,
      "client": {
        "company_type": "company",
        "type": "bv",
        "email": "info@customer.be",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "first_name": "Jan",
        "last_name": "Janssen",
        "address": "Kerkstraat 1",
        "address_zip": "1000",
        "address_city": "Brussels",
        "address_country": "BE",
        "telephone": "+32 2 123 45 67"
      },
      "invoice_lines": [
        { "description": "Website development", "unit_price": 1500.00, "amount": 1, "vat_percentage": 21 },
        { "description": "Hosting (12 months)", "unit_price": 15.00, "amount": 12, "vat_percentage": 21 }
      ]
    }
  ]'

Example: individual customer

For an individual, type and vat_id are not required:

[
  {
    "language": "en",
    "invoice_date": "2026-02-20",
    "expire_days": 14,
    "client": {
      "company_type": "individual",
      "email": "john.doe@gmail.com",
      "first_name": "John",
      "last_name": "Doe",
      "address": "Dorpstraat 45",
      "address_zip": "9000",
      "address_city": "Ghent",
      "address_country": "BE"
    },
    "invoice_lines": [
      { "description": "Logo graphic design", "unit_price": 350.00, "amount": 1, "vat_percentage": 21 }
    ]
  }
]

Example: VAT reverse charge (intra-Community)

For reverse charge, use vat_shifted and vat_percentage: 0:

[
  {
    "language": "en",
    "invoice_date": "2026-02-25",
    "expire_days": 30,
    "vat_shifted": 4,
    "remarks": "Reverse charge - VAT to be accounted for by the customer",
    "client": {
      "company_type": "company",
      "type": "gmbh",
      "email": "info@deutschefirma.de",
      "vat_country_code": "DE",
      "vat_id": "123456789",
      "first_name": "Hans",
      "last_name": "Müller",
      "address": "Hauptstraße 10",
      "address_zip": "10115",
      "address_city": "Berlin",
      "address_country": "DE"
    },
    "invoice_lines": [
      { "description": "Consulting services", "unit_price": 2500.00, "amount": 1, "vat_percentage": 0 }
    ]
  }
]

Response

HTTP 201: Created

{
  "invoices": [1234, 5678]
}

invoices is a list of internal database IDs in the same order as the input; these are not invoice numbers. Invoice numbers are generated automatically according to your company settings.

Errors

See the error table in the API overview. A validation error looks like this:

{
  "error": "invalid_body",
  "errors": {
    "0.language": ["The language must be one of: nl, fr, en, de."],
    "0.client.email": ["The client email must be a valid email address."],
    "0.invoice_lines.0.unit_price": ["The unit price must be a number."]
  }
}

Client matching (avoiding duplicate clients)

For each invoice, NumNum checks whether the client already exists, otherwise it creates one:

• With a VAT number (vat_country_code + vat_id): match on your company + the normalized VAT number. Formatting doesn’t matter: 0123456789 and 0123.456.789 match the same client.
• Without a VAT number: fall back to the combination company + vat_id + email. Use a consistent email address to avoid duplicates.

⚠️ If the client already exists (VAT match), it is not overwritten with the new details (name, address, email). Change client details in NumNum itself.

Notes

• Amounts: use a dot as the decimal separator (1234.56), no comma and no thousands separator.
• Dates: YYYY-MM-DD format with leading zeros (2026-02-05).
• VAT: numeric value without a % sign (21, not "21%" or 0.21).
• Atomic: if one invoice in the batch fails, none are created.
• Automatic numbering: you cannot supply your own invoice number.

Entity types

Valid values for client.type (only required for companies), among others: bv, nv, vzw, bvba, cvba, comm.v, comm.va, vof, eenmanszaak, sa, sarl, sas, srl, gmbh, ag, limited-ltd, limited-llc, natuurlijk-persoon, onbekend. Not sure? Use onbekend.

Deprecated endpoint

The old endpoint POST /webhooks/create-invoice (without /api/v1) still works for existing integrations but is deprecated: it returns a bare list ([10232, 10233]) and uses different error codes (406/401). Migrate to POST /api/v1/webhooks/create-invoice.