Hero

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.

Environments

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

Versioning

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

Changelog

Major version Release Date Comment
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

Webhook

Overview

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.

Configuration

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

Webhook

Payload

Parameter Description
event
string
This will be UPLOAD as currently the only webhook service we are supplying will be on the change of Upload status.
status
string
This is the upload status and will be one of the following: LOADING, ABORTED, PROCESSING, FAILED, or COMPLETED.
clientId
UUID
The unique identifier of your organisation within the DataShare system.
engagementId
string
This is the unique identifier for the engagement.
uploadId
string
This is the unique identifier for the upload.
apiUrl
string
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.