{ "openapi": "3.1.0", "info": { "title": "Complyance API", "version": "3.0.0", "description": "Submit e-invoices, retrieve documents and manage the companies in your workspace. Every environment uses the same host: the request or your API key chooses sandbox or production." }, "servers": [ { "url": "https://prod.gets.complyance.io", "description": "Sandbox and production" } ], "tags": [ { "name": "Unify", "description": "Submit documents for any supported country." }, { "name": "Documents", "description": "Follow submitted documents and retrieve received purchase invoices." }, { "name": "Connect", "description": "Onboard and manage the companies in an ISV workspace." } ], "paths": { "/api/v3/unify": { "post": { "operationId": "submitDocument", "tags": [ "Unify" ], "summary": "Submit a document", "description": "Validates one invoice or credit note for a country and document type, and queues it for delivery to the tax authority or the Peppol network. Delivery continues after the response.", "security": [ { "bearerAuth": [] } ], "externalDocs": { "url": "/api-reference/gets/fields/", "description": "Payload fields for each country and document type" }, "parameters": [ { "name": "new-api", "in": "header", "required": true, "description": "Selects this request format. Without it, the request is read in the earlier format.", "schema": { "type": "string", "enum": [ "true" ] }, "example": "true" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyRequest" }, "example": { "country": "AE", "environment": "sandbox", "purpose": "invoicing", "source": "acme-erp:1.0.0", "documentType": { "base": "tax_invoice", "modifiers": [] }, "payload": { "header": { "documentType": { "base": "tax_invoice" }, "documentNumber": "INV-2026-000184", "issueDate": "2026-09-18", "currency": "AED", "taxCurrency": "AED", "exchangeRate": { "rate": 1 }, "dueDate": "2026-10-18" }, "parties": { "seller": { "name": "Acme Trading LLC", "address": { "country": "AE", "city": "Dubai", "addressLine1": "12 Harbour Road", "stateOrProvince": "Dubai" }, "taxIds": [ { "type": "VAT", "value": "100012345600003" } ], "registrationNumbers": [ { "type": "CRN", "value": "CN-1234567" } ], "peppolId": "100012345600003" }, "buyer": { "name": "Gulf Retail FZ-LLC", "address": { "country": "AE", "addressLine1": "48 Market Street", "city": "Dubai", "stateOrProvince": "Dubai" }, "taxIds": [ { "value": "100012345600004" } ], "peppolId": "100012345600004" } }, "lineItems": [ { "id": "1", "name": "Cloud subscription — Business plan", "quantity": 20, "unitCode": "PCE", "taxAmount": 100, "lineTaxableValue": 2000, "taxCategory": "S", "taxRate": 5, "commodityClassification": { "code": "851762", "scheme": "HS" }, "price": { "amount": 100, "grossPrice": 100 }, "taxExemptionReason": "Certain financial services", "taxExemptionReasonCode": "CERTAIN_FINANCIAL_SERVICES", "extensions": { "ae_itemType": "Services", "ae_rcmType": "ELECTRONIC_DEVICES", "ae_serviceAccountingCode": "998314", "ae_sacScheme": "SAC" } } ], "payment": { "paymentMeans": [ { "paymentMeansCode": "PAYMENT_TO_BANK_ACCOUNT", "creditTransferInfo": { "payeeFinancialAccountId": "AE070331234567890123456" } } ] }, "totals": { "totalAmountExcludingTax": 2000, "totalAmountIncludingTax": 2100, "amountDue": 2100, "totalLineTaxableAmount": 2000, "totalTaxAmount": 100 }, "extensions": { "peppol_precedingInvoiceIssueDate": "2026-08-14", "peppol_seller_peppolIdScheme": "0235", "peppol_buyer_peppolIdScheme": "0235", "peppol_totalTaxAmountInTaxCurrency": 100, "ae_buyer_authorityName": "Dubai Department of Economy and Tourism", "ae_beneficiaryId": "FTZ-2291", "ae_principalTRN": "100098765400003", "ae_totalAmountIncludingTaxInAED": 2100, "ae_seller_authorityName": "Dubai Department of Economy and Tourism", "ae_seller_passportIssuingCountry": "AE", "ae_buyer_passportCountry": "AE" } } } } }, "description": "`source` must be one of your sources, as `name:version`. The example uses a sample source." }, "responses": { "200": { "description": "The document passed validation and was stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyAccepted" }, "example": { "documentId": "01K5EXAMPLE00000000000142", "documentNumber": "INV-2026-000184", "message": "Your invoice was validated and is ready for submission.", "Base64XML": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9InVybjpvYXNpczpuYW1lczpzcGVjaWZpY2F0aW9uOnVibDpzY2hlbWE6eHNkOkludm9pY2UtMiIgeG1sbnM6Y2FjPSJ1cm46b2FzaXM6bmFtZXM6c3BlY2lmaWNhdGlvbjp1Ymw6c2NoZW1hOnhzZDpDb21tb25BZ2dyZWdhdGVDb21wb25lbnRzLTIiIHhtbG5zOmNiYz0idXJuOm9hc2lzOm5hbWVzOnNwZWNpZmljYXRpb246dWJsOnNjaGVtYTp4c2Q6Q29tbW9uQmFzaWNDb21wb25lbnRzLTIiPjxjYmM6Q3VzdG9taXphdGlvbklEPnVybjpwZXBwb2w6cGludDpiaWxsaW5nLTFAYWUtMTwvY2JjOkN1c3RvbWl6YXRpb25JRD48Y2JjOlByb2ZpbGVJRD51cm46cGVwcG9sOmJpczpiaWxsaW5nPC9jYmM6UHJvZmlsZUlEPjxjYmM6SUQ+SU5WLTIwMjYtMDAwMTg0PC9jYmM6SUQ+PGNiYzpJc3N1ZURhdGU+MjAyNi0wOS0xODwvY2JjOklzc3VlRGF0ZT48Y2JjOkR1ZURhdGU+MjAyNi0xMC0xODwvY2JjOkR1ZURhdGU+PGNiYzpJbnZvaWNlVHlwZUNvZGU+MzgwPC9jYmM6SW52b2ljZVR5cGVDb2RlPjxjYmM6RG9jdW1lbnRDdXJyZW5jeUNvZGU+QUVEPC9jYmM6RG9jdW1lbnRDdXJyZW5jeUNvZGU+PGNhYzpBY2NvdW50aW5nU3VwcGxpZXJQYXJ0eT48Y2FjOlBhcnR5PjxjYmM6RW5kcG9pbnRJRCBzY2hlbWVJRD0iMDIzNSI+MTAwMDEyMzQ1NjAwMDAzPC9jYmM6RW5kcG9pbnRJRD48Y2FjOlBvc3RhbEFkZHJlc3M+PGNiYzpTdHJlZXROYW1lPjEyIEhhcmJvdXIgUm9hZDwvY2JjOlN0cmVldE5hbWU+PGNiYzpDaXR5TmFtZT5EdWJhaTwvY2JjOkNpdHlOYW1lPjxjYmM6Q291bnRyeVN1YmVudGl0eT5EdWJhaTwvY2JjOkNvdW50cnlTdWJlbnRpdHk+PGNhYzpDb3VudHJ5PjxjYmM6SWRlbnRpZmljYXRpb25Db2RlPkFFPC9jYmM6SWRlbnRpZmljYXRpb25Db2RlPjwvY2FjOkNvdW50cnk+PC9jYWM6UG9zdGFsQWRkcmVzcz48Y2FjOlBhcnR5VGF4U2NoZW1lPjxjYmM6Q29tcGFueUlEPjEwMDAxMjM0NTYwMDAwMzwvY2JjOkNvbXBhbnlJRD48Y2FjOlRheFNjaGVtZT48Y2JjOklEPlZBVDwvY2JjOklEPjwvY2FjOlRheFNjaGVtZT48L2NhYzpQYXJ0eVRheFNjaGVtZT48Y2FjOlBhcnR5TGVnYWxFbnRpdHk+PGNiYzpSZWdpc3RyYXRpb25OYW1lPkFjbWUgVHJhZGluZyBMTEM8L2NiYzpSZWdpc3RyYXRpb25OYW1lPjwvY2FjOlBhcnR5TGVnYWxFbnRpdHk+PC9jYWM6UGFydHk+PC9jYWM6QWNjb3VudGluZ1N1cHBsaWVyUGFydHk+PGNhYzpBY2NvdW50aW5nQ3VzdG9tZXJQYXJ0eT48Y2FjOlBhcnR5PjxjYmM6RW5kcG9pbnRJRCBzY2hlbWVJRD0iMDIzNSI+MTAwMDEyMzQ1NjAwMDA0PC9jYmM6RW5kcG9pbnRJRD48Y2FjOlBvc3RhbEFkZHJlc3M+PGNiYzpTdHJlZXROYW1lPjQ4IE1hcmtldCBTdHJlZXQ8L2NiYzpTdHJlZXROYW1lPjxjYmM6Q2l0eU5hbWU+RHViYWk8L2NiYzpDaXR5TmFtZT48Y2JjOkNvdW50cnlTdWJlbnRpdHk+RHViYWk8L2NiYzpDb3VudHJ5U3ViZW50aXR5PjxjYWM6Q291bnRyeT48Y2JjOklkZW50aWZpY2F0aW9uQ29kZT5BRTwvY2JjOklkZW50aWZpY2F0aW9uQ29kZT48L2NhYzpDb3VudHJ5PjwvY2FjOlBvc3RhbEFkZHJlc3M+PGNhYzpQYXJ0eVRheFNjaGVtZT48Y2JjOkNvbXBhbnlJRD4xMDAwMTIzNDU2MDAwMDQ8L2NiYzpDb21wYW55SUQ+PGNhYzpUYXhTY2hlbWU+PGNiYzpJRD5WQVQ8L2NiYzpJRD48L2NhYzpUYXhTY2hlbWU+PC9jYWM6UGFydHlUYXhTY2hlbWU+PGNhYzpQYXJ0eUxlZ2FsRW50aXR5PjxjYmM6UmVnaXN0cmF0aW9uTmFtZT5HdWxmIFJldGFpbCBGWi1MTEM8L2NiYzpSZWdpc3RyYXRpb25OYW1lPjwvY2FjOlBhcnR5TGVnYWxFbnRpdHk+PC9jYWM6UGFydHk+PC9jYWM6QWNjb3VudGluZ0N1c3RvbWVyUGFydHk+PGNhYzpQYXltZW50TWVhbnM+PGNiYzpQYXltZW50TWVhbnNDb2RlPjMwPC9jYmM6UGF5bWVudE1lYW5zQ29kZT48Y2FjOlBheWVlRmluYW5jaWFsQWNjb3VudD48Y2JjOklEPkFFMDcwMzMxMjM0NTY3ODkwMTIzNDU2PC9jYmM6SUQ+PC9jYWM6UGF5ZWVGaW5hbmNpYWxBY2NvdW50PjwvY2FjOlBheW1lbnRNZWFucz48Y2FjOlRheFRvdGFsPjxjYmM6VGF4QW1vdW50IGN1cnJlbmN5SUQ9IkFFRCI+MTAwLjAwPC9jYmM6VGF4QW1vdW50PjxjYWM6VGF4U3VidG90YWw+PGNiYzpUYXhhYmxlQW1vdW50IGN1cnJlbmN5SUQ9IkFFRCI+MjAwMC4wMDwvY2JjOlRheGFibGVBbW91bnQ+PGNiYzpUYXhBbW91bnQgY3VycmVuY3lJRD0iQUVEIj4xMDAuMDA8L2NiYzpUYXhBbW91bnQ+PGNhYzpUYXhDYXRlZ29yeT48Y2JjOklEPlM8L2NiYzpJRD48Y2JjOlBlcmNlbnQ+NTwvY2JjOlBlcmNlbnQ+PGNhYzpUYXhTY2hlbWU+PGNiYzpJRD5WQVQ8L2NiYzpJRD48L2NhYzpUYXhTY2hlbWU+PC9jYWM6VGF4Q2F0ZWdvcnk+PC9jYWM6VGF4U3VidG90YWw+PC9jYWM6VGF4VG90YWw+PGNhYzpMZWdhbE1vbmV0YXJ5VG90YWw+PGNiYzpMaW5lRXh0ZW5zaW9uQW1vdW50IGN1cnJlbmN5SUQ9IkFFRCI+MjAwMC4wMDwvY2JjOkxpbmVFeHRlbnNpb25BbW91bnQ+PGNiYzpUYXhFeGNsdXNpdmVBbW91bnQgY3VycmVuY3lJRD0iQUVEIj4yMDAwLjAwPC9jYmM6VGF4RXhjbHVzaXZlQW1vdW50PjxjYmM6VGF4SW5jbHVzaXZlQW1vdW50IGN1cnJlbmN5SUQ9IkFFRCI+MjEwMC4wMDwvY2JjOlRheEluY2x1c2l2ZUFtb3VudD48Y2JjOlBheWFibGVBbW91bnQgY3VycmVuY3lJRD0iQUVEIj4yMTAwLjAwPC9jYmM6UGF5YWJsZUFtb3VudD48L2NhYzpMZWdhbE1vbmV0YXJ5VG90YWw+PGNhYzpJbnZvaWNlTGluZT48Y2JjOklEPjE8L2NiYzpJRD48Y2JjOkludm9pY2VkUXVhbnRpdHkgdW5pdENvZGU9IlBDRSI+MjA8L2NiYzpJbnZvaWNlZFF1YW50aXR5PjxjYmM6TGluZUV4dGVuc2lvbkFtb3VudCBjdXJyZW5jeUlEPSJBRUQiPjIwMDAuMDA8L2NiYzpMaW5lRXh0ZW5zaW9uQW1vdW50PjxjYWM6SXRlbT48Y2JjOk5hbWU+Q2xvdWQgc3Vic2NyaXB0aW9uIOKAlCBCdXNpbmVzcyBwbGFuPC9jYmM6TmFtZT48Y2FjOkNsYXNzaWZpZWRUYXhDYXRlZ29yeT48Y2JjOklEPlM8L2NiYzpJRD48Y2JjOlBlcmNlbnQ+NTwvY2JjOlBlcmNlbnQ+PGNhYzpUYXhTY2hlbWU+PGNiYzpJRD5WQVQ8L2NiYzpJRD48L2NhYzpUYXhTY2hlbWU+PC9jYWM6Q2xhc3NpZmllZFRheENhdGVnb3J5PjwvY2FjOkl0ZW0+PGNhYzpQcmljZT48Y2JjOlByaWNlQW1vdW50IGN1cnJlbmN5SUQ9IkFFRCI+MTAwLjAwPC9jYmM6UHJpY2VBbW91bnQ+PC9jYWM6UHJpY2U+PC9jYWM6SW52b2ljZUxpbmU+PC9JbnZvaWNlPg==" } } } }, "400": { "description": "The request is malformed, or names an unsupported country or an unknown source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" }, "examples": { "invalid": { "summary": "Invalid request", "value": { "code": "invalid_argument", "message": "Invalid request." } }, "country": { "summary": "Unsupported country", "value": { "error": "Unsupported country: XX" } }, "source": { "summary": "Missing source", "value": { "error": "source is required for invoicing" } } } } } }, "401": { "description": "The API key is missing, invalid, revoked or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "The `source` was not found in your workspace. Check its name and version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" } } } }, "403": { "description": "The key cannot make this request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" }, "examples": { "environment": { "summary": "Wrong environment", "description": "The key belongs to a different environment from `environment`. Use a sandbox key with `sandbox` and a production key with `production`.", "value": { "code": "permission_denied", "message": "A mock API key is required for the sandbox environment" } }, "permission": { "summary": "Read-only key", "description": "Submitting needs a key with write permission.", "value": { "code": "insufficient_permission", "message": "The API key does not have enough permissions." } } } } } }, "422": { "description": "The document failed validation. Each error names the field in GETS and in your payload, and the rule it broke.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyValidationFailure" }, "example": { "documentId": "01K5EXAMPLE00000000000142", "documentNumber": "INV-2026-000184", "message": "Your invoice could not be validated. Review the errors and try again.", "validationStage": "gets", "errors": [ { "code": "IBR-015", "getsPath": "totals.amountDue", "payloadPath": "totals.amountDue", "message": "An Invoice MUST have the Amount due for payment (ibt-115).", "severity": "error", "ruleSet": "ae:tax_invoice" } ] } } } }, "429": { "description": "Too many requests. Wait for the number of seconds in `Retry-After`, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" }, "example": { "error": "Too many requests" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "500": { "description": "Something went wrong on our side. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifyProblem" }, "example": { "error": "Internal server error" } } } } } } }, "/api/v3/documents": { "get": { "operationId": "listPurchaseInvoices", "tags": [ "Documents" ], "summary": "List purchase invoices", "description": "Lists the purchase invoices received in a date range, with cursor pagination. Your API key decides the workspace and environment.", "security": [ { "bearerAuth": [] } ], "externalDocs": { "url": "/api-reference/purchases/list/" }, "parameters": [ { "name": "type", "in": "query", "required": true, "description": "Only `purchases` is supported.", "schema": { "type": "string", "enum": [ "purchases" ] }, "example": "purchases" }, { "name": "from", "in": "query", "required": true, "description": "First day of the range, `YYYY-MM-DD`, by when the invoice was received (UTC).", "schema": { "type": "string", "format": "date" }, "example": "2026-09-22" }, { "name": "to", "in": "query", "required": false, "description": "Last day of the range, `YYYY-MM-DD`. Defaults to `from`.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `nextCursor` from the previous page. Keep the same range and limit while paging.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of received purchase invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseList" }, "example": { "success": true, "data": { "items": [ { "documentId": "01K5EXAMPLE00000000000142", "receivedAt": "2026-09-22T08:15:00.000Z", "storedAt": "2026-09-22T08:15:02.000Z", "status": "purchase.invoice.stored", "country": "AE", "environment": "sandbox", "invoiceNumber": "INV-2026-0142", "supplierName": "Acme Trading LLC", "issueDate": "2026-09-22" } ], "hasMore": false, "nextCursor": null } } } } }, "400": { "description": "A date, cursor or limit is invalid, or sales listing was requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentsError" }, "examples": { "invalid": { "summary": "Invalid value", "value": { "success": false, "code": "VALIDATION_ERROR", "message": "from must be on or before to" } }, "sales": { "summary": "Sales listing", "value": { "success": false, "code": "NOT_SUPPORTED", "message": "Sales document listing is not yet supported. Use type=purchases." } } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "422": { "description": "A required query parameter is missing or has the wrong type, such as no `from` or a `limit` above 100." }, "500": { "description": "Retrieval failed. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentsError" }, "example": { "success": false, "code": "INTERNAL_ERROR", "message": "Failed to list documents" } } } } } } }, "/api/v3/documents/{documentId}": { "get": { "operationId": "getDocument", "tags": [ "Documents" ], "summary": "Get a document", "description": "With `type=sales`, returns where a submitted document is in processing. With `type=purchases`, returns a received purchase invoice with its full data.", "security": [ { "bearerAuth": [] } ], "externalDocs": { "url": "/api-reference/purchases/get/" }, "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "The `documentId` from a submission, a listing or a webhook.", "schema": { "type": "string" }, "example": "01K5EXAMPLE00000000000142" }, { "name": "type", "in": "query", "required": true, "description": "`sales` for a document you submitted, `purchases` for one you received.", "schema": { "type": "string", "enum": [ "sales", "purchases" ] }, "example": "sales" } ], "responses": { "200": { "description": "The document.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SalesDocument" }, { "$ref": "#/components/schemas/PurchaseDocument" } ] }, "examples": { "sales": { "summary": "Submitted document", "value": { "success": true, "data": { "documentId": "01K5EXAMPLE00000000000142", "documentNumber": "INV-2026-000184", "country": "AE", "environment": "sandbox", "state": "final_valid", "isTerminal": true, "lastUpdatedAt": "2026-09-22T10:00:04.000Z", "errors": [], "government": { "status": "APPROVED" }, "validationResults": { "status": "Valid", "validationSteps": [ { "name": "schema", "status": "Valid", "error": null } ] } } } }, "purchases": { "summary": "Purchase invoice", "description": "`invoice` and `xml` are shortened here.", "value": { "success": true, "data": { "documentId": "01K5EXAMPLE00000000000142", "documentNumber": "INV-2026-0142", "country": "AE", "environment": "sandbox", "state": "final_valid", "isTerminal": true, "lastUpdatedAt": "2026-09-22T08:15:02.000Z", "errors": [], "government": { "status": "APPROVED" }, "invoice": { "header": { "documentNumber": "INV-2026-0142" } }, "xml": "..." } } } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "404": { "description": "No document with this identifier for this key. Check the identifier, the `type` and the key's environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentsError" }, "example": { "success": false, "code": "NOT_FOUND", "message": "Document not found" } } } }, "422": { "description": "`type` is missing or not `sales` or `purchases`." }, "500": { "description": "Retrieval failed. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentsError" }, "example": { "success": false, "code": "INTERNAL_ERROR", "message": "Failed to retrieve document" } } } } } } }, "/v3/connect/companies": { "post": { "operationId": "createCompany", "tags": [ "Connect" ], "summary": "Create a UAE company", "description": "Registers a UAE company in your workspace with its first branch and source. Complete the UAE prerequisites first.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#create-a-uae-company" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompany" }, "example": { "sourceName": "acme-dubai", "sourceVersion": "v1", "countryCode": "AE", "tin": "1234567890", "contactPersonEmail": "finance@example.com", "contactPersonName": "Alex Morgan", "branchName": "Dubai", "platformEnvironment": "sandbox" } } }, "description": "Unknown fields are rejected. Replace the sample identity with your company's details." }, "responses": { "201": { "description": "The company, its first branch and its source were created. Check `readyForInvoicing` before submitting invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyCreated" }, "example": { "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "sourceId": "01JABCDEF1234567890SOURCE", "branchId": "66b9f0b2c2d3e4f567890456", "userGivenBranchId": "acme-dubai", "peppolParticipantId": "0235:1234567890", "legalName": "Acme Trading LLC", "tin": "1234567890", "vatTrn": "123456789000003", "sourceName": "acme-dubai", "sourceVersion": "v1", "countryCode": "AE", "branchName": "Dubai", "contactPersonName": "Alex Morgan", "contactPersonEmail": "finance@example.com", "platformEnvironment": "sandbox", "readyForInvoicing": false, "mappingReadiness": { "status": "ACTION_REQUIRED", "code": "CONNECT_MAPPING_NOT_CONFIGURED" }, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z" }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "400": { "$ref": "#/components/responses/ConnectValidation" }, "401": { "$ref": "#/components/responses/InvalidKey" }, "403": { "description": "This workspace or key cannot onboard companies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" } } } }, "409": { "description": "The company cannot be created as requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "examples": { "exists": { "summary": "Already exists", "description": "List your companies and reuse the existing identifiers.", "value": { "success": false, "error": { "code": "CONNECT_COMPANY_ALREADY_EXISTS", "message": "This company already exists in your workspace.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } }, "linkage": { "summary": "Prerequisite missing", "description": "Complete the UAE prerequisite for this environment.", "value": { "success": false, "error": { "code": "ASP_LINKAGE_NOT_FOUND", "message": "No pending ASP linkage was found for this company.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } } } }, "429": { "$ref": "#/components/responses/ConnectRateLimited" }, "504": { "description": "Onboarding took too long. The company may still have been created: list your companies before trying again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" } } } } } }, "get": { "operationId": "listCompanies", "tags": [ "Connect" ], "summary": "List companies", "description": "Lists the company sources in your workspace, most recently updated first. A UAE company with several branches appears once per branch.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#list-companies" }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Companies per page, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "example": "10" }, { "name": "countryCode", "in": "query", "required": false, "description": "Only companies in this country.", "schema": { "type": "string" }, "example": "AE" }, { "name": "sourceVersion", "in": "query", "required": false, "description": "Only sources with this exact version.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only active or only inactive (archived) sources.", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "search", "in": "query", "required": false, "description": "Text to search for in company sources.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of company sources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" }, "example": { "success": true, "data": [ { "companyId": "66b9f0a1c2d3e4f567890123", "sourceName": "acme-dubai", "sourceVersion": "v1", "legalName": "Acme Trading LLC", "legalIdentifier": null, "countryCode": "AE", "status": "active", "sourceId": "01JABCDEF1234567890SOURCE", "branchId": "66b9f0b2c2d3e4f567890456", "branchName": "Dubai", "tin": "1234567890", "vatTrn": "123456789000003", "mappingReadiness": { "status": "READY", "templateId": "default-gets-66b9e000c2d3e4f567890000" }, "readyForInvoicing": true, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z" } ], "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000", "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasMore": false }, "filters": { "countryCode": "AE" }, "sort": { "field": "updatedAt", "order": "desc" } } } } } }, "400": { "$ref": "#/components/responses/ConnectValidation" }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } }, "/v3/connect/companies/onboarding-jobs": { "post": { "operationId": "createOnboardingJob", "tags": [ "Connect" ], "summary": "Onboard companies in bulk", "description": "Onboards up to 500 companies in one country and waits for the job to finish. A `200` can still contain failed rows: check each row's `status` and `nextAction`.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/partner-platform/isv/companies/bulk-onboarding/" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingJobRequest" }, "example": { "countryCode": "AE", "platformEnvironment": "sandbox", "rows": [ { "sourceName": "acme-dubai", "sourceVersion": "v1", "tin": "1234567890", "contactPersonEmail": "finance@example.com", "contactPersonName": "Alex Morgan", "branchName": "Dubai" } ] } } } }, "responses": { "200": { "description": "The job finished. Rows can be `onboarded`, `duplicate` or `failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "id": "66ba10d4c2d3e4f567890abc", "workspaceId": "66b9e000c2d3e4f567890000", "countryCode": "AE", "filename": "API bulk onboarding", "status": "completed", "totalRows": 1, "processedRows": 1, "succeededRows": 1, "failedRows": 0, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z", "completedAt": "2026-09-22T10:00:00.000Z", "rows": [ { "id": "66ba10d5c2d3e4f567890abd", "jobId": "66ba10d4c2d3e4f567890abc", "rowIndex": 0, "status": "onboarded", "sourceName": "acme-dubai", "sourceVersion": "v1", "countryCode": "AE", "nextAction": "mapping_action_required", "connectCompanyId": "66b9f0a1c2d3e4f567890123", "data": { "companyId": "66b9f0a1c2d3e4f567890123", "sourceId": "01JABCDEF1234567890SOURCE", "branchId": "66b9f0b2c2d3e4f567890456", "userGivenBranchId": "acme-dubai", "peppolParticipantId": "0235:1234567890", "legalName": "Acme Trading LLC", "tin": "1234567890", "vatTrn": "123456789000003", "sourceName": "acme-dubai", "sourceVersion": "v1", "countryCode": "AE", "branchName": "Dubai", "contactPersonName": "Alex Morgan", "contactPersonEmail": "finance@example.com", "platformEnvironment": "sandbox", "readyForInvoicing": false, "mappingReadiness": { "status": "ACTION_REQUIRED", "code": "CONNECT_MAPPING_NOT_CONFIGURED" }, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z" }, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z" } ] }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "400": { "description": "The job could not start: a row or the country is invalid. The message lists the rows to fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Row 1: tin must be exactly 10 digits", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "403": { "description": "This workspace cannot onboard companies in this country.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_ONBOARDING_ACCESS_DENIED", "message": "Your role cannot onboard companies.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } }, "/v3/connect/companies/{sourceName}": { "parameters": [ { "name": "sourceName", "in": "path", "required": true, "description": "The source name, as returned when the company was created.", "schema": { "type": "string" }, "example": "acme-dubai" }, { "name": "sourceVersion", "in": "query", "required": false, "description": "The source version. Send it to pick the version explicitly.", "schema": { "type": "string" }, "example": "v1" } ], "get": { "operationId": "getCompany", "tags": [ "Connect" ], "summary": "Get a company source", "description": "Returns one company source.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#retrieve-update-or-archive-a-source" }, "responses": { "200": { "description": "The source, in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "sourceName": "acme-dubai", "sourceVersion": "v1", "legalName": "Acme Trading LLC", "legalIdentifier": null, "countryCode": "AE", "status": "active", "sourceId": "01JABCDEF1234567890SOURCE", "branchId": "66b9f0b2c2d3e4f567890456", "branchName": "Dubai", "tin": "1234567890", "vatTrn": "123456789000003", "mappingReadiness": { "status": "READY", "templateId": "default-gets-66b9e000c2d3e4f567890000" }, "readyForInvoicing": true, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-22T10:00:00.000Z" }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "404": { "description": "No source with this name and version in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_COMPANY_NOT_FOUND", "message": "Company source 'acme-dubai' not found.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } }, "patch": { "operationId": "updateCompany", "tags": [ "Connect" ], "summary": "Update a company source", "description": "Changes a source's details. Send only the fields you want to change. This does not replace country onboarding.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#retrieve-update-or-archive-a-source" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompany" }, "example": { "legalName": "Acme Trading LLC" } } } }, "responses": { "200": { "description": "The updated source, in `data`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "sourceName": "acme-dubai", "sourceVersion": "v1", "legalName": "Acme Trading LLC", "legalIdentifier": null, "countryCode": "AE", "status": "active", "sourceId": "01JABCDEF1234567890SOURCE", "branchId": "66b9f0b2c2d3e4f567890456", "branchName": "Dubai", "tin": "1234567890", "vatTrn": "123456789000003", "mappingReadiness": { "status": "READY", "templateId": "default-gets-66b9e000c2d3e4f567890000" }, "readyForInvoicing": true, "createdAt": "2026-09-22T10:00:00.000Z", "updatedAt": "2026-09-23T09:15:00.000Z" }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "400": { "$ref": "#/components/responses/ConnectValidation" }, "404": { "description": "No source with this name and version in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_COMPANY_NOT_FOUND", "message": "Company source 'acme-dubai' not found.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } }, "delete": { "operationId": "archiveCompany", "tags": [ "Connect" ], "summary": "Archive a company source", "description": "Archives the source: it becomes `inactive` and any scheduled allowance is cancelled. Its document history is kept.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#retrieve-update-or-archive-a-source" }, "responses": { "200": { "description": "The source was archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "archived": true, "companyId": "66b9f0a1c2d3e4f567890123", "sourceName": "acme-dubai" }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "404": { "description": "No source with this name and version in your workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_COMPANY_NOT_FOUND", "message": "Company source 'acme-dubai' not found.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } }, "/v3/connect/companies/{companyId}/branches": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "The `companyId` returned when the company was created or listed. 24 hexadecimal characters.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "example": "66b9f0a1c2d3e4f567890123" } ], "post": { "operationId": "addBranch", "tags": [ "Connect" ], "summary": "Add a branch", "description": "Adds a branch, with its own source, to an onboarded UAE company. The branch uses the company's environment.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#add-branches" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" }, "example": { "branchName": "Abu Dhabi", "sourceName": "acme-abu-dhabi", "sourceVersion": "v1" } } } }, "responses": { "201": { "description": "The branch and its source were created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "branchId": "66b9f0c3c2d3e4f567890789", "branchName": "Abu Dhabi", "userGivenBranchId": "acme-abu-dhabi", "sourceId": "01JABCDEF1234567890SRCAUH", "sourceName": "acme-abu-dhabi", "sourceVersion": "v1", "platformEnvironment": "sandbox", "readyForInvoicing": false, "mappingReadiness": { "status": "ACTION_REQUIRED", "code": "CONNECT_MAPPING_NOT_CONFIGURED" } }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "400": { "$ref": "#/components/responses/ConnectValidation" }, "409": { "description": "A source with this name and version already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_SOURCE_ALREADY_EXISTS", "message": "Source 'acme-abu-dhabi' (version v1) already exists in this workspace.", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } }, "/v3/connect/companies/{companyId}/branches/bulk": { "parameters": [ { "name": "companyId", "in": "path", "required": true, "description": "The `companyId` returned when the company was created or listed. 24 hexadecimal characters.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "example": "66b9f0a1c2d3e4f567890123" } ], "post": { "operationId": "addBranches", "tags": [ "Connect" ], "summary": "Add branches in bulk", "description": "Adds 1–100 branches to an onboarded UAE company. Each branch succeeds or fails on its own: check every result.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/companies/#add-branches" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "branches" ], "additionalProperties": false, "properties": { "branches": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Branch" } } } }, "example": { "branches": [ { "branchName": "Abu Dhabi", "sourceName": "acme-abu-dhabi", "sourceVersion": "v1" }, { "branchName": "Sharjah", "sourceName": "acme-sharjah", "sourceVersion": "v1" } ] } } } }, "responses": { "200": { "description": "Every branch was processed. Failed branches do not undo successful ones.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "processed": 2, "succeeded": 1, "failed": 1, "results": [ { "branchName": "Abu Dhabi", "sourceName": "acme-abu-dhabi", "sourceVersion": "v1", "success": true, "data": { "companyId": "66b9f0a1c2d3e4f567890123", "branchId": "66b9f0c3c2d3e4f567890789", "branchName": "Abu Dhabi", "userGivenBranchId": "acme-abu-dhabi", "sourceId": "01JABCDEF1234567890SRCAUH", "sourceName": "acme-abu-dhabi", "sourceVersion": "v1", "platformEnvironment": "sandbox", "readyForInvoicing": false, "mappingReadiness": { "status": "ACTION_REQUIRED", "code": "CONNECT_MAPPING_NOT_CONFIGURED" } } }, { "branchName": "Sharjah", "sourceName": "acme-sharjah", "sourceVersion": "v1", "success": false, "error": { "code": "CONNECT_SOURCE_ALREADY_EXISTS", "message": "Source 'acme-sharjah' (version v1) already exists in this workspace.", "retryable": false } } ] }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "workspaceId": "66b9e000c2d3e4f567890000" } } } } }, "400": { "$ref": "#/components/responses/ConnectValidation" }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } }, "/v3/connect/invoices/counts": { "get": { "operationId": "countDocuments", "tags": [ "Connect" ], "summary": "Count documents", "description": "Counts valid sales and purchase documents for your managed companies in one country, all time or in a date range.", "security": [ { "apiKey": [] } ], "externalDocs": { "url": "/api-reference/connect/invoice-counts/" }, "parameters": [ { "name": "X-Environment", "in": "header", "required": false, "description": "Which environment to count. Defaults to `production`, so send it explicitly.", "schema": { "type": "string", "enum": [ "sandbox", "production" ], "default": "production" }, "example": "sandbox" }, { "name": "countryCode", "in": "query", "required": true, "description": "Country to count.", "schema": { "type": "string", "enum": [ "AE", "SA", "MY", "BE", "DE" ] }, "example": "AE" }, { "name": "companyId", "in": "query", "required": false, "description": "One company. Leave empty to count every managed company in the country.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "name": "documentType", "in": "query", "required": false, "description": "Only sales or only purchase documents. Leave empty for both.", "schema": { "type": "string", "enum": [ "sales", "purchase" ] } }, { "name": "from", "in": "query", "required": false, "description": "First day, `YYYY-MM-DD`, in the country's local calendar. Send with `to`.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-01" }, { "name": "to", "in": "query", "required": false, "description": "Last day, `YYYY-MM-DD`, inclusive. Send with `from`.", "schema": { "type": "string", "format": "date" }, "example": "2026-09-30" } ], "responses": { "200": { "description": "Counts for the country, and for each company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSuccess" }, "example": { "success": true, "data": { "totalCount": 25, "salesCount": 17, "purchaseCount": 8, "companies": [ { "companyId": "66b9f0a1c2d3e4f567890123", "totalCount": 20, "salesCount": 14, "purchaseCount": 6 }, { "companyId": "66b9f0a1c2d3e4f567890456", "totalCount": 5, "salesCount": 3, "purchaseCount": 2 } ] }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z", "filters": { "countryCode": "AE", "environment": "sandbox", "companyId": null, "documentType": null, "from": "2026-09-01", "to": "2026-09-30" } } } } } }, "400": { "description": "A filter is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "examples": { "range": { "summary": "Incomplete range", "value": { "success": false, "error": { "code": "CONNECT_DATE_RANGE_INCOMPLETE", "message": "Send both from and to, or neither." }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } }, "country": { "summary": "Unsupported country", "value": { "success": false, "error": { "code": "CONNECT_UNSUPPORTED_COUNTRY", "message": "countryCode must be one of AE, SA, MY, BE, DE." }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } } } }, "401": { "$ref": "#/components/responses/InvalidKey" }, "429": { "$ref": "#/components/responses/ConnectRateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key, as `Authorization: Bearer YOUR_API_KEY`." }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your ISV workspace API key." } }, "schemas": { "UnifyRequest": { "type": "object", "required": [ "country", "environment", "purpose", "source", "documentType", "payload" ], "properties": { "country": { "type": "string", "enum": [ "AE", "SA", "OM", "MY", "BE", "DE" ], "description": "ISO 3166-1 alpha-2 code of the country the document is for." }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Must match your API key: a sandbox key for `sandbox`, a production key for `production`." }, "purpose": { "type": "string", "enum": [ "invoicing" ], "description": "`invoicing` validates and submits the document." }, "source": { "type": "string", "pattern": "^[^:]+:[^:]+$", "description": "Your source as `name:version`, from onboarding." }, "documentType": { "type": "object", "required": [ "base", "modifiers" ], "description": "Decides which payload fields are required.", "properties": { "base": { "type": "string", "description": "For example `tax_invoice` or `credit_note`." }, "modifiers": { "type": "array", "items": { "type": "string" }, "description": "Send an empty array when none apply." }, "variant": { "type": "string" } } }, "payload": { "type": "object", "description": "The invoice in the structure expected by your source's mapping. See the GETS field reference for fields used in country validation." } } }, "UnifyAccepted": { "type": "object", "required": [ "documentId", "message", "Base64XML" ], "properties": { "documentId": { "type": "string", "description": "Keep it to look the document up later." }, "documentNumber": { "type": "string" }, "message": { "type": "string" }, "Base64XML": { "type": "string", "description": "The generated e-invoice XML, Base64-encoded. Empty for countries where it is not produced at this point." } } }, "UnifyValidationError": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": [ "string", "null" ], "description": "The rule identifier, for example `IBR-015` or a Saudi `BR-KSA-*` rule." }, "getsPath": { "type": [ "string", "null" ], "description": "The field in GETS." }, "payloadPath": { "type": [ "string", "null" ], "description": "The field in the payload you sent." }, "message": { "type": "string" }, "severity": { "type": [ "string", "null" ] }, "ruleSet": { "type": [ "string", "null" ], "description": "The rules the document was checked against, as `country:documentType`." } } }, "UnifyValidationFailure": { "type": "object", "required": [ "message", "errors" ], "properties": { "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "message": { "type": "string" }, "validationStage": { "type": "string", "enum": [ "gets", "xml" ], "description": "`gets` when a field or rule failed. `xml` when producing the e-invoice failed: contact support with the `documentId`." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/UnifyValidationError" } } } }, "UnifyProblem": { "type": "object", "description": "Either `error`, or `code` and `message`.", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "DocumentsError": { "type": "object", "required": [ "success", "code", "message" ], "properties": { "success": { "const": false }, "code": { "type": "string" }, "message": { "type": "string" } } }, "PurchaseList": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] } } } } }, "SalesDocument": { "type": "object", "description": "Where a submitted document is in processing.", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "documentId": { "type": "string" }, "documentNumber": { "type": "string" }, "country": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "state": { "type": "string", "enum": [ "rejected", "submitted", "processing", "delivery_success", "delivery_failed", "final_valid", "final_invalid" ] }, "isTerminal": { "type": "boolean", "description": "`true` once processing has finished." }, "lastUpdatedAt": { "type": "string", "format": "date-time" }, "errors": { "type": "array", "items": { "type": "object" } }, "government": { "type": "object" }, "validationResults": { "type": "object" } } } } }, "PurchaseDocument": { "type": "object", "description": "A received purchase invoice with its data.", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object" }, "xml": { "type": "string" } } } } }, "ConnectMeta": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Quote it when you contact support." }, "timestamp": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string" } } }, "ConnectSuccess": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "const": true }, "data": {}, "meta": { "$ref": "#/components/schemas/ConnectMeta" } } }, "ConnectError": { "type": "object", "required": [ "success", "error", "meta" ], "properties": { "success": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string", "description": "Wording can change. Act on `code`." }, "retryable": { "type": "boolean", "description": "Whether the same request can be retried." }, "details": { "type": "object" } } }, "meta": { "$ref": "#/components/schemas/ConnectMeta" } } }, "MappingReadiness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "READY", "ACTION_REQUIRED" ] }, "templateId": { "type": "string", "description": "Only when `READY`." }, "code": { "type": "string", "enum": [ "CONNECT_MAPPING_NOT_CONFIGURED", "CONNECT_MAPPING_INELIGIBLE", "CONNECT_MAPPING_CONFLICT", "CONNECT_MAPPING_LINK_FAILED" ], "description": "Only when `ACTION_REQUIRED`." } } }, "CreateCompany": { "type": "object", "additionalProperties": false, "required": [ "sourceName", "sourceVersion", "countryCode", "tin", "contactPersonEmail", "branchName", "platformEnvironment" ], "properties": { "sourceName": { "type": "string", "minLength": 1, "description": "Unique with `sourceVersion` in your workspace." }, "sourceVersion": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string", "enum": [ "AE" ] }, "tin": { "type": "string", "pattern": "^[0-9]{10}$", "description": "UAE tax identification number, exactly 10 digits." }, "contactPersonEmail": { "type": "string", "format": "email", "description": "The email the company's ASP authorization was registered with. A different email returns `ASP_LINKAGE_NOT_FOUND`." }, "contactPersonName": { "type": "string" }, "contactPersonMobile": { "type": "string", "pattern": "^\\+?[0-9]+$", "description": "Digits with an optional leading `+`, no spaces." }, "branchName": { "type": "string", "minLength": 1, "description": "Name of the first branch." }, "platformEnvironment": { "type": "string", "enum": [ "sandbox", "simulation", "production" ] } } }, "CompanyCreated": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "companyId": { "type": "string" }, "sourceId": { "type": "string" }, "branchId": { "type": "string" }, "userGivenBranchId": { "type": "string", "description": "Share it with suppliers as the buyer reference." }, "readyForInvoicing": { "type": "boolean" }, "mappingReadiness": { "$ref": "#/components/schemas/MappingReadiness" } } }, "meta": { "$ref": "#/components/schemas/ConnectMeta" } } }, "CompanyList": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/ConnectMeta" } } }, "UpdateCompany": { "type": "object", "properties": { "sourceVersion": { "type": "string" }, "legalName": { "type": "string" }, "legalIdentifier": { "type": "string" }, "countryCode": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "metadata": { "type": "object" } } }, "Branch": { "type": "object", "additionalProperties": false, "required": [ "branchName", "sourceName", "sourceVersion" ], "properties": { "branchName": { "type": "string", "minLength": 1 }, "sourceName": { "type": "string", "minLength": 1 }, "sourceVersion": { "type": "string", "minLength": 1 } } }, "OnboardingJobRequest": { "type": "object", "required": [ "countryCode", "rows" ], "properties": { "countryCode": { "type": "string", "enum": [ "AE", "SA", "MY" ] }, "filename": { "type": "string", "description": "A label for the job." }, "platformEnvironment": { "type": "string", "enum": [ "sandbox", "simulation", "production" ], "description": "Defaults to `sandbox`. A row can set its own." }, "rows": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Each row needs `sourceName`. UAE rows also need `tin`, `contactPersonEmail` and `branchName`; Saudi and Malaysian rows need `legalName`. `sourceVersion` defaults to `1.0`.", "items": { "type": "object" } } } } }, "responses": { "InvalidKey": { "description": "The API key is missing, invalid or revoked. This body has no `success` wrapper.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "key_revoked" ] }, "message": { "type": "string" } } }, "example": { "code": "invalid_api_key", "message": "Invalid API key" } } } }, "ConnectValidation": { "description": "A field is missing, malformed or not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_VALIDATION_ERROR", "message": "tin must be exactly 10 digits", "retryable": false }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } } }, "ConnectRateLimited": { "description": "Too many requests for this workspace. Wait for `Retry-After` seconds, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectError" }, "example": { "success": false, "error": { "code": "CONNECT_RATE_LIMIT_EXCEEDED", "message": "Rate limit exceeded.", "retryable": true, "details": { "retryAfterSec": 30 } }, "meta": { "requestId": "01K5EXAMPLE0000000REQUEST", "timestamp": "2026-09-22T10:00:00.000Z" } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } } } } }