API Docs

Not all APIs are created equal - transform your connectivity with DataShare API

Getting Started

DataShare API is organised around REST. Our API accepts form-encoded request bodies, returning JSON-encoded responses, and zipped CSV extracts. It uses standard HTTP response codes and OAuth2 authentication.

We offer Postman Scripts and Swagger Docs to help you get started as soon as you have an API key.


A sandbox environment is available for testing. You are only allowed to use test data in this environment. To gain access to this environment, contact your Validis representative.

After application certification, promotion to production will be approved.

Region Url Description
Sandbox https://api.sandbox.validis.com/ Non-production sandbox environment
United Kingdom https://api.uk.validis.com/ UK production environment
United States https://api.us.validis.com/ US production environment
Canada https://api.ca.validis.com/ Canada production environment
Australia https://api.au.validis.com/ Australia production environment


The release of new APIs will be communicated to partners who will be given time to update their systems before old versions are deprecated.


Major version Release Date Comment
v21.3 Mar 2021 Enhancements to Delete and New Endpoint jeCompliance report
v21.1 Jan 2021 Enhancements to existing endpoints
v2.99 Nov 2020 New Endpoints Audit WorkFlow, enhancements to existing endpoints
v2.95 Aug 2020 New Endpoints Delete, Passthrough, Working Papers
v2.91 May 2020 Endpoints moved out of beta
v2.90 April 2020 v2 Extracts endpoints released
v2.89 March 2020 Beta Swagger added, Displayflipped added FAQs
v2.86 February 2020 Selective Data Push(Beta), Group Invoice Linkage
v2.84 December 2019 Processing Back-Off, Exposing Detailed Endpoints, COA Tags Descriptions, Data Refresh Scheduler
v2.82 November 2019 Data Refresh, Python sample code, Add line numbers to code sample
v2.78 Aug 2019 Multiple: Theme Change, new endpoint releases, new endpoint parameters, updated postman collection
v1 Nov 2018 New endpoints for GL Journals, Account Receivable Items, and Account Payable Items
v1 Jun 2018 First DataShare API version exposing endpoints to get and create engagements, trigger and get uploads, generate major reports



When the DataShare API product is enabled the option to use a webhook for notifications is available. Notifications will be sent out whenever there is a change in status for an upload.


Users with appropriate permission will be able to set up the configuration in the System Configuration section of Datashare Admin.

You will be able to set the following configuration:

  • Webhook On/Off switch
  • Webhook URL – Set the URL including the correct protocol of where the notification will be sent to



Parameter Description
This will be UPLOAD as currently the only webhook service we are supplying will be on the change of Upload status.
This is the upload status and will be one of the following: LOADING, ABORTED, PROCESSING, FAILED, or COMPLETED.
The unique identifier of your organisation within the DataShare system.
This is the unique identifier for the engagement.
This is the unique identifier for the upload.
This the root url to use when requesting data via API.

HTTP Status Codes

Status Code Description
200 OK General success status code. Most common code to indicate success
201 Created The request has succeeded and a new resource has been created as a result.
202 Accepted The request has been received but not yet acted upon. It is noncommittal, since there is no way in HTTP to later send an asynchronous response indicating the outcome of the request.
400 Bad Request General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples
401 Unauthorized Error code for a missing or invalid authentication token
403 Forbidden Error code for user not authorized to perform the operation, doesn’t have rights to access the resource, or the resource is unavailable for some reason (e.g. time constraints, etc.)
404 Not Found Used when the requested resource is not found, whether it doesn’t exist or if there was a 401 or 403 that, for security reasons, the service wants to mask
406 Not Acceptable Response Error code provided when an HTTP Accept header can’t be satisfied.
409 Uniqueness Violation Error code provided when the same request is in process
429 Too many requests Error code provided when the rate limit has been hit
500 Internal Server Error The general catch-all error when the server-side throws an exception.

Rate Limiting

Each API key(Primary and Secondary provided) is limited to 5000 API calls per rolling 24 hour period. Tips to minimise calls:

  • Only pull data in response to a successful upload identified by a webhook
  • For large data analytics use cases, there are endpoints which allow you to pull all the data. Please refresh the data as identified by the status in the LastUpload endpoint or webhook payload.

Secondary API Key

The secondary API key can be used for a separate application, or as a failover once the call limit of the primary API key has been reached.

API Key Expiry

When an API key expires due to rate limiting, you will receive a statusCode: 429, message: Rate limit is exceeded. Try again in <duration>.

Beta Endpoints

Endpoints noted as Beta will go through iterative updates, and this will include breaking changes which will be highlights weeks before release.