invoices

Add a new invoice to the database.

POST

/invoice

curl --request POST \
  --url https://api-sandbox.timeking.nl/api/external/v1/invoice \
  --header 'X-API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "<string>",
  "administration_id": 123,
  "attention_of": "<string>",
  "bottom_comment": "<string>",
  "client_id": 123,
  "coc_number": "<string>",
  "company": "<string>",
  "confirmed": 123,
  "connections_settings": {},
  "country": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "credit_id": 123,
  "custom_user": "<string>",
  "default_vat_rate_id": 123,
  "deleted_at": "2023-11-07T05:31:56Z",
  "discount": "<string>",
  "due_at": "2023-11-07T05:31:56Z",
  "email": "<string>",
  "export_man_day": 123,
  "export_presets": 123,
  "external_ids": {},
  "first_name": "<string>",
  "g_account_active": 123,
  "group_per": [
    "<string>"
  ],
  "hash": "<string>",
  "id": 123,
  "invoice_number": "<string>",
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "customfield1": "<string>",
      "customfield2": "<string>",
      "customfield3": "<string>",
      "customfield4": "<string>",
      "customfield5": "<string>",
      "description": "<string>",
      "discount": "<string>",
      "external_ids": {},
      "from_related": 123,
      "id": 123,
      "invoice_id": 123,
      "item_id": "<string>",
      "item_pricing_id": 123,
      "item_type": "<string>",
      "price": "<string>",
      "purchase_price": "<string>",
      "quantity": "<string>",
      "related_datetime": "2023-11-07T05:31:56Z",
      "related_id": 123,
      "related_type": "<string>",
      "related_vat_rate_id": 123,
      "sort_order": 123,
      "tax": "<string>",
      "unit": "<string>",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "last_name": "<string>",
  "mail_sent_at": "2023-11-07T05:31:56Z",
  "man_day_id": 123,
  "merge_items": 123,
  "merge_items_name": "<string>",
  "paid_at": "2023-11-07T05:31:56Z",
  "phone": "<string>",
  "postalcode": "<string>",
  "presets": [
    "<string>"
  ],
  "quote_id": 123,
  "reference": "<string>",
  "reminder": 123,
  "sent_at": "2023-11-07T05:31:56Z",
  "sort_by": "<string>",
  "source_id": 123,
  "source_type": "<string>",
  "status_id": 123,
  "status_updated_at": "2023-11-07T05:31:56Z",
  "subtotal": "<string>",
  "sync_messages": {},
  "tax": "<string>",
  "template_id": 123,
  "top_comment": "<string>",
  "total": "<string>",
  "town": "<string>",
  "transaction_id": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "user_id": 123,
  "vat_number": "<string>"
}
'

{
  "data": {
    "invoice": {
      "address": "<string>",
      "administration_id": 123,
      "attention_of": "<string>",
      "bottom_comment": "<string>",
      "client_id": 123,
      "coc_number": "<string>",
      "company": "<string>",
      "confirmed": 123,
      "connections_settings": {},
      "country": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "credit_id": 123,
      "custom_user": "<string>",
      "default_vat_rate_id": 123,
      "deleted_at": "2023-11-07T05:31:56Z",
      "discount": "<string>",
      "due_at": "2023-11-07T05:31:56Z",
      "email": "<string>",
      "export_man_day": 123,
      "export_presets": 123,
      "external_ids": {},
      "first_name": "<string>",
      "g_account_active": 123,
      "group_per": [
        "<string>"
      ],
      "hash": "<string>",
      "id": 123,
      "invoice_number": "<string>",
      "items": [
        {
          "created_at": "2023-11-07T05:31:56Z",
          "customfield1": "<string>",
          "customfield2": "<string>",
          "customfield3": "<string>",
          "customfield4": "<string>",
          "customfield5": "<string>",
          "description": "<string>",
          "discount": "<string>",
          "external_ids": {},
          "from_related": 123,
          "id": 123,
          "invoice_id": 123,
          "item_id": "<string>",
          "item_pricing_id": 123,
          "item_type": "<string>",
          "price": "<string>",
          "purchase_price": "<string>",
          "quantity": "<string>",
          "related_datetime": "2023-11-07T05:31:56Z",
          "related_id": 123,
          "related_type": "<string>",
          "related_vat_rate_id": 123,
          "sort_order": 123,
          "tax": "<string>",
          "unit": "<string>",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "last_name": "<string>",
      "mail_sent_at": "2023-11-07T05:31:56Z",
      "man_day_id": 123,
      "merge_items": 123,
      "merge_items_name": "<string>",
      "paid_at": "2023-11-07T05:31:56Z",
      "phone": "<string>",
      "postalcode": "<string>",
      "presets": [
        "<string>"
      ],
      "quote_id": 123,
      "reference": "<string>",
      "reminder": 123,
      "sent_at": "2023-11-07T05:31:56Z",
      "sort_by": "<string>",
      "source_id": 123,
      "source_type": "<string>",

Body

Invoice object.

addressstring

The street and house number of the invoiced party. Copied from the client when empty.

administration_idinteger

The ID of the administration this invoice belongs to, which also determines its invoice number series. Defaults to the default administration when empty.

attention_ofstring

The person the invoice is addressed for the attention of. Copied from the client when empty.

bottom_commentstring

The footnote printed below the invoice lines (HTML). Replaced by the G-account footnote when a G-account amount applies and the comment is empty or the default one.

client_idinteger

The ID of the client (klant) this invoice is for. Empty contact fields are filled from the client on save, and on create the client's invoicing defaults apply to the export options. Either client_id or company must be set.

coc_numberstring

The Chamber of Commerce number of the invoiced party. Copied from the client when empty.

companystring

The company name of the invoiced party. Copied from the client's name when empty; when no client_id is given, set this to invoice a party that is not a client.

confirmedinteger

Whether this invoice is finalized. Finalizing assigns the invoice number; a finalized invoice can no longer be changed in its lines, deleted, or given a different sent or due date. Create the invoice as a draft, add its rate lines through the /invoiceitem endpoint with invoice_id, then update the invoice (optionally with confirmed: 1): the update puts the rate lines on the invoice and recalculates the totals. Returned as 1 (yes) or 0 (no).

connections_settingsobject

The settings of this invoice per connected third party application, keyed by connection (e.g. {"exact_online": {"journal": "70"}}).

countrystring

The country of the invoiced party, returned as the full country name (falls back to the Netherlands). Accepts an ISO 3166-1 alpha-2 code or a country name; copied from the client when empty.

created_atstring

The date and time this invoice was created.

credit_idinteger

The ID of the credit invoice that credits this invoice.

custom_userstring

A legacy free-text user field that is no longer used.

default_vat_rate_idinteger

The ID of the default VAT rate of this invoice. When this VAT rate is reverse-charged, no VAT is calculated on the invoice.

deleted_atstring

The date and time this invoice was archived (soft deleted), or empty when it is not archived.

discountstring

The total discount of all invoice lines in euros (zero or negative). Calculated automatically from the invoice lines (items). Returned as a numeric string, e.g. "12.50".

due_atstring

The due date of this invoice. Derived from the sent date and the client's (or default) payment term when the invoice is finalized without a valid one, and locked once the invoice is finalized.

emailstring

The email address the invoice is sent to (max. 50 characters). Copied from the client's invoicing email address (or else its email address) when empty.

export_man_dayinteger

Whether the man-day register is attached to this invoice. Returned as 1 (yes) or 0 (no).

export_presetsinteger

Whether the order overview reports of the selected presets are attached to this invoice. Returned as 1 (yes) or 0 (no).

external_idsobject

The IDs connected to this invoice in connected third party applications, keyed by connection (e.g. {"exact_online": "..."}).

first_namestring

The first name of the contact person this invoice is addressed to.

g_account_activeinteger

Whether a G-account amount applies to this invoice. Empty follows the client setting, or else the default setting. Returned as 1 (yes) or 0 (no).

group_perstring[]

The types of rate lines that are combined into one invoice line when they share the same pricing, unit, description, discount and price. Any of 'operation', 'material', 'vehicle', 'user' or 'weight_type'.

hashstring

The random 40-character token in the public link of this invoice. Generated automatically on create.

idintegerverplicht

The ID of this invoice.

invoice_numberstring

The invoice number. Assigned automatically from the administration's number series when the invoice is finalized (confirmed), and empty while it is a draft.

itemsobject[]

The lines on the invoice document, from which the totals of this invoice are calculated. They are built automatically from the rate lines linked to this invoice through the /invoiceitem endpoint (with invoice_id) each time the invoice is updated, and cannot be changed directly.

child attributes tonen

last_namestring

The last name of the contact person this invoice is addressed to.

mail_sent_atstring

The date and time this invoice was last sent by email (format Y-m-d H:i:s).

man_day_idinteger

The ID of the man-day register attached to this invoice.

merge_itemsinteger

Whether all rate lines are merged into a single invoice line. Returned as 1 (yes) or 0 (no).

merge_items_namestring

The description of the single invoice line when merge_items is enabled.

paid_atstring

The date and time this invoice was paid, or empty when it is not paid.

phonestring

The phone number of the invoiced party. Copied from the client when empty.

postalcodestring

The postal code of the invoiced party. Copied from the client when empty.

presetsstring[]

The IDs of the presets whose reports are attached to this invoice when export_presets is enabled.

quote_idinteger

The ID of the quote this invoice was created from.

referencestring

The reference of this invoice, printed on the document.

reminderinteger

The number of payment reminders sent for this invoice.

sent_atstring

The invoice date printed on the document. Set to today when the invoice is finalized without one, and locked once the invoice is finalized.

sort_bystring

A legacy sorting field that is no longer used.

source_idinteger

The ID of the record this invoice was made from. Detected automatically.

source_typestring

The type of the record this invoice was made from. Either 'order' (project), 'suborder' or 'client' (klant). Detected automatically.

status_idinteger

The ID of the current invoice status, whose code is one of 'draft', 'confirmed', 'sent_concept', 'sent_email', 'paid', 'credit' or 'credit_old'. Maintained automatically.

status_updated_atstring

The date and time the status of this invoice last changed. Set automatically.

subtotalstring

The total amount excluding VAT in euros as a numeric string. Calculated automatically from the invoice lines (items).

sync_messagesobject

The error messages of the last failed sync to connected third party applications, keyed by connection (e.g. {"exact_online": {"invoice": "..."}}). Maintained automatically.

taxstring

The total VAT amount in euros as a numeric string. Calculated automatically from the invoice lines (items).

template_idinteger

The ID of the invoice layout used for the document. When empty, the layout of the client, then the administration, then the default layout is assigned automatically.

top_commentstring

The header comment printed above the invoice lines (HTML). Replaced by the G-account header comment when a G-account amount applies and the comment is empty or the default one.

totalstring

The total amount including VAT in euros as a numeric string. Calculated automatically from the invoice lines (items).

townstring

The city of the invoiced party. Copied from the client when empty.

transaction_idstring

The reference of the pending online payment transaction of this invoice.

updated_atstring

The date and time this invoice was last updated.

user_idinteger

The ID of the user linked to this invoice.

vat_numberstring

The VAT number of the invoiced party. Copied from the client when empty.

Antwoord

Successful operation.

dataobject

The result message and the result data.

child attributes tonen

statusstring

The result status, success.

Nog hulp nodig? Vraag het team

Autorisaties

Body

Antwoord