logo
API docs by Redocly

Tax Agile API Specification (1.4.2)

Download OpenAPI specification:

URL: https://vatcalc.freshdesk.com/support/home
Latest API Release Notes

Tax Agile API provides a RESTful implementation of the functionality in our web application.

Requres an Account ID and API Key pair for the POST /v1/auth endpoint which will return a short-lived JWT Bearer token in the response.

Use the Bearer token in the Authorization header of subsequent requests.

Please contact us if you would like a demo and access.

Find out more about our products on our website vatcalc.com

VAT Auditor

Complete an Audit of VAT compliance on your data.

Create a new audit.

Submit transaction data to VAT Auditor

Send it as either body JSON, or as an Excel xlsx as multipart form-data, which has been mapped to our data model.

This endpoint returns with an operation token to use with the GET /operations/{id} endpoint to poll for the Audit completion.

In v1.3.0 we added the POST /datamanager/vat/uploads endpoint which should now be used for sending data to VAT Filer, previously this resource supported that use-case, but that is now deprecated.

In v1.3.1 we added validation to the json payload that dates are in the format 'YYYY-MM-DD'.

Authorizations:
BearerAuth
Request Body schema:
required

The request can be sent as an application/json in the request body, or a multipart/form-data.

application/json

An array of data [ vatDataModelSchema ] transactions, plus an options object which specifies how the system handles the Audit. When sending Tax Agile data model format JSON, the mappingId should be set to 'default'.

multipart/form-data

The form two fields 'file' and 'options'.

  • The 'options' field takes a json {} with the Audit options.

  • The 'file' field takes a file object which can be either an Excel xlsx file, or an Avalara iVAT Reporting XML file.

If sending the Avalara XML format you must set the Content-Type of the 'file' field to application/vnd.avalara.ivat.reporting+xml and the mappingId set to vnd.avalara.ivat.reporting+xml.

Check out the example in the Postman Sample Collection as the multipart/form-data request has it's own Content-Type, as does the 'options' field.

Note: Maximum file size 5mb

Array of objects (VAT Data Model)
object (VAT Upload - Options)

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "_id": "ceb50cb0-0135-4fdf-bcd3-dbfc9d4d9adc",
  • "href": "/v1/operations/ceb50cb0-0135-4fdf-bcd3-dbfc9d4d9adc"
}

Summary list of audits.

Lists the (100) most recent audits.

If there a no items in the list this will return an empty array, on a 200 OK.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Summary of a specific audit.

The {id} for the path parameter is provided by the GET /operations/{id} response as the href field in the body and also the location header.

It is also avaialable from the summary list of audits GET /auditor/vat/audits endpoint.

The response body is a summary of the audit including metrics, data summary, datasource information, and includes results href.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 9A8FL3X3hr6I0QSLNFAA

Id of the audit

Responses

Response samples

Content type
application/json
{
  • "_id": "i1yKcOrT2Rv9neYsKwvG",
  • "entryDateTime": "2023-05-18T09:45:57.204Z",
  • "summary": {
    },
  • "dataDetails": {
    },
  • "options": {
    },
  • "results": {
    }
}

Removes audit results and data from the platform.

Deletes audit and associated data.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 9A8FL3X3hr6I0QSLNFAA

Id of the specific audit

Responses

Response samples

Content type
application/json
{
  • "errorCode": "VA008",
  • "message": "Audit Id is a mandatory path parameter"
}

Results of a specific audit.

The {id} for the path parameter is provided by the GET /operations/{id} response as the href field in the body and also the location header.

It is also avaialable from the summary list of audits GET /auditor/vat/audits endpoint.

The response body is an array of transactions, showing data errors, audit check issues and successful transactions.

To get a JSON summary of each error in the audit, use the format=errorList query parameter only (don't combine with pageSize and startAfter). It returns the first 10,000 errors.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 9A8FL3X3hr6I0QSLNFAA

Id of the audit

query Parameters
pageSize
integer
Example: pageSize=100

State the number of transactions to return in the response.

Maximum value 1000. If not provided defaults to 20.

startAfter
string
Example: startAfter=b5e9282e-8a40-4462-81c3-2ab28b904f57

When moving through the results dataset provide the id of the last transaction in the previous page, and the response will 'startAfter' that transaction.

Leave blank to receive the first page of data.

format
string
Example: format=errorList

Use format=errorList to get a list of each error. Limited to 10,000 records.

Responses

Response samples

Content type
application/json
Example
{
  • "transactions": [
    ],
  • "count": {
    },
  • "next": {
    },
  • "first": {
    }
}

VAT Calculator

Use our engine to do VAT determination on transactions.

Send a transaction and receive a VAT determination.

Send a transaction to the determination engine for VAT. The request body supports a large number of conditions which may be true on your transaction, but all are not required. It can be helpful to use VAT Advisor to enter a sample transaction to understand the request body you need to send. The transaction can be stored if you include the query parameter commit=true if stored, the response will provide a uuid.

Authorizations:
BearerAuth
query Parameters
commit
string
Example: commit=true

Optional, defaults to false; if true the transaction is stored and a unique id is provided in the response.

useTaxCodes
string
Example: useTaxCodes=true

Optional, defaults to false; if true the engine will check the ERP tax codes setup in our system and return the matching ERP code.

taxCodeScheme
string
Example: taxCodeScheme=avalara

Optional, if used it specifies which kind of taxCode to return. Must be used with useTaxCodes=true

Request Body schema: application/json
required

The payload body requires a JSON object which represents the transaction. If fields are missing, the API will return a response object with context enriched guidance on how to correct the request. Then the caller can resend an updated transaction

object
object
object
object
object
object
object
object
object
object
object
object
object
object
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "transaction1": "Supply of goods - BE - Intra-Community supply - N/A - 0 - 0 - 0",
  • "transaction2": "N/A - N/A - No exemption - N/A",
  • "rateT1": 0,
  • "reversedOutputVat": 0,
  • "reversedOutputVatRate": 0,
  • "deductibleInputVat": 0,
  • "invoiceMentioning": "Article 138(1) Directive 2006/112 EC",
  • "invoiceMentioningEu": "Article 138(1) Council Directive 2006/112 EC",
  • "taxableTransactionT1": "Supply of goods",
  • "transType": "Intra-Community supply",
  • "posT1": "BE",
  • "exemptionDescriptionT1": "Intra-Community supply",
  • "obligationToPayT1": "N/A",
  • "taxPoint": "2025-05-09T00:00:00.000Z",
  • "deductibleRate": 0,
  • "sellerVatNo": "BE",
  • "buyerVatNo": "DE",
  • "baseAmount": 100,
  • "vatAmount": 0,
  • "importVatAmount": 0,
  • "vatCode": "BESICSG000",
  • "taxCode": [
    ],
  • "peppolVatexCode": "VATEX-EU-79-C",
  • "peppolTaxCategoryId": "K",
  • "calculatedRate": 0,
  • "uuid": "fea0f7da-074e-47e9-8bde-51b8b5f778da",
  • "vatBoxes": [
    ],
  • "provisions": [
    ]
}

Fetch a collection of transactions with filter params.

Returns a paginated dataset of the committed (saved) transactions stored on the platform. Takes filter criteria as query parameters and sets defaults to ensure a huge dataset is not fetched. Can be used to collect data periodically to store in your analysis data store; or to build an interactive dashboard in your application.

Authorizations:
BearerAuth
query Parameters
entryDateTimeFrom
string
Example: entryDateTimeFrom=2022-06-28T00:00:00.000Z

Datetime stamp in UTC ISO string format from which to select transactions to return. Optional, if not provided it defaults to current date time -30 days.

entryDateTimeTo
string
Example: entryDateTimeTo=2022-06-28T23:59:59.999Z

Datetime stamp in UTC ISO string format of the end of the date time range. Optional, no default if not provided.

page
string
Example: page=1

The page number of the result set you want to fetch. Optional, defaults to 1.

pageSize
string
Example: pageSize=20

The number of transactions to return in a page of results. Optional, defaults to 20.

docNumber
string
Example: docNumber=12345678

Filter result set by matching a document number provided on the original request.

vatCode
string
Example: vatCode=BESICSG000

Filter result set by matching a VAT code from the VAT determination made by our engine.

Responses

Response samples

Content type
application/json
{
  • "count": 25,
  • "next": {
    },
  • "previous": {
    },
  • "data": [
    ]
}

Return a specific transaction by id.

Providing the id of the transaction will fetch the transaction from the Tax Agile platform; by default it returns a summary of the payload sent in, and our response back.

Using the ?detail=true query parameter returns a detail representation of the transaction and how it was processed by our engine.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: f17b19f2-391c-46b4-9857-025cb0d64a51

Uuid of the transaction

query Parameters
detail
boolean
Example: detail=true

Optional parameter to fetch a detailed representation of the transaction; if not used it defaults to a summary

Responses

Response samples

Content type
application/json
Example
{
  • "request": {
    },
  • "response": {
    },
  • "entryDateTime": "2022-06-28T14:12:35.000Z",
  • "_id": "7942cf02-2067-4b37-8e00-e3bd3926d6e5",
  • "source": "calculator-api"
}

VAT Filer

VAT Filer provides filings, filing events, filing reports, based on data loaded using Data manager.

List available filings

Returns a paginated list of filings available on the platform. Use the returned id values as the filingId when setting up filing events on company registrations.

Authorizations:
BearerAuth
query Parameters
countryCode
string = 2 characters
Example: countryCode=BE

Filter by ISO 3166-1 alpha-2 country code (e.g. GB, DE)

category
string (filingCategories)
Enum: "vat-return" "vat-book" "annual-vat-return" "ec-sales-listing" "intrastat-arrivals" "intrastat-dispatches" "customer-listing" "intrastat-combined" "oss-return" "union-oss-return" "saf-t" "ec-purchase-listing" "ec-combined-listing" "supplier-and-customer-listing" "register"
Example: category=vat-return

Filter by filing category

page
integer >= 1
Default: 1

Page number (1-based)

pageSize
integer >= 1
Default: 10

Number of results per page

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "page": 0,
  • "pageSize": 0,
  • "next": {
    },
  • "previous": {
    }
}

List filing events

Returns a paginated list of filing events based on company setup on the account, filtered by due date range. The date range must not exceed 365 days.

Authorizations:
BearerAuth
query Parameters
dueDateFrom
required
string <date>
Example: dueDateFrom=2025-01-01

Start of due date range (inclusive), format YYYY-MM-DD

dueDateTo
required
string <date>
Example: dueDateTo=2025-12-31

End of due date range (inclusive), format YYYY-MM-DD. Must be ≥ dueDateFrom and within 365 days of it.

companyId
string
Example: companyId=2cb5fb93-64ca-4ce2-ae3f-ad9d67c90578

Filter by company ID

companyCode
string
Example: companyCode=ABC123

Filter by company code

countryCode
string
Example: countryCode=BE

Filter by country code

filingCategory
string (filingCategories)
Enum: "vat-return" "vat-book" "annual-vat-return" "ec-sales-listing" "intrastat-arrivals" "intrastat-dispatches" "customer-listing" "intrastat-combined" "oss-return" "union-oss-return" "saf-t" "ec-purchase-listing" "ec-combined-listing" "supplier-and-customer-listing" "register"
Example: filingCategory=vat-return

Filter by filing category

status
string (filingStatus)
Enum: "Open" "Draft" "Approved" "Submitted"

Filter by filing status

preparerUserId
string

Filter by preparer identifier (id)

reviewerUserId
string

Filter by reviewer identifier (id)

submitterUserId
string

Filter by submitter identifier (id)

periodKey
string
Example: periodKey=12-2026

Filter by period key

page
integer >= 1
Default: 1

Page number (1-based)

pageSize
integer [ 1 .. 200 ]
Default: 50

Number of results per page (max 200)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "next": {
    },
  • "previous": {
    }
}

Get report options for a filing event

Returns the available report options for the identified filing event, including links to the view and filing report endpoints.

Authorizations:
BearerAuth
path Parameters
companyId
required
string
Example: 916b42c6-07d6-49cb-a44d-4d9c24e46363

The company ID

filingId
required
string
Example: 6lxvlAsBZikljpKymB5R

The filing ID

periodKey
required
string
Example: 11-2025

The period key

Responses

Response samples

Content type
application/json
{
  • "view": {
    },
  • "filing": {
    }
}

Retrieve an HTML view report

Returns the specified report for the filing event. The view report returns an HTML page. All other report types return a message directing callers to use POST for filing reports.

First call the metadata endpoint to understand the options available, like languages available.

Authorizations:
BearerAuth
path Parameters
companyId
required
string
Example: 916b42c6-07d6-49cb-a44d-4d9c24e46363

The company ID

filingId
required
string
Example: 6lxvlAsBZikljpKymB5R

The filing ID

periodKey
required
string
Example: 11-2025

The period key

report
required
string
Value: "filing"

The type of report

query Parameters
lang
string
Example: lang=eng

Language code for the report (ISO 639-2, e.g. pol, eng, default)

Responses

Response samples

Content type
application/json
Example
{
  • "errorCode": "VFR002",
  • "message": "Use POST for reports/filing"
}

Generate a filing report - e-File (xml, csv, txt, boe)

Generates the output filing document for the identified filing event. The report path parameter must be filing.

First call the metadata endpoint to know the questions to answer as part of this generation.

Provide any required questionnaire answers and the required formatId in the request body.

Authorizations:
BearerAuth
path Parameters
companyId
required
string
Example: 916b42c6-07d6-49cb-a44d-4d9c24e46363

The company ID

filingId
required
string
Example: 6lxvlAsBZikljpKymB5R

The filing ID

periodKey
required
string
Example: 11-2025

The period key

report
required
string
Value: "filing"

The type of report

Request Body schema: application/json
required
formatId
required
string

Specific format definition ID, as shown by the metadata endpoint

required
Array of objects (filingReportQuestion)

Answered questionnaire questions

Responses

Request samples

Content type
application/json
{
  • "formatId": "008e23c7-e749-4151-9f91-16b7568a2b24",
  • "questions": [
    ]
}

Response samples

Content type
No sample

Get filing report metadata

Returns the available output formats for the filing report. Optionally filter by formatId or format (mutually exclusive) to retrieve the matching format definition including its questionnaire questions.

Authorizations:
BearerAuth
path Parameters
companyId
required
string
Example: 916b42c6-07d6-49cb-a44d-4d9c24e46363

The company ID

filingId
required
string
Example: 6lxvlAsBZikljpKymB5R

The filing ID

periodKey
required
string
Example: 11-2025

The period key

report
required
string
Value: "filing"

The report type — must be filing for metadata

query Parameters
formatId
string

Return metadata for a specific format definition ID. Mutually exclusive with format.

format
string

Return metadata filtered by format extension (e.g. xml, csv). Mutually exclusive with formatId.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "extension": "string"
}

Authentication

Use API key to fetch a short-lived session JWT.

Authenticate API Key to receive a Bearer token.

Use API key and accountId to authenticate, and receive a time-based Bearer token which is then used on subsequent requests in the Authorization header.

Authorizations:
BearerAuth
Request Body schema: application/json
required
apiKey
required
string [ 1 .. 40 ] characters

The API key issued by Tax Agile

accountId
required
string [ 1 .. 100 ] characters

The account id issued by Tax Agile

Responses

Request samples

Content type
application/json
{
  • "apiKey": "d9b97d76-5b6c-426f-9625-a1f63b7e195b",
  • "accountId": "1Qwj3WEgtaABCCkzgkAL"
}

Response samples

Content type
application/json
{
  • "expiresIn": 86400,
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50SWQiOiJERU1PIiwiaWF0IjoxNjUzMDU3MjU2LCJleHAiOjE2NTMxNDM2NTZ9.bSMQE3mRHL0LGl9Fpn3rl8wJkvQC7WN9N-U7ikwaavQ",
  • "tokenType": "Bearer"
}

VAT Data manager

VAT Data manager for uploads - includes details of the data pipeline options selected.

Create an upload of data with data pipeline options.

Send data in either json or multi-part form data.

Providing options which link the upload to pipeline options like enrichment and sending to Filer or Auditor.

In v1.3.1 we added validation to the json payload that dates are in the format 'YYYY-MM-DD'.

In v1.3.3 we added the ability to send JSON and use a data mapping to transform incomplete JSON into our Tax Agile JSON format.

Authorizations:
BearerAuth
Request Body schema:
required

The request can be sent as an application/json in the request body, or a multipart/form-data file.

application/json

The request body must be an object, containing a data and options object { data: [], options {}}. The data array can be in vatDataModelSchema or a bespoke format and use a data mapping to transform the body. The options object specifies the data pipeline, stating if the data is sent to Filer and/or Auditor and the data mapping id to use. When sending Tax Agile data model format JSON, the mappingId should be set to default.

multipart/form-data

The form has two fields file and options.

  • The 'options' field takes a json {} with the pipeline options.

  • The 'file' field takes a file object which can be either an Excel xlsx file, or an Avalara iVAT Reporting XML file.

If sending the Avalara XML format you must set the *Content-Type of the file field to application/vnd.avalara.ivat.reporting+xml and the mappingId set to vnd.avalara.ivat.reporting+xml.

Check out the example in the Postman Sample Collection as the multipart/form-data request has it's own Content-Type, as does the 'options' field.

Note: Maximum file size 5mb

Array of objects (VAT Data Model)
object (VAT Upload - Options)

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "_id": "ceb50cb0-0135-4fdf-bcd3-dbfc9d4d9adc",
  • "href": "/v1/operations/ceb50cb0-0135-4fdf-bcd3-dbfc9d4d9adc"
}

Summary list of the most recent 100 uploads.

Summary list of the most recent 100 uploads.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns the specific upload record.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 4e9a3622-c743-46e7-8bb0-f4fa51795164

Id of the upload

Responses

Response samples

Content type
application/json
{
  • "_id": "4e9a3622-c743-46e7-8bb0-f4fa51795164",
  • "status": "Complete",
  • "uploadDetails": {
    },
  • "options": {
    },
  • "progress": {
    }
}

Deletes the upload including the data created by the upload pipeline.

This endpoint deletes the upload resource, and the associated data created during the upload.

If sendToFiler was used when loading the data, then deleting the upload, removes the data from the returns in VAT Filer.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 4e9a3622-c743-46e7-8bb0-f4fa51795164

Id of the upload

Responses

Response samples

Content type
application/json
{
  • "errorCode": "DMV008",
  • "message": "Id is a mandatory path parameter"
}

Operations

Long running operation queues.

Status of a long-running operation.

Returns details of a long-running operation.

Use this endpoint to poll for completion of an operation. When the operation completes this endpoint returns a new location header and href in body of the new resource on a 302 See Other status.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: e7c54568-6a4a-4e73-a176-dc59d0ec5604

Uuid of the specific operation

Responses

Response samples

Content type
application/json
{
  • "_id": "7942cf02-2067-4b37-8e00-e3bd3926d6",
  • "status": "Pending | Inprogress",
  • "href": "/v1/operations/7942cf02-2067-4b37-8e00-e3bd3926d6"
}

Companies

Endpoints supporting create, list, update or delete operations on the companies resource.

Create company

Creates a new company from a JSON request body, returning a unique company internal ID.

Authorizations:
BearerAuth
Request Body schema: application/json
required
booksClosingDay
integer
companyCode
required
string

User defined short code for the company, mandatory and must be unique.

This code is used when loading transaction data for the company and when setting up tax codes.

Array of objects (companyContactRequest)

A company can have contacts and for future use it supports setting up >1 contact, but in current implementation only 1 contact is used by the application.

An empty array [] is valid.

If creating the contact as part of the company creation request, then any or all fields may be provided.

Array of VAT (object) or Sales tax (object)

Tax domain specific attributes for the company, for example VAT Domain attributes.

This is the main object sub-structure of a Company, focussing on the VAT Domain, this is where registrations and filings are provisioned.

An empty array [] is valid.

Note: This object supports different data formats for different tax domains. The documentation states oneOf and lists both VAT and Sales Tax domains, but at time of publishing (Q1/2026) only VAT Domain is implemanted.

establishedCountry
required
string = 2 characters

Main establishment country using ISO 3166-1 alpha-2 country code format.

financialYearStart
string <date>

Financial year start date in YYYY-MM-DD format.

Array of objects (companyLink)

Companies can be linked to other companies by defining parent-child relationships.

This can be where companyCode values are consolidated, or for VAT groups.

This is not mandatory and an empty array [] is valid.

Array of objects (companyLocation)

A company can have locations and for future use it supports setting up >1 location, but in current implementation only 1 location is used by the application.

This is not mandatory and an empty array [] is valid.

name
required
string

Company name.

This is presented in the UX as the full human readable name of the company.

registrationNumber
string

Company registration number.

type
required
string
Enum: "Taxable person" "Private individual" "Non-taxable legal person" "European Union body" "Embassy" "International body" "NATO"

Type of person.

Must use one of the explicit string values listed in the enumeration list.

Responses

Request samples

Content type
application/json
Example
{
  • "companyCode": "ABC123",
  • "name": "ACME Packaging Europe GMBH",
  • "establishedCountry": "BE",
  • "type": "Taxable person"
}

Response samples

Content type
application/json
{
  • "_id": "232e67cf-ff4c-41a2-a472-93a58b373ad4"
}

Get companies paginated list

Retrieves a paginated list of companies with optional filtering

Authorizations:
BearerAuth
query Parameters
page
string
Default: "1"

Page number for pagination

pageSize
string
Default: "10"

Number of items per page

companyCode
string

Filter by exact company code match

companyCodeIncludes
string

Filter by company code using trigram search

name
string

Filter by exact company name match

nameIncludes
string

Filter by company name using trigram search

establishedInCountryCode
string = 2 characters
Example: establishedInCountryCode=BE

Filter by country where company is established (ISO 3166-1 alpha-2)

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "data": [
    ],
  • "page": "string",
  • "pageSize": "string"
}

Get company by id

TODO wrong schema - Retrieves a single company by its UUID

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Company UUID

Responses

Response samples

Content type
application/json
{
  • "_id": "232e67cf-ff4c-41a2-a472-93a58b373ad4",
  • "booksClosingDay": 0,
  • "companyCode": "ABC123",
  • "contacts": [
    ],
  • "domains": [
    ],
  • "establishedCountry": "BE",
  • "financialYearStart": "2026-01-01",
  • "linkedCompanies": [
    ],
  • "locations": [
    ],
  • "name": "ACME Packaging Europe GMBH",
  • "registrationNumber": "1234567890",
  • "type": "Taxable person"
}

Update a company

Updates an existing company object.

An idempotent operation, the request body must contain the complete updated company object.

Note: The data provided in the request body will overwrite data already set, this not a PATCH, so it is not suitable for partial updates.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: 232e67cf-ff4c-41a2-a472-93a58b373ad4

Company unique internal id.

This will need to match the value provided in the request body _id field.

Request Body schema: application/json
required
_id
required
string

Unique internal identifier of the company resource.

booksClosingDay
integer
companyCode
required
string

User defined short code for the company, not mandatory but recommended to include at creation.

This code is used when loading transaction data for the company and when setting up tax codes.

Array of objects (companyContactRequest)

A company can have contacts and for future use it supports setting up >1 contact, but in current implementation only 1 contact is used by the application.

An empty array [] is valid.

If creating the contact as part of the company creation request, then any or all fields may be provided.

Array of VAT (object) or Sales tax (object)

Tax domain specific attributes for the company, for example VAT Domain attributes.

This is the main object sub-structure of a Company, focussing on the VAT Domain, this is where registrations and filings are provisioned.

An empty array [] is valid.

Note: This object supports different data formats for different tax domains. The documentation states oneOf and lists both VAT and Sales Tax domains, but at time of publishing (Q1/2026) only VAT Domain is implemanted.

establishedCountry
required
string = 2 characters

Main establishment country using ISO 3166-1 alpha-2 country code format.

financialYearStart
string <date>

Financial year start date in YYYY-MM-DD format.

Array of objects (companyLink)

Companies can be linked to other companies by defining parent-child relationships.

This can be where companyCode values are consolidated, or for VAT groups.

Array of objects (companyLocation)

A company can have locations and for future use it supports setting up >1 location, but in current implementation only 1 location is used by the application.

An empty array [] is valid.

name
required
string

Company name.

This is presented in the UX as the full human readable name of the company.

registrationNumber
string

Company registration number.

type
required
string
Enum: "Taxable person" "Private individual" "Non-taxable legal person" "European Union body" "Embassy" "International body" "NATO"

Type of person.

Must use one of the explicit string values listed in the enumeration list.

Responses

Request samples

Content type
application/json
{
  • "_id": "232e67cf-ff4c-41a2-a472-93a58b373ad4",
  • "companyCode": "ABC1234567890",
  • "name": "ACME Packaging Europe GMBH",
  • "establishedCountry": "BE",
  • "type": "Taxable person"
}

Response samples

Content type
application/json
{
  • "errorCode": "EXA001",
  • "message": "The provided <field> is not valid"
}

Delete company by id

Deletes a company by its UUID.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Company UUID

Responses

Response samples

Content type
application/json
{
  • "errorCode": "COM004",
  • "message": "Id is missing from request path"
}