Essentio Data Formats
Last updated: 2 November 2026
Essentio hands you your data in two downloads: a Business's full archive, and your own personal data. This page describes every file each one holds and, for a spreadsheet, each of its columns. Nothing in them is locked to Essentio: PDF, the EU e-invoice XML, CSV and JSON are open formats that other software reads.
The Business Archive
An Owner or an Admin asks for it in Settings → General, on every plan. Essentio builds it in the background and emails a link to it, valid for 7 days without signing in. It is one ZIP file holding:
| File | What it holds |
|---|---|
invoices/<number>.pdf |
Every issued Invoice, as a PDF, a cancelled one included |
invoices/<number>.xml |
The same Invoice as EU e-invoice XML (EN 16931, UBL), unless README.txt lists it |
credit-notes/<number>.pdf |
Every issued Credit Note, as a PDF |
credit-notes/<number>.xml |
The same Credit Note as EU e-invoice XML (EN 16931, UBL), unless README.txt lists it |
proforma-invoices/<number>.pdf |
Every issued Proforma Invoice, as a PDF. A Proforma Invoice is not a tax invoice, so it has no XML |
quotes/<number>.pdf |
Every issued Quote, as a PDF. A Quote has no XML either |
receipts/<number>.pdf |
Every Receipt, as a PDF. A voided Receipt says so on its face |
drafts/<id>.json |
Every Draft, one JSON file each, in the shape the Public API gives a document |
clients.csv |
The Clients, one row each |
payments.csv |
Every Payment, one row each, reversed ones included |
products.csv |
Every Product, one row each, archived ones included |
settings.json |
The Business's settings, its VAT rates, its bank accounts and its number patterns |
README.txt |
What the archive holds, and each document that has no XML file, with the reason |
<number> is the document's or the Receipt's number. A character other than a letter, a digit, a dot, a hyphen or an underscore, such as the slash a number pattern may hold, is written as an underscore. A Draft has no number yet, so its file is named by <id>, the number Essentio gives each document, which the Public API names it by too.
The CSV files are UTF-8, comma-separated, with a header row and double quotes around a cell that needs them. Amounts are decimals with a dot, never rounded by the export, and dates are written as YYYY-MM-DD. A cell whose text begins with =, +, -, @, a tab or a line break is written with an apostrophe (') in front, so a spreadsheet application shows it as text and does not run it as a formula, and so is a cell whose text already begins with apostrophes before one of those characters; a plain number such as -5 is written as it is. Essentio's Import Clients removes that one apostrophe. The JSON files are UTF-8; in them an amount or a rate is a string holding a decimal with a dot, never rounded, a date is YYYY-MM-DD, a time is ISO 8601 with its offset, and a value that was never given is null.
clients.csv
Every Client, and every deleted Client that an issued document still names, so that each PDF has its row. It is the same file as Clients → Export → Essentio file, and Clients → Import reads it back.
| Column | What it holds |
|---|---|
| Account Code | The Client's account code |
| Name | The Client's name |
| Legal Name | The Client's legal name |
| The Client's email address | |
| Phone | The Client's phone number |
| Address | The street address |
| City | The city |
| Postal Code | The postal code |
| Country | The country, as a two-letter ISO code |
| VAT Number | The Client's VAT number |
| Currency | The Client's currency, as a three-letter ISO code |
| Payment Terms | The payment terms, in days |
| Notes | Your notes on the Client |
| Is Active | Yes or No |
| Created At | When the Client was created, YYYY-MM-DD HH:MM:SS in UTC |
| Updated At | When the Client was last changed, YYYY-MM-DD HH:MM:SS in UTC |
The import reads the columns from Account Code to Notes; it ignores the last three.
payments.csv
Every Payment recorded on a document, oldest first.
| Column | What it holds |
|---|---|
| Document Number | The number of the Invoice or Proforma Invoice the Payment was recorded on |
| Document Type | Invoice or Proforma Invoice |
| Client | The name of that document's Client |
| Payment Date | The day the money was received |
| Amount | The amount received |
| Currency | The Payment's currency, as a three-letter ISO code |
| Method | How it was paid, as recorded |
| Reference | The payment reference, as recorded |
| Status | completed, or voided for a reversed Payment |
| Receipt Number | The number of the Receipt issued for it, if any |
| Notes | Your notes on the Payment |
products.csv
Every Product, an archived one included, by its code. A deleted Product is not in it.
| Column | What it holds |
|---|---|
| Code | The Product's code |
| Name | The Product's name |
| Description | Its description |
| Type | product or service |
| Unit | The unit it is sold in |
| Price | Its price, with at least two decimals, more where the price has more |
| Currency | The price's currency, as a three-letter ISO code |
| VAT Rate | The VAT rate it is offered at, in percent |
| VAT Included | Yes if the price includes VAT, else No |
| Track Inventory | Yes or No |
| Stock Quantity | How many are in stock, when stock is tracked |
| Minimum Stock | The stock level to keep, when stock is tracked |
| Category | Its category |
| SKU | Its stock keeping unit |
| Barcode | Its barcode |
| Active | Yes or No |
| Archived | Yes for an archived Product, else No |
| Notes | Your notes on the Product |
drafts/<id>.json
Every Draft, one file each: the document as the Public API gives it, its Document, which the developer site describes field by field, without the two fields that say what may be done with it now and where its Client opens it. A deleted Draft is not in the archive.
| Key | What it holds |
|---|---|
id |
Essentio's number for the document, which names the file |
document_type |
invoice, proforma, credit_note or quote |
status |
draft |
is_test |
Whether it is a sample of a Test business: always false here |
document_number |
Its number: null, as a Draft has none yet |
requested_document_number |
The number it asks to be issued as, if one was typed |
requested_issue_date |
The day it is to be issued on, if one was chosen |
client_id |
Its Client's id |
client |
Its Client: the id and the name |
currency |
Its currency, as a three-letter ISO code |
issue_date |
Its issue date: null until it is issued |
due_date |
Its due date, or the day a Proforma Invoice or a Quote is valid until |
supply_date |
Its supply date, or the first day of its supply period |
supply_date_to |
The last day of its supply period, if it has one |
is_overdue |
Whether it is overdue: always false for a Draft |
days_overdue |
The days since its due date while it is overdue: null for a Draft |
payment_terms |
Its payment terms, in days |
client_reference |
The Client's reference |
purchase_order_number |
The Client's purchase order number |
project_reference |
The project reference |
notes |
Its notes, which the document prints |
footer_text |
Its footer text |
terms_and_conditions |
Its terms and conditions |
late_fee_rate |
Its late fee rate, in percent |
internal_notes |
Your internal notes on it, which the document does not print |
lines |
Its Lines, in order: each one's id, description, quantity, unit, unit price, VAT rate, VAT category, exemption code, product code, notes and net amount |
subtotal |
The sum of its Lines' net amounts |
discount_percent |
Its Discount as a percentage of the subtotal, if it was given as one |
discount_amount |
Its Discount as an amount: zero if it has none |
subtotal_after_discount |
Its subtotal less its Discount: the subtotal itself if it has none |
discount_name |
The name its Discount is printed by, if its writer gave it one |
total_vat |
Its VAT |
total |
Its Total |
vat_groups |
Its VAT, by VAT category and rate: each group's category, rate, exemption code, net amount and VAT |
bank_account_ids |
The ids of the bank accounts it shows, in its order: the ids settings.json gives them |
amount_due |
The amount still due: null for a Draft |
prepaid |
What was paid on the Proforma Invoice it was made from |
payments_total |
What was paid on it: nothing, for a Draft |
shows_amount_due |
Whether the document shows an amount due |
shows_prepaid |
Whether it shows what was prepaid |
shows_payments |
Whether it shows its Payments |
still_takes_payment |
Whether a Payment may still be recorded on it |
proforma_id |
The id of the Proforma Invoice it was made from, if any |
converted_into_id |
The id of the Invoice a Proforma Invoice became, if any |
last_sent |
When it was last sent, to whom and how, if it was |
created_at |
When it was created |
updated_at |
When it was last changed |
settings.json
What the Business set up in Essentio. It holds no password, login, key, token or secret: not the mail server's, not the connected mailbox's, not an API key, a Webhook's or a bank connection's.
| Key | What it holds |
|---|---|
business |
What Settings → General shows: the name, legal name and internal label, the email address, phone, cell phone, fax and website, the address, city, postal code and country, the VAT number, whether the Business is a VAT payer, the VAT abbreviation and name, the TAX ID, the registration number, the reporting currency and the currencies it invoices in, its time zone and its language |
document_defaults |
What a new document starts with: the terms and conditions, the footer text and the late fee rate |
templates |
The template chosen for each type of document and for the Statement |
numbering |
For each type of document and for the Receipt, its number pattern and the next number; when the numbers start again (never, yearly or monthly); and the Clients' account code format, its next number and the account type |
email |
How the Business's email is sent: the provider (essentio, google_gmail, microsoft_graph or smtp; null for a Business that never saved its Email settings, whose email Essentio sends), and the address and name the email comes from, for a connected mailbox and for the Business's own mail server |
vat_rates |
Every VAT rate, an inactive one included: its id, name and rate in percent, whether it is active, and whether Essentio ships it for the Business's country or the Business made it |
bank_accounts |
Every bank account: its id, account name, bank name, IBAN, SWIFT/BIC and account number, and whether it is the default |
Download my data
Profile → Download my data gives any User their own personal data at once, as one JSON file named essentio-my-data-<date>.json. It holds nothing a Business keeps, such as its documents, Clients or Payments: those are in the Business Archive. Times are ISO 8601 with their offset, and a time that never happened is null.
| Key | What it holds |
|---|---|
profile |
Your name, email address, when it was confirmed and when you first confirmed an email address, when you signed up, your Appearance, which version of the Terms of Service you accepted and when, when you last signed in and when you last used Essentio (noted at most once an hour), and how you came to sign up (through an app you were connecting, a Partner's link, an invitation or directly; the domain of the website that sent you; the campaign tags of the address you first opened; and your browser's preferred language) |
businesses |
Each Business you belong to, a deleted one included: its name, your role and when you joined. For a Business you own, also every complimentary plan Essentio gave it (the plan, when it was given, when it ends and when it was revoked) and the tax IDs given when it paid for a plan, such as a VAT number (its type and value, whether it was verified, the name and address the tax register holds for it, and when it was given) |
invitations |
Every invitation sent to your address: the Business, the role, when it was sent, when it expires and when it was accepted |
email_changes |
Each change of the email address you sign in with, while Essentio keeps it (seven days, so it can be undone): the address it was changed from and to, when, until when it could be undone and when it was undone. Never the link that undoes it |
connected_apps |
Every app you connected: the app, the Business, the role you gave it, and when it was connected, last used and ended |
oauth_apps |
Every app you registered as a developer: its name, its redirect addresses, whether it keeps a secret (never the secret itself), when you registered it and accepted the terms, whether it is deleted, and its Webhook's address and events |
partner_applications |
Every application you made to become a Partner: its status, your practice, your note, your personal link, and when you applied, were approved and when the partnership ended |
pending_businesses |
Each new Business you began paying for at Stripe Checkout, while Essentio keeps it: the name, email address, country and currencies you gave it, whether monthly or yearly, when you began, until when its payment page was open, when it was paid for and the Business it became. Never Stripe's own references for it |
feedback |
Every piece of feedback you sent from Essentio: its text, when you sent it, the Business you sent it from (none once that Business is erased), the page, your role there, your browser, and the email address you agreed to be answered at (null if you did not agree) |
downloaded_at |
When you downloaded the file |
The file holds no password, key or secret, and nothing about another person, not even who invited you.