API playground
Every endpoint with its parameters and examples. Press Try it to send a real request to sandbox from your browser.
Unify
Submit a document
Validates one invoice or credit note for a country and document type, then stores it and continues delivery to the tax authority or the Peppol network (purpose: invoicing), checks it without storing it (validate), or saves it as a sample for mapping (mapping). Send several documents at once in an invoices array (see UnifyBatchRequest), or send the request as XML with Content-Type: application/xml. Too many requests in a short time return 429.
/api/v3/unify Authorization
Authorization string header required
Your API key, as Bearer YOUR_API_KEY.
Headers
new-api string header
Selects this request format for a JSON body. Without it, a JSON request is read in the earlier format. Not needed for XML.
Value true
Body
application/jsonsource must be one of your sources, as name:version. The examples use a sample source and a sample seller: replace them with your own. The minimal example has only the fields a UAE tax invoice needs; the full example adds common optional fields.
country string required
ISO 3166-1 alpha-2 code of the country the document is for.
One of AESAOMMYBEDE
environment string required
Must match your API key: a sandbox key for sandbox, a production key for production.
One of sandboxproduction
purpose string required
invoicing validates, stores and submits the document. validate runs the same checks without storing or submitting anything. mapping saves the payload as a sample to build a mapping from. Required: a request without it is refused with 400.
One of invoicingvalidatemapping
documentType object required
Decides which payload fields are required.
3 child attributes
base string required
For example tax_invoice or credit_note.
modifiers string[] required
Send an empty array when none apply.
variant string
payload object required
The invoice in the shape your source's mapping reads. With the Default GETS Mapping the payload is GETS, described by the GETS JSON Schema at /gets.schema.json and the field reference at /api-reference/gets/fields/. Dates are YYYY-MM-DD; amounts are numbers.
source string
Your source as name:version, split at the last colon. The version is the free text you registered, such as 1.0.0 or v1. Required for invoicing and validate.
The fields inside payload depend on the country and document type. See them in the field reference, or build a payload with .
Responses
200
For invoicing, the document passed validation and was stored. For validate, the checks ran: read valid. For mapping, the sample was saved. For a batch, the batch was read: read each item.
400
The request is malformed, names an unsupported country, has no purpose, or has a missing or malformed source (not name:version). A batch with more items than its limit, or one that mixes validate with other purposes, is refused the same way.
401
The API key is missing, invalid, revoked or expired.
403
The key cannot make this request.
404
The source was not found in your workspace. Check its name and version.
409
More than one source in your workspace has this name and version. Archive or rename the duplicate.
412
The source's mapping cannot take invoices yet. reason says why: no mapping for this source, country and document type, more than one, an inactive mapping, test cases that have not passed, or production that is still locked for this country, document type and request format.
413
An XML body is larger than 8 MiB.
415
An XML request has the wrong Content-Type, or a compressed body.
422
The document failed validation. Each error names the field in GETS and in your payload, and the rule it broke.
429
Too many requests in a short time. Wait for the number of seconds in Retry-After, then send again.
500
Something went wrong on our side. Retry with backoff.
503
A service the request needs is briefly unavailable. Send again after a short wait, then with longer waits.
More detail, with walkthroughs, in the reference page.