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.
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.
|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|
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|
|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
|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
||General success status code. Most common code to indicate success|
||The request has succeeded and a new resource has been created as a result.|
||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.|
||General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples|
||Error code for a missing or invalid authentication token|
||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.)|
||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|
||Error code provided when an HTTP Accept header can’t be satisfied.|
||Error code provided when the same request is in process|
||Error code provided when the rate limit has been hit|
||The general catch-all error when the server-side throws an exception.|
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>.
Endpoints noted as Beta will go through iterative updates, and this will include breaking changes which will be highlights weeks before release.