Reference Data API¶
Read-only lookup lists for the values used throughout the API — currencies, countries, locales, timezones, page sizes, document types, and the three coded lists EN 16931 asks you to choose from. Use them to populate dropdowns in your UI or to validate input before you submit it.
These endpoints are public: they require no authentication and are not metered. Every response is a static list wrapped in the standard {"data": [...]} envelope.
List Currencies¶
Supported currencies, including the display symbol and the number of decimal places used when formatting amounts.
Response:
{
"data": [
{ "code": "USD", "name": "US Dollar", "symbol": "$", "decimals": 2 },
{ "code": "JPY", "name": "Japanese Yen", "symbol": "¥", "decimals": 0 },
{ "code": "KWD", "name": "Kuwaiti Dinar", "symbol": "KD", "decimals": 3 }
]
}
| Field | Description |
|---|---|
code |
ISO 4217 currency code (e.g. USD) |
name |
Human-readable currency name |
symbol |
Display symbol for the currency |
decimals |
Number of decimal places used when formatting amounts (0, 2, or 3) |
Try it
List Countries¶
Supported countries for addresses and tax handling.
Response:
{
"data": [
{ "code": "US", "name": "United States" },
{ "code": "GB", "name": "United Kingdom" }
]
}
| Field | Description |
|---|---|
code |
ISO 3166-1 alpha-2 country code (e.g. US) |
name |
Country name |
Try it
List Locales¶
Supported locales for formatting numbers, dates, and text.
Response:
{
"data": [
{ "code": "en-US", "name": "English (United States)" },
{ "code": "fr-FR", "name": "French (France)" }
]
}
| Field | Description |
|---|---|
code |
BCP 47 locale code (e.g. en-US) |
name |
Human-readable locale name |
Try it
List Timezones¶
Supported IANA timezones with their UTC offset.
Response:
{
"data": [
{ "name": "UTC", "offset": "+00:00" },
{ "name": "America/New_York", "offset": "-05:00" },
{ "name": "Asia/Kolkata", "offset": "+05:30" }
]
}
| Field | Description |
|---|---|
name |
IANA timezone name (e.g. America/New_York) |
offset |
UTC offset (e.g. -05:00) |
Try it
List Page Sizes¶
Supported PDF page sizes, with dimensions in millimetres.
Response:
{
"data": [
{ "id": "LETTER", "name": "US Letter", "width_mm": 215.9, "height_mm": 279.4 },
{ "id": "A4", "name": "ISO A4", "width_mm": 210.0, "height_mm": 297.0 }
]
}
| Field | Description |
|---|---|
id |
Page size identifier (e.g. LETTER, A4) |
name |
Human-readable page size name |
width_mm |
Page width in millimetres |
height_mm |
Page height in millimetres |
Try it
List Document Types¶
Supported document types, each with the metadata you need to build a type-aware create form — the number prefix, whether it is payable / takes a source document / supports a reason, which line-item shape it uses, and the lifecycle actions available to it. See the Document Types guide for the concepts behind these fields.
Response:
{
"data": [
{
"id": "invoice",
"name": "Invoice",
"number_prefix": "INV-",
"payable": true,
"requires_source_document": false,
"supports_reason": false,
"line_item_type": "standard",
"actions": ["finalize", "void", "mark-sent", "mark-paid", "mark-unpaid", "archive", "restore"]
},
{
"id": "credit_note",
"name": "Credit Note",
"number_prefix": "CN-",
"payable": false,
"requires_source_document": true,
"supports_reason": true,
"line_item_type": "standard",
"actions": ["finalize", "void", "archive", "restore"]
},
{
"id": "delivery_note",
"name": "Delivery Note",
"number_prefix": "DN-",
"payable": false,
"requires_source_document": false,
"supports_reason": false,
"line_item_type": "shipped",
"actions": ["finalize", "void", "archive", "restore"]
}
]
}
| Field | Description |
|---|---|
id |
Document type identifier — pass as document_type when creating a document |
name |
Human-readable document type name |
number_prefix |
Conventional prefix for this type's number (e.g. INV-, CN-) |
payable |
Whether the type has the full payable lifecycle (mark-sent → mark-paid). Only invoice and proforma are payable |
requires_source_document |
Whether source_document_id is required (true for credit_note) |
supports_reason |
Whether the reason field applies (true for credit_note) |
line_item_type |
Line-item shape: standard (priced) or shipped (quantities only, no prices — used by delivery_note) |
actions |
Lifecycle transition actions available to this type (see the Lifecycle guide) |
Try it
Coded lists (EN 16931)¶
Three fields take a code from a published standard rather than a label:
line_items[].unit_code, line_items[].taxes[].category, and the
document-level tax_scheme. The API never infers them — mapping "hrs" to
HUR is a guess that is right until it silently is not, and the audience for
the result is a tax authority — so these endpoints are how you find the code you
need.
Their responses carry two fields the other reference lists do not:
| Field | Description |
|---|---|
standard |
The code list these values come from |
exhaustive |
Whether data is the complete list |
exhaustive is the one to branch on. true means a value outside data is
wrong, so you can back a picker with no escape hatch. false means data is a
shortlist of the codes an invoice usually needs — the API accepts any code,
nothing validates against the list, and treating it as closed will reject values
that are perfectly valid.
List Tax Categories¶
UNCL5305, in full. The VAT treatment of a line, which its rate does not say:
two lines at 0% may be zero-rated, exempt, reverse-charge or outside scope, and
EN 16931 puts them in separate VAT breakdown groups with different mandatory
fields. exhaustive: true.
{
"data": [
{ "code": "S", "label": "Standard rate" },
{ "code": "Z", "label": "Zero rated" },
{ "code": "E", "label": "Exempt from VAT" },
{ "code": "AE", "label": "Reverse charge" },
{ "code": "K", "label": "Intra-community supply" },
{ "code": "G", "label": "Export outside the EU" },
{ "code": "O", "label": "Outside the scope of VAT" }
],
"standard": "UNCL5305",
"exhaustive": true
}
Try it
List Tax Schemes¶
UNCL5153 — the tax regime a document is issued under. One per document, not per line: an invoice is issued under a regime, and EN 16931 could not express a mixture anyway.
VAT is the only member an e-invoice can carry. The others exist so you can
state that your tax is not VAT and be told so, rather than have VAT assumed on
your behalf. There is no default — a PDF does not need a scheme, and guessing
one puts a claim in a document a tax authority reads that you never made.
POST /documents/validate-compliance reports an unstated scheme
as a BT-118 violation, and neither serializer will write the document without
one.
{
"data": [
{ "code": "VAT", "label": "VAT" },
{ "code": "GST", "label": "GST" },
{ "code": "LOC", "label": "Sales tax (local)" },
{ "code": "OTH", "label": "Other" }
],
"standard": "UNCL5153",
"exhaustive": true
}
Try it
List Unit Codes¶
UN/ECE Recommendation 20 — the unit a line item is measured in. A shortlist:
twenty-one of hundreds, ordered by how often an invoice needs them rather than
alphabetically. exhaustive: false, and it means it — unit_code accepts any
value and an uncommon code is still correct.
{
"data": [
{ "code": "C62", "label": "Unit / piece" },
{ "code": "HUR", "label": "Hour" },
{ "code": "DAY", "label": "Day" },
{ "code": "E48", "label": "Service unit" }
],
"standard": "UN/ECE Recommendation 20",
"exhaustive": false
}