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 |
| Australia | https://api.au.validis.com/ | Australia 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 |
|---|---|---|
| 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 |
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
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.