NAV Navbar

logo

Getting Started

DataShare API provides a way to manage engagements, trigger uploads, be notified when an update is available for client data uploads, and access the uploaded financial data.

REST endpoints detailed below use OAuth 2 protocol to authenticate 3rd party application. You can access financial data by 3 different solutions:

DataShare API can be used in conjunction with the DataShare portal, or as an alternative to integrate with 3rd party or proprietary systems. In both cases, software settings (API Keys, Webhook settings) must be done in DataShare Admin.

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

Environments

DataShare is available in 3 regions:

Region Url Description
United Kingdom https://api.uk.validis.com/v1 UK production environment
United States https://api.us.validis.com/v1 US production environment
Canada https://api.ca.validis.com/v1 Canada production environment

Sandbox environment

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

Region Url Description
Sandbox https://api.sandbox.validis.com/v1 Non-production sandbox environment

Versioning

APIs will be versioned using only a MAJOR number. 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 releases of the DataShare API will come with new versions of the APIs, the version history will be detailed below.

Change log

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

Nov 2018 - GL Journals, Account Receivable Items, and Account Payable Items

Following endpoints have been added:

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

The format of the notification will be::

{

“event”: “String”,

“status”: “String”,

“clientId”: “uuid”,

“engagementId”: “integer”,

“externalEngagementId”: “String”,

“uploadId”: “uuid”,

“apiUrl”: “url”

}

The fields will have the following details:

event – This will be UPLOAD as currently the only webhook service we are supplying will be on the change of Upload status.

status – This is the upload status and will be one of the following: LOADING, ABORTED, PROCESSING, FAILED, or COMPLETED.

clientId – This is your unique identifier.

engagementId – This is the unique identifier for the engagement.

uploadId – This is the unique identifier for the upload.

apiUrl – This the root url to use when requesting data via API.

Response codes

Success Response

Code Name Description
200 OK General success status code. Most common code to indicate success
201 Created Successful creation occurred (via either POST or PUT). Set the Location header to contain a link to the newly-created resource. Response body content may or may not be present.

Error Response

Code Name Description
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 If an HTTP Accept header can’t be satisfied.
500 Internal Server Error The general catch-all error when the server-side throws an exception.

Rate Limiting

Each API key is limited to 5000 API calls a day. This is a daily hard limit implemented on the server. we do not foresee any issues staying beneath this as long as these guidelines are followed: - Only pull data in response to a success upload identified by a webhook - For large data analytics use cases, use the CSVs and store the result in a database. When uploads occur, refresh the new datasets.

Beta Endpoints

Any endpoints that are noted as Beta may change without warning and will not follow the standard versioning process until they are production ready. Beta endpoints will be available in the Sandbox and may be availble in the production endpoints. If you are interested in using a Beta endpoint, contact your Validis contact who will be able to keep you updated with any changes and take into account any improvements you suggest during the Beta period.

Authenticating Your App

Overview

URL https://api.{environment}.validis.com/v1/oauth/token
Methods Supported POST

DataShare API uses API Keys and an Access Token (JSON Web Tokens - JWTs) for authentication.

At the start of a session the consumer needs to obtain a valid access token by authenticating using its API Key. Upon a successful request, the Authentication API will return a time limited JWT (valid for 30 minutes) that can be used for authentication with the other APIs in conjunction with the API key. Once expired, the consumer needs to authenticate again.

API Key

Your API key is available through DataShare Admin. Do not share this with anyone else, do not record this key in any form except for the purpose of retrieving authentication tokens. You will be given a primary and a secondary key and either can be used. You can create a new primary or secondary key, but as soon as you do the previous key will be retired.

Authentication

Example request for POST Authentication

curl -X POST \
  http://api.{environment}.validis.com/v1/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -F grant_type=vapi_key \
  -F key={your api key}

Example successful response for POST Authentication

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDExNjEyNjQsInVzZXJJZCI6NjI3LCJqdGkiOiIzMGYwOWZjYy1hYzNmLTQyZmQtYTRlNy0xNWVjODI2YTZiMjYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.4TgB6vsPcc4z2-IufQyA0RugvToirvQ6ZmTYFjwKVfE",
    "token_type": "bearer",
    "expires_in": 1799,
    "resellerId": "7cc0c2f5-8908-47e5-8a23-e27575d484c6",
    "clientId": "bfda4997-02d2-4b29-9db8-60b2e3d81bd0",
    "permissions": [
        "LF6UX4",
        "8F24PP",
        "9C2DOP",
        "3F9972",
        "BB3AB0",
        "45EB0A",
        "ZUQRX0",
        "FF7451",
        "1BE664"
    ],
    "userId": 627,
    "vconnectClientId": "bfda4997-02d2-4b29-9db8-60b2e3d81bd0",
    "jti": "30f09fcc-ac3f-42fd-a4e7-15ec826a6b26"
}

Once authenticated, each further request will then require 2 headers:

Authentication endpoint is used to obtain an access token, which is valid for 30 minutes. The access token is required on every call, and the client id (clientId) that is required on some endpoints.

Required Parameters

Parameter Type Constraint Description Location
content-Type String Required The content type expected. Value: application/x-www-form-urlencoded Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
key String Required API Key fetched from DataShare Admin Body
grant_type String Required Value: vapi_key Body

Optional Parameters

There are no optional parameters for this endpoint.

*The following elements are returned in the POST Authentication response

Field Format Description
access_token String JSON Web Token (JWT)
token_type String The JWT grant type
expires_in Integer Time in seconds until access token expires
clientId String (UUID) The unique identifier of the client
permissions Comma separated list An obfuscated list of permissions granted by the token. All granted permissions are already included in the JWT but this may be useful when investigating permission issues.
userId Integer The unique identifier of the user
vconnectClientId String (UUID) The unique identifier of the client
jti String JSON Web Token Id

Uploading Data

Overview

URL https://api.{environment}.validis.com/v1/clients/{clientId}/engagements
Methods Supported POST

An engagement is a customer of a client. You have to create an engagement in order to upload and the uploaded data is stored against the engagement. An engagement can have many uploads, but they will only be able to view the data of the last successful upload. You are able to enter an externalEngagementId (this wil be the unique identifier from another system) so they when you will be able to map the data to the entity in your system.

This section details how to find an engagement.

URL https://api.{environment}.validis.com/v1/clients/{clientId}/connectors
Methods Supported GET

DataShare API uses connectors to extract data from available accounting packages. This endpoint shows which accounting packages are available to the client.

Use the Connectors endpoint to obtain the available connectors for uploading data. The connector name (‘name’) would be required on the Upload call and if you want to give a full description of the connector to a customer then use the ‘title’ and the ‘description’ (the description is only applicable if there are mulitple versions of the connector for an accounting package). As the applicable connectors do not change that often, some people cache this response and check on for any updates on a daily basis.

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/connectors/{connectorName}/upload
Methods Supported POST

Create an engagement to be able to upload data for the customer. Use the ‘externalEngagementId’ to use the same unique identifier as you use in your system.

Creating a Engagement

Example request for POST Engagements

curl -X POST \
  https://api.sandbox.validis.com/v1/clients/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/engagements \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDExODM2MTAsInVzZXJJZCI6NjI3LCJqdGkiOiJlYmFhYTNhNC0xYzA1LTRiNDktOTdjMi1kZjE5NGI5NmYxOGYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.CuWq0ELz-hTktcSWhudiN8kcz_5xdtlkK_PguszMqGc' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \
  -d '{ 
  "sme": { 
    "name": "Example Customer 2"
  } 
,
"externalEngagementId": "Example2"
}'

Example successful response for POST Engagements

{
    "id": 4183,
    "externalEngagementId": "Example2",
    "clientId": "bfda4997-02d2-4b29-9db8-60b2e3d81bd0",
    "relationshipManager": null,
    "owner": {
        "id": 627,
        "firstName": "Api",
        "lastName": null,
        "email": "api@api.com",
        "phone": null,
        "title": null
    },
    "backupOwners": [],
    "agents": [],
    "connectorId": null,
    "connector": null,
    "status": 0,
    "tag": null,
    "sme": {
        "id": 4126,
        "name": "Example Customer 2",
        "contacts": [],
        "externalSmeId": "Example2",
        "type": "AUDIT",
        "locale": "en_GB"
    },
    "createdAt": 1541182238244,
    "createdBy": {
        "id": 627,
        "firstName": "Api",
        "lastName": null,
        "email": "api@api.com",
        "phone": null,
        "title": null
    },
    "reconciliationEnabled": false
}

Required Parameters

Parameter Type Constraint Description Location
clientId String UUID Required The unique identifier for the Client Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
sme_Name String Required The name of the Engagement for the request Body

Optional Parameters

Parameter Type Constraint Description Location
externalEngagementId String Optional External system client Identifier Body
usePortal Boolean Optional Default is false, when true an SME Contact is created with the provided First Name, Last Name, Email Address Header

The following elements are returned in the POST Engagements response

Field Format Description
Id Integer The unique identifier for the user/engagement
externalEngagementId String External system engagement Identifier
clientId String (UUID) The unique identifier of the client
firstName String The first name for the user
lastName String The last name for the user
email String The email for the user
phone String The phone number for the user
title String The title for the user/connector
connectorId Integer The unique ID for the connector used by the engagement
name String The name of the company/connector
status String The status of the Engagement
externalSmeId String External system SME Identifier (this currently only has one type – AUDIT)
type String Validis defined engagement type
locale String ISO code for the language used as a default for the engagement
createdAt Timestamp The date the engagement was created
reconciliationEnabled Booleon Indicator to show if they are able to use the reconciliation module

Reviewing Connectors

Example request for GET Connectors

curl -X GET \
  https://api.sandbox.validis.com/v1/clients/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/connectors \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDExNjEyNjQsInVzZXJJZCI6NjI3LCJqdGkiOiIzMGYwOWZjYy1hYzNmLTQyZmQtYTRlNy0xNWVjODI2YTZiMjYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.4TgB6vsPcc4z2-IufQyA0RugvToirvQ6ZmTYFjwKVfE' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Connectors

[
    {
        "id": 1,
        "name": "sage50",
        "description": null,
        "type": 1,
        "title": "Sage 50 UK"
    },
    {
        "id": 2,
        "name": "quickbooks",
        "description": null,
        "type": 1,
        "title": "QuickBooks Desktop"
    },
    {
        "id": 4,
        "name": "quickbooks-online",
        "description": null,
        "type": 0,
        "title": "QuickBooks Online"
    },
    {
        "id": 13,
        "name": "xero.partner",
        "description": "Partner",
        "type": 0,
        "title": "Xero"
    }
]

Required Parameters

Parameter Type Constraint Description Location
clientId String UUID Required The unique identifier for the Client Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Connectors response

Field Format Description
id Integer The Id of the connector
name String Code for the connector
description String Description of the connector version
type Integer 0 Online connector, 1 Offline connector
title String Name of the connector

Performing a Upload

Example request for POST Upload

curl -X POST \
  https://api.sandbox.validis.com/v1/engagements/660/connectors/sage50/upload \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDE5NTUsInVzZXJJZCI6NjI3LCJqdGkiOiIwZTA3ZTRiMC1jMDgzLTRlNDItYWNiZi0zOTdiZjllMGJkMzkiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.VqkmTjHMBPhXM8MgENwZPibKx-kVus2JgfZeiqH5_TY' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for POST Upload

{
    "action": "DOWNLOAD",
    "url": "http://vclient-provisioner-demo1-validis.azurewebsites.net/vclient/vclient.application?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCJCQUMxQjUiLCJCQjNBQkEiLCI1QTNBRDAiLCJGRjc0NTEiXSwicm9sZXMiOlsiOUVERERFIl0sImV4cCI6MTU4ODA1NjIzOCwidXNlcklkIjo2MjcsImVuZ2FnZW1lbnRJZCI6NjYwLCJqdGkiOiI1ZWQwN2ZkNy1iMTAyLTQxMGEtYjc0Ny05Y2FiOTg4OTAwZjciLCJjbGllbnRfaWQiOiJ2Y2xpZW50IiwidXNlcm5hbWUiOiJjb20udmFsaWRpcy52YXV0aC5zZWN1cml0eS5WQXBpQXV0aFVzZXJAM2FjNmEyMzYiLCJ2Y29ubmVjdENsaWVudElkIjoiYmZkYTQ5OTctMDJkMi00YjI5LTlkYjgtNjBiMmUzZDgxYmQwIn0.et5zz9xwLvztJYyMRV214eS6imzIVMaqvfKtlTWeWzo&client=bfda4997-02d2-4b29-9db8-60b2e3d81bd0&company=616&connector=sage50"
}

You will need to have an engagement and know the accounting package before you can start an upload. You will be able to create an engagement as you should have the details for the engagement in your system. You will have to show a list of applicable packages to your customer (using the connectors endpoint). Once the customer has authenticated, the progress of the upload can be tracked in the Get Uploads endpoint or you can receive updates using the DataShare Webhook which is configured in DataShare Admin.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Client Path
connectorName String Required Accounting Package identifier Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the POST Upload response

Field Format Description
type String One of two options will be shown: DOWNLOAD – This is for offline connectors and will show a URL that will download the vClient connector. REDIRECT – This is for online connectors that require authentication and will also provide a URL to be redirected to authenticate the accounting package.
datashareClientUrl String When the type is DOWNLOAD, this will be populated with the URL for the DataShare Connect application that will upload the data to Validis.
redirectUrl String When the type is REDIRECT, this will be populated with the URL that customer will need to authenticate the sharing of data with DataShare.

Client Details

Overview

URL https://api.{environment}.validis.com/v1/clients/{clientId}/engagements
Methods Supported GET

Search for an engagement. If you use the ‘externalEngagementId’ when creating a engagement and you will be able to use your unique identifier to obtain the ‘engagementId’ for the corresponding customer in DataShare. The ‘engagementId’ is used for retrieving data about the customer.

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/companyDetails
Methods Supported GET

The company details gives you details of the company uploading that is stored in the accounting package. The base currency that is set for the package is shown once in the company details.

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/periods/
Methods Supported GET

This endpoint gives data for the company uploading that is applicable to multiple elements across the upload. The details shown in the endpoints are correct for the latest upload.

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/connectors/{connectorName}/uploads
Methods Supported GET

This endpoint allows you to add data to an existing Engagement and track the progress of the upload. If you have an online connector, it will provide you a link to the cloud package’s authentication page, once authenticated, it will download the required data to populate DataShare. If you have an offline (desktop) package, it will download the vClient connector which when opened will ask for the credentials for the package and any relevant information required to process the data (e.g. Chart of Accounts) and then it will extract the required data to populate DataShare.

Reviewing Engagements

Example request for GET Engagements

curl -X GET \
  https://api.sandbox.validis.com/v1/clients/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/engagements \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDExODM2MTAsInVzZXJJZCI6NjI3LCJqdGkiOiJlYmFhYTNhNC0xYzA1LTRiNDktOTdjMi1kZjE5NGI5NmYxOGYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.CuWq0ELz-hTktcSWhudiN8kcz_5xdtlkK_PguszMqGc' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Engagements

{
    "content": [
        {
            "id": 696,
            "externalEngagementId": "Example1",
            "clientId": "bfda4997-02d2-4b29-9db8-60b2e3d81bd0",
            "relationshipManager": null,
            "owner": {
                "id": 627,
                "firstName": "Api",
                "lastName": null,
                "email": "api@api.com",
                "phone": null,
                "title": null
            },
            "backupOwners": [],
            "agents": [],
            "connectorId": null,
            "connector": null,
            "status": 0,
            "tag": null,
            "sme": {
                "id": 648,
                "name": "Example Customer",
                "contacts": [],
                "externalSmeId": null,
                "type": "AUDIT",
                "locale": "en_GB"
            },
            "createdAt": 1528197801090,
            "createdBy": {
                "id": 627,
                "firstName": "Api",
                "lastName": null,
                "email": "api@api.com",
                "phone": null,
                "title": null
            },
            "reconciliationEnabled": false
        }
    ],
    "last": false,
    "totalPages": 55,
    "totalElements": 55,
    "sort": null,
    "numberOfElements": 1,
    "first": true,
    "size": 1,
    "number": 0
}

Required Parameters

Parameter Type Constraint Description Location
clientId String UUID Required The unique identifier for the Client Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
externalEngagementId String Optional Comma separated list of externalEngagementIds query string parameter
page Integer Optional Starting page (page numbering starts at 0) query string parameter
size Integer Optional Size of each page query string parameter
orderBy String Optional Comma separated list of fields to sort by. Use -{field name} to sort in descending order query string parameter

The following elements are returned in the GET Engagements response

Field Format Description
Id Integer The unique identifier for the user/engagement
externalEngagementId String External system engagement Identifier
clientId String (UUID) The unique identifier of the client
relationshipManager String The relationship manager assign to the client
Owner.firstName String The first name for the engagement owner
Owner.lastName String The last name for the engagement owner
Owner.email String The email for the engagement owner
Owner.phone String The phone number for the engagement owner
Owner.title String The title for the engagement owner
connectorId Integer The unique ID for the connector used by the engagement
name String The name of the company/connector
status String The status of the Engagement
Sme.name String Name of client contact setup on system
type String Validis defined engagement type
locale String ISO code for the language used as a default for the engagement
createdAt Timestamp The date the engagement was created
reconciliationEnabled Booleon Indicator to show if they are able to use the reconciliation module
last Boolean TRUE if the current page is the last page. FALSE if the current page is not the last page.
totalPages Integer Total number of pages available for the page size selected.
totalElements Integer Number of elements in the current page.
sort String Sorting direction - DESC for descending and ASC for ascending.
numberOfElements Integer The element (upload) number for the sorting criteria.
first Boolean TRUE if the current page is the first page. FALSE if the current page is not the first page.
size Integer The number of elements per page.
number Integer The number of the page (first page is 0)

Retrieve Company Details

GET Company Details (Beta)

Example request for GET Company Details

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/companyDetails \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzc2MzYsInVzZXJJZCI6NjI3LCJqdGkiOiIxMzg5OGNiMi0zMmI0LTQzYzItOGZmMy1mYjU5ZDJmMDJmZDciLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.50vGryBQSZbuRgcD2HpZae3eirTDBTzAJiVuuQWhaJI' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Company Details

{
    "name": "Clothing Retailers",
    "registrationNumber": null,
    "salesTaxNumber": "999999999",
    "payrollTaxNumber": null,
    "address1": null,
    "address2": null,
    "address3": null,
    "townCity": null,
    "stateCounty": null,
    "postZipCode": null,
    "countryCode": null,
    "countryName": null,
    "telephone1": null,
    "fax1": null,
    "email1": null,
    "url": null,
    "currencyIso": "GBP"
}

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this API

The following elements are returned in the GET Company Details response

Field Format Description
name String Company name
registrationNumber String Registration number as exported from the accounting package
salesTaxNumber String Sales tax number as exported from the accounting package
payrollTaxNumber String Payroll tax number as exported from the accounting package
address1 String Address first line as exported from the accounting package
address2 String Address second line as exported from the accounting package
address3 String Address third line as exported from the accounting package
townCity String Town as exported from the accounting package
stateCounty String State/County as exported from the accounting package
postZipcode String Postcode/Zip code as exported from the accounting package
countryCode String Country ISO code (3 chars)
countryName String Country name as exported from the accounting package
telephone1 String Telephone number as exported from the accounting package
fax1 String Fax number as exported from the accounting package
email1 String Email address as exported from the accounting package
currencyIso String Currency ISO code (3 chars) for Base currency

GET Periods

Example request for GET Periods

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/periods \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDQxNzEsInVzZXJJZCI6NjI3LCJqdGkiOiI2MzUyMGQyYS1mN2QyLTRmODUtOTg5Yi0xZTA0MzBkOWU4YmEiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.DdAYD4c57vcFFwx4s9sydhVIhZquORyb9uDNNXdG8Sg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Periods

[
    {
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
        "yearId": 2018,
        "name": "FY-2018",
        "periods": [
            {
                "startDate": "2018-01-01",
                "endDate": "2018-01-31",
                "periodId": 201801,
                "name": "FP-1",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-02-01",
                "endDate": "2018-02-28",
                "periodId": 201802,
                "name": "FP-2",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-03-01",
                "endDate": "2018-03-31",
                "periodId": 201803,
                "name": "FP-3",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-04-01",
                "endDate": "2018-04-30",
                "periodId": 201804,
                "name": "FP-4",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-05-01",
                "endDate": "2018-05-31",
                "periodId": 201805,
                "name": "FP-5",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-06-01",
                "endDate": "2018-06-30",
                "periodId": 201806,
                "name": "FP-6",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-07-01",
                "endDate": "2018-07-31",
                "periodId": 201807,
                "name": "FP-7",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-08-01",
                "endDate": "2018-08-31",
                "periodId": 201808,
                "name": "FP-8",
                "type": "PERIOD"
            },
            {
                "startDate": "2018-09-01",
                "endDate": "2018-09-30",
                "periodId": 201809,
                "name": "FP-9",
                "type": "PERIOD"
            }
        ]
    }
]

The financial periods are the financial periods as set in the accounting package if they are available. If they are not available, DataShare will create monthly periods. These periods may be used in returning information for reports etc. The periodIds may not be consistent between uploads, so you will need to check the periodIds for each upload. PLEASE NOTE: although there is a pattern in the periodIds in the example, this is not consistent in all accounting packages.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Periods response

Field Format Description
uploadId String (UUID) The Id of the upload
yearId String The Id of the financial year the upload
periodId String The Id of the financial period for the upload
name String The name of the year/period as defined in Validis
startDate Date The start date of the financial year/period
endDate Date The end date of the financial year/period
periodNo Integer The numeric financial period within the financial year

Reviewing Uploads

Example request for GET Uploads

curl -X GET \
  https://api.sandbox.validis.com/v1/clients/{clientId}/uploads \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDQxNzEsInVzZXJJZCI6NjI3LCJqdGkiOiI2MzUyMGQyYS1mN2QyLTRmODUtOTg5Yi0xZTA0MzBkOWU4YmEiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.DdAYD4c57vcFFwx4s9sydhVIhZquORyb9uDNNXdG8Sg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Uploads

{
    "content": [
        {
            "uploadId": "013f8c93-75cb-4e37-a977-28b488c4e8cd",
            "status": "COMPLETED",
            "resellerId": "7cc0c2f5-8908-47e5-8a23-e27575d484c6",
            "clientId": "bfda4997-02d2-4b29-9db8-60b2e3d81bd0",
            "smeId": 616,
            "smeName": "Validis-Sandbox",
            "engagementId": 660,
            "contactId": 627,
            "creationDate": "2018-10-24T11:14:08.737+0000",
            "completionDate": "2018-10-24T11:18:02.757+0000",
            "connectorName": "sage50",
            "connectorVersion": "21.00.03.0296",
            "externalEngagementId": null,
            "active": false,
            "uploadType": "MANUAL"
        }
    ],
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "sort": [
        {
            "direction": "DESC",
            "property": "completionDate",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "descending": true,
            "ascending": false
        }
    ],
    "numberOfElements": 1,
    "first": true,
    "size": 20,
    "number": 0
}

You will need to have an engagement and know the accounting package before you can start an upload. You will be able to create an engagement as you should have the details for the engagement in your system. You will have to show a list of applicable packages to your customer (using the connectors endpoint). Once the customer has authenticated, the progress of the upload can be tracked in the Get Uploads endpoint or you can receive updates using the DataShare Webhook which is configured in DataShare Admin.

Required Parameters

Parameter Type Constraint Description Location
clientId String UUID Required The unique identifier for the Client Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
engagementId Integer Optional To filter the uploads for a Validis defined Engagement id (long) (Comma separated list of ids) query string parameter
uploadId String (UUID) Optional To filter the details of a single upload using the Id of the upload query string parameter
createdDateFrom String Optional To filter of all uploads that were created after the specified time (format is yyyy-mm-ddThh:mm:ss) query string parameter
createdDateTo String Optional To filter of all uploads that were created after the specified time (format is yyyy-mm-ddThh:mm:ss) query string parameter
completedDateFrom String Optional To filter of all uploads that were completed after the specified time (format is yyyy-mm-ddThh:mm:ss) query string parameter
completedDateTo String Optional To filter of all uploads that were completed after the specified time (format is yyyy-mm-ddThh:mm:ss) query string parameter
page Integer Optional Starting page (page numbering starts at 0) query string parameter
size Integer Optional Size of each page query string parameter
orderBy String Optional Comma separated list of fields to sort by. Use -{field name} to sort in descending order. query string parameter

The following elements are returned in the GET Uploads response

Field Format Description
uploadId String (UUID) The Id of the upload
uploadStatus String The status of the upload
clientId String (UUID) The unique identifier of the client
engagementId Integer The Id of the Engagement that defines the upload
contactId String The Id of the contact representing the Engagement who performed the upload
creationDate String The time the upload was started
completionDate String The time the upload was completed
connectorName String The name of the accounting package the upload was extracted from
connectorVersion String The version of the accounting package the upload was extracted from
active Boolean True if the Engagement is enabled. False if they are disabled.
uploadType String The type of the upload
externalEngagementId String The External Engagement Id
engagementName String The name of the Engagement
smeId Integer The Id of the SME that has completed the upload
smeName String The name of the SME that has completed the upload
last Boolean True if the current page is the last page. False if the current page is not the last page.
totalElements Integer Total number of elements (uploads) available for the client.
totalPages Integer Total number of pages available for the page size selected.
first Boolean True if the current page is the first page. False if the current page is not the first page.
direction String Sorting direction - DESC for descending and ASC for ascending.
property String The field in the results that is used to sort
ignoreCase Boolean True if the response sorts taking case into account. False if the response doesn’t sort taking case into account.
nullHandling String Defined null handler.
ascending Boolean True if the response is in ascending order. False if the response is not in ascending order.
descending Boolean True if the response is in descending order. False if the response is not in descending order.
numberOfElements Integer Number of elements in the current page.
size Integer The number of elements per page.
number Integer The element (upload) number for the sorting criteria.

Get Last Upload

Example request for GET Last Upload

curl -X GET \
  https://api.sandbox.validis.com/v1/clients/{clientId}/lastUploads?engagementIds={engagementId(s)} \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDQxNzEsInVzZXJJZCI6NjI3LCJqdGkiOiI2MzUyMGQyYS1mN2QyLTRmODUtOTg5Yi0xZTA0MzBkOWU4YmEiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.DdAYD4c57vcFFwx4s9sydhVIhZquORyb9uDNNXdG8Sg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Last Uploads

    {
        "uploadId": "6a3a9a23-7b28-4bfb-85da-2f9663c8cec8",
        "status": "COMPLETED",
        "resellerId": "7cc0c2f5-8908-47e5-8a23-e27575d484c6",
        "clientId": "158f6c61-c7ba-43d9-9f46-af21d0519b39",
        "smeId": 7437,
        "smeName": null,
        "engagementId": 7482,
        "contactId": 2998,
        "creationDate": "2019-06-24T10:38:06.067+0000",
        "completionDate": "2019-06-24T10:42:51.650+0000",
        "connectorName": "sage50",
        "connectorVersion": "25.0.66.0",
        "externalEngagementId": null,
        "active": false,
        "uploadType": "MANUAL",
        "withMemo": false,
        "memo": null,
        "content": null
    }

Required Parameters

Parameter Type Constraint Description Location
clientId String UUID Required The unique identifier for the Client Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
engagementIds Integer Required To filter the uploads for a Validis defined Engagement id (long) (Comma separated list of ids) query string parameter

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Starting page (page numbering starts at 0) query string parameter
size Integer Optional Size of each page query string parameter

The following elements are returned in the GET Last Upload response

Field Format Description
uploadId String (UUID) The Id of the upload
status String The status of the upload
resellerId String (UUID) The unique identifier of the resller
clientId String (UUID) The unique identifier of the client
smeId Integer The Id of the SME that has completed the upload
smeName String The name of the SME that has completed the upload
engagementId Integer The Id of the Engagement that defines the upload
contactId String The Id of the contact representing the Engagement who performed the upload
creationDate String The time the upload was started
completionDate String The time the upload was completed
connectorName String The name of the accounting package the upload was extracted from
connectorVersion String The version of the accounting package the upload was extracted from
active Boolean True if the Engagement is enabled. False if they are disabled.
uploadType String The type of the upload
withMemo Boolean Default response is false
memo String Default response is null
content String Default response is null

Financial Information (JSON)

Overview

URL https://api.{environment}.validis.com/v1/reports/income-statement-standard/engagements/{engagementId}?year=current
Methods Supported GET
URL https://api.{environment}.validis.com/v1/reports/balance-sheet-standard/engagements/{engagementId}?year=current
Methods Supported GET
URL https://api.{environment}.validis.com/v1/reports/cashflow-statement/engagements/{engagementId}?year=current
Methods Supported GET
URL https://api.{environment}.validis.com/v1/reports/trial-balance/engagements/{engagementId}?year=current
Methods Supported GET
URL https://api.{environment}.validis.com/v1/reports/financial-snapshot/engagements/{engagementId}?year=current
Methods Supported GET
URL https://api.{environment}.validis.com/v1/reports/quality-score/engagements/{engagementId}?year=current
Methods Supported GET

These endpoints give standardised reports as shown in DataShare View. You select them either by using a one of the specified financial years or selecting the specific periods you require the reports for.

AcceptUnassigned

This optional parameter will return the results of the report if there are unassigned accounts therefore the details in the report could be incorrect (Default if not present will be True). If there are unassigned accounts and this parameter is False, then an error message will be returned. If there are unassigned accounts and this parameter is True, then the report details will be shown in their current state. Unassigned accounts are accounts from the accounting package that currently have not been mapped to the Validis chart of accounts. There is a section in DataShare View for the Client to assign accounts. query string parameter

Income Statement

Example request for GET Income Statement

curl -X GET \
  https://api.sandbox.validis.com/v1/reports/income-statement-standard/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDcwNzQsInVzZXJJZCI6NjI3LCJqdGkiOiIxNWM0NzU4Yi02OGQ3LTRlODAtOGMxMi1lNGNmOTJkMDAzMWYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.Jo4kAt42gi5WUBDdgjAv2pJzHpsIXEr24lc7bJJ6tjo' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Income Statement

{
    "ranges": [
        {
            "startPeriod": {
                "startDate": "2018-01-01",
                "endDate": "2018-01-31",
                "periodId": 201801,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": "2018-11-01",
                "endDate": "2018-11-30",
                "periodId": 201811,
                "name": "FP-11"
            },
            "type": "YEAR",
            "yearId": 2018,
            "name": "FY-2018"
        }
    ],
    "elements": [
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.retained_profit",
                "value": "Retained profit/(Loss)"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": -277011.92,
                    "displayFlipped": true
                }
            ],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.profit_loss_after_tax",
                        "value": "Profit/(Loss) after tax"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -377011.92,
                            "displayFlipped": true
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.profit_loss_before_tax",
                                "value": "Profit/(Loss) before tax"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -377011.92,
                                    "displayFlipped": true
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.operating_profit",
                                        "value": "Operating Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -384189.06,
                                            "displayFlipped": true
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.gross_profit",
                                                "value": "Gross Profit/(Loss)"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -1135276.33,
                                                    "displayFlipped": true
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.sales",
                                                        "value": "Revenue"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": -3927314.19,
                                                            "displayFlipped": true
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.cost_of_sales",
                                                        "value": "Cost of Goods Sold"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 2792037.86,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ],
                                            "displayType": "TITLE_AFTER"
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.operating_costs",
                                                "value": "Operating Expenses"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 751087.27,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.bad_debts",
                                                        "value": "Bad Debts"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.depreciation_and_amortization",
                                                        "value": "Depreciation & Amortization"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 4000,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.directors_costs",
                                                        "value": "Directors costs"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.disposals",
                                                        "value": "Disposals"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.staff_costs",
                                                        "value": "Payroll Costs"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 588347.75,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.exchange_differences",
                                                        "value": "Exchange differences"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.professional_fees",
                                                        "value": "Professional fees"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 5013.98,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.repairs_and_maintenance",
                                                        "value": "Repairs and Maintenance"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.rent_and_utilities",
                                                        "value": "Rent and Utilities"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 105947.32,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.research_and_development",
                                                        "value": "Research & Development"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.sales_and_marketing",
                                                        "value": "Sales & Marketing"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 26765.3,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.telecommunications",
                                                        "value": "Telecommunications"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 6202.61,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.other_operating_costs",
                                                        "value": "Other Operating Expenses"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 14810.31,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.investment_income",
                                        "value": "Investment Income"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.non_operating_income",
                                        "value": "Other Income/(Expenses)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.financial_charges",
                                        "value": "Interest Expense"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 7177.14,
                                            "displayFlipped": true
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.pnl_corporation_tax",
                                "value": "Income tax expense"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 0,
                                    "displayFlipped": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.dividends",
                        "value": "Dividends"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 100000,
                            "displayFlipped": true
                        }
                    ]
                }
            ]
        }
    ],
    "currency": {
        "id": 826,
        "iso3": "GBP",
        "decimals": 2,
        "name": "Pound Sterling",
        "symbol": null
    }
}

The Income Statement is based on the customer’s data using the Validis Chart of Accounts (CoA). Please note that this report will change if the CoA is amended in DataShare View and this report may be wrong if there are unassigned accounts in the CoA. You will be notified will an error message if there unassigned accounts and you will be able to override this to get a response with the details as they are by using the acceptUnassigned optional parameter.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

Parameter Type Constraint Description Location
acceptUnassigned Boolean Optional See acceptUnassigned query string parameter

The following elements are returned in the GET Income Statement response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

Balance Sheet

Example request for GET Balance Sheet

curl -X GET \
  https://api.sandbox.validis.com/v1/reports/balance-sheet-standard/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDcwNzQsInVzZXJJZCI6NjI3LCJqdGkiOiIxNWM0NzU4Yi02OGQ3LTRlODAtOGMxMi1lNGNmOTJkMDAzMWYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.Jo4kAt42gi5WUBDdgjAv2pJzHpsIXEr24lc7bJJ6tjo' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Balance Sheet

{
    "ranges": [
        {
            "startPeriod": {
                "startDate": "2018-01-01",
                "endDate": "2018-01-31",
                "periodId": 201801,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": "2018-11-01",
                "endDate": "2018-11-30",
                "periodId": 201811,
                "name": "FP-11"
            },
            "type": "YEAR",
            "yearId": 2018,
            "name": "FY-2018"
        }
    ],
    "elements": [
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.assets",
                "value": "Total Assets"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": 2936060.69,
                    "displayFlipped": false
                }
            ],
            "decorations": {
                "VARIANCE": [],
                "VARIANCEPERCENTAGE": []
            },
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.current_assets",
                        "value": "Current Assets"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 2295905.21,
                            "displayFlipped": false
                        }
                    ],
                    "decorations": {
                        "VARIANCE": [],
                        "VARIANCEPERCENTAGE": []
                    },
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.cash_short_term_investments",
                                "value": "Cash and Short Term Investments"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 139676.05,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.accounts_receivable",
                                "value": "Trade and Other Receivables"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1859139.85,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.inventory",
                                "value": "Inventory"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 263092.84,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.prepayments",
                                "value": "Prepaid Expenses"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1103,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.other_current_assets",
                                "value": "Other Current Assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 32893.47,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        }
                    ]
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.fixed_assets",
                        "value": "Non-Current Assets"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 640155.48,
                            "displayFlipped": false
                        }
                    ],
                    "decorations": {
                        "VARIANCE": [],
                        "VARIANCEPERCENTAGE": []
                    },
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.ppe",
                                "value": "Property, Plant and Equipment"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 231169.36,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.goodwill",
                                "value": "Goodwill"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2000,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.intangible_assets",
                                "value": "Intangible Assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 4000,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.long_term_investments",
                                "value": "Long Term Investments"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 390286.12,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.other_fixed_assets",
                                "value": "Other Non-Current Assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 12700,
                                    "displayFlipped": false
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        }
                    ]
                }
            ]
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.liabilities_and_equity",
                "value": "Total Liabilities and Equity"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": -2936060.69,
                    "displayFlipped": true
                }
            ],
            "decorations": {
                "VARIANCE": [],
                "VARIANCEPERCENTAGE": []
            },
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.current_liabilities",
                        "value": "Current Liabilities"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -1757073.82,
                            "displayFlipped": true
                        }
                    ],
                    "decorations": {
                        "VARIANCE": [],
                        "VARIANCEPERCENTAGE": []
                    },
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.short_term_borrowings",
                                "value": "Short Term Borrowings"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -641085.7,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.bs_bank_loans",
                                "value": "Current Portion of Long Term Debt"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -12600,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.capital_leases",
                                "value": "Obligations Under Capital Leases"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -5200,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.creditors",
                                "value": "Trade and Other Payables"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -720322.56,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.accruals",
                                "value": "Accrued Expenses"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -4952.35,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.other_current_liabilities",
                                "value": "Other Current Liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -372913.21,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        }
                    ]
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.long_term_liabilities",
                        "value": "Non-Current Liabilities"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -94800,
                            "displayFlipped": true
                        }
                    ],
                    "decorations": {
                        "VARIANCE": [],
                        "VARIANCEPERCENTAGE": []
                    },
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.bank_loans_long_term",
                                "value": "Long Term Debt"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -75400,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.capital_leases",
                                "value": "Obligations Under Capital Leases"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -8600,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.other_long_term_liabilities",
                                "value": "Other Non-Current Liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -10800,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        }
                    ]
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.shareholders_equity",
                        "value": "Shareholders Equity"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -1084186.87,
                            "displayFlipped": true
                        }
                    ],
                    "decorations": {
                        "VARIANCE": [],
                        "VARIANCEPERCENTAGE": []
                    },
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.share_capital",
                                "value": "Common Stock"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -10000,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.preferred_stock",
                                "value": "Preferred Stock"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -28000,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.profit_and_loss",
                                "value": "Profit/(Loss) YTD"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -1006186.87,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.other_equity",
                                "value": "Other Equity"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -40000,
                                    "displayFlipped": true
                                }
                            ],
                            "decorations": {
                                "VARIANCE": [],
                                "VARIANCEPERCENTAGE": []
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "currency": {
        "id": 826,
        "iso3": "GBP",
        "decimals": 2,
        "name": "Pound Sterling",
        "symbol": null
    }
}

The Balance Sheet is based on the customer’s data using the Validis Chart of Accounts (CoA). Please note that this report will change if the CoA is amended in DataShare View and this report may be wrong if there are unassigned accounts in the CoA. You will be notified will an error message if there unassigned accounts and you will be able to override this to get a response with the details as they are by using the acceptUnassigned optional parameter.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

Parameter Type Constraint Description Location
acceptUnassigned Boolean Optional See acceptUnassigned query string parameter

The following elements are returned in the GET Balance Sheet response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

Cashflow Statement

Example request for GET Cashflow Statement

curl -X GET \
  https://api.sandbox.validis.com/v1/reports/cashflow-statement/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDcwNzQsInVzZXJJZCI6NjI3LCJqdGkiOiIxNWM0NzU4Yi02OGQ3LTRlODAtOGMxMi1lNGNmOTJkMDAzMWYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.Jo4kAt42gi5WUBDdgjAv2pJzHpsIXEr24lc7bJJ6tjo' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Cashflow Statement

{
    "ranges": [
        {
            "startPeriod": {
                "startDate": "2018-01-01",
                "endDate": "2018-01-31",
                "periodId": 201801,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": "2018-11-01",
                "endDate": "2018-11-30",
                "periodId": 201811,
                "name": "FP-11"
            },
            "type": "YEAR",
            "yearId": 2018,
            "name": "FY-2018"
        }
    ],
    "elements": [
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.other_movements",
                "value": "Other movements"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": 0,
                    "displayFlipped": true
                }
            ],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.change_in_cash",
                        "value": "Change in Cash"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -224151.4,
                            "displayFlipped": true
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.net_cashflow_from_operations",
                                "value": "Net cash flows from operating activities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -282950.07,
                                    "displayFlipped": true
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.cashflow_from_operations",
                                        "value": "Cash flows from operating activities"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -282950.07,
                                            "displayFlipped": true
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.operating_profit_before_working_capital",
                                                "value": "Operating profit before w/capital changes"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -381011.92,
                                                    "displayFlipped": true
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.profit_loss_before_tax",
                                                        "value": "Profit/(Loss) before tax"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": -377011.92,
                                                            "displayFlipped": true
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.depreciation",
                                                        "value": "Depreciation"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 4000,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.amortisation",
                                                        "value": "Amortization charges"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.impairment",
                                                        "value": "Impairment charges"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 0,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.inventories_movement",
                                                "value": "Movement in inventories"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -14388,
                                                    "displayFlipped": true
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.receivables_movement",
                                                "value": "Movement in trade and other receivables"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 161542.76,
                                                    "displayFlipped": true
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.payables_movement",
                                                "value": "Movement in trade and other payables"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -49092.91,
                                                    "displayFlipped": true
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.corporate_tax_movement",
                                        "value": "Income taxes (paid)/refunded"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.net_cashflows_from_investments",
                                "value": "Cash flows from investing activities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 10073.67,
                                    "displayFlipped": true
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.tangible_asset_movement",
                                        "value": "Movement in property, plant and equipment"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 10073.67,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.goodwill_movement",
                                        "value": "Movement in goodwill and other intangibles"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.investments_movement",
                                        "value": "Movements in investments and other assets"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.net_cashflows_from_financing",
                                "value": "Cash flows from financing activities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 48725,
                                    "displayFlipped": true
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.movement_capital",
                                        "value": "Movement in capital"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.other_equity_movement",
                                        "value": "Movement in other equity"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.dividends_movement",
                                        "value": "Dividends paid"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 100000,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.borrowings_movement",
                                        "value": "Movement in borrowings"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -51275,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.capital_obligations_movement",
                                        "value": "Movement in capital obligations"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.other_financings_movement",
                                        "value": "Movement in other loans"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 0,
                                            "displayFlipped": true
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "SHOW_CHILDREN_ONLY"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.cash_or_equivalents_movements",
                        "value": "Movement in cash and cash equivalents"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 224151.4,
                            "displayFlipped": false
                        }
                    ]
                }
            ]
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.opening_cash",
                "value": "Opening cash and cash equivalents"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": -728561.05,
                    "displayFlipped": false
                }
            ]
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.closing_cash",
                "value": "Closing cash and cash equivalents"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": -504409.65,
                    "displayFlipped": false
                }
            ]
        }
    ],
    "currency": {
        "id": 826,
        "iso3": "GBP",
        "decimals": 2,
        "name": "Pound Sterling",
        "symbol": null
    }
}

The Cashflow Statement is based on the customer’s data using the Validis Chart of Accounts (CoA). Please note that this report will change if the CoA is amended in DataShare View and this report may be wrong if there are unassigned accounts in the CoA. You will be notified will an error message if there unassigned accounts and you will be able to override this to get a response with the details as they are by using the acceptUnassigned optional parameter.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

Parameter Type Constraint Description Location
acceptUnassigned Boolean Optional See acceptUnassigned query string parameter

The following elements are returned in the GET Cashflow Statement response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

Trial Balance

Example request for GET Trial Balance

curl -X GET \
  'https://api.sandbox.validis.com/v1/reports/trial-balance/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDgwNjIyMzIsInVzZXJJZCI6NjI3LCJqdGkiOiI3MmE1Mzk4Mi0yNTEyLTQ4NDgtODMwMy1lMjg5ZTU5ODRlNzIiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTMzMzhlYmJkMzEwNzRhZWFiZjI4MWZjYWMzYjQ0ZmQxLCBjcmVhdGVkQXQ9MjAxOC0xMi0xMSAxMDowNDowNS4zODcsIGNyZWF0ZWRCeT05MDksIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.cuvMDoCBWkkYCiR5tEphqBHq2SkaNEAbhzRrP3G2Nlg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Trial Balance

{
    "ranges": [
        {
            "startPeriod": {
                "startDate": "2017-01-01",
                "endDate": "2017-01-31",
                "periodId": 201701,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": "2017-12-01",
                "endDate": "2017-12-31",
                "periodId": 201712,
                "name": "FP-12"
            },
            "type": "YEAR",
            "yearId": 2017,
            "name": "FY-2017"
        }
    ],
    "elements": [
        {
            "title": {
                "type": "LABEL",
                "key": "Total",
                "value": "total"
            },
            "values": [
                {
                    "type": "DECIMAL_AMOUNT",
                    "value": 0,
                    "displayFlipped": false
                }
            ],
            "decorations": {
                "CREDIT": [
                    {
                        "type": "DECIMAL_AMOUNT",
                        "value": 7888684.03,
                        "displayFlipped": false
                    }
                ],
                "DEBIT": [
                    {
                        "type": "DECIMAL_AMOUNT",
                        "value": 7888684.03,
                        "displayFlipped": false
                    }
                ]
            },
            "children": [
                {
                    "title": {
                        "type": "ACCOUNT",
                        "accountId": 89,
                        "code": "0010",
                        "name": "Freehold Property",
                        "tag": "LAND_AND_BUILDING_COST",
                        "primaryCategory": "FIXED_ASSETS"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 180000,
                            "displayFlipped": false
                        }
                    ],
                    "decorations": {
                        "CREDIT": [
                            {
                                "type": "VOID",
                                "displayFlipped": false
                            }
                        ],
                        "DEBIT": [
                            {
                                "type": "DECIMAL_AMOUNT",
                                "value": 180000,
                                "displayFlipped": false
                            }
                        ]
                    }
                },
                {
                    "title": {
                        "type": "ACCOUNT",
                        "accountId": 91,
                        "code": "0012",
                        "name": "Premium on New Shops",
                        "tag": "OTHER_INTANGIBLE_ASSETS_COST",
                        "primaryCategory": "FIXED_ASSETS"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 72000,
                            "displayFlipped": false
                        }
                    ],
                    "decorations": {
                        "CREDIT": [
                            {
                                "type": "VOID",
                                "displayFlipped": false
                            }
                        ],
                        "DEBIT": [
                            {
                                "type": "DECIMAL_AMOUNT",
                                "value": 72000,
                                "displayFlipped": false
                            }
                        ]
                    }
                }
            ]
        }
    ],
    "currency": {
        "id": 826,
        "iso3": "GBP",
        "decimals": 2,
        "name": "Pound Sterling",
        "symbol": null
    }
}

The Trial Balance is based on the customer’s data showing the balances of credit and debits within the period ranges selected.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Trial Balance response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

Financial Snapshot

Example request for GET Financial Snapshot

curl -X GET \
  'https://api.sandbox.validis.com/v1/reports/financial-snapshot/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDgwNjIyMzIsInVzZXJJZCI6NjI3LCJqdGkiOiI3MmE1Mzk4Mi0yNTEyLTQ4NDgtODMwMy1lMjg5ZTU5ODRlNzIiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTMzMzhlYmJkMzEwNzRhZWFiZjI4MWZjYWMzYjQ0ZmQxLCBjcmVhdGVkQXQ9MjAxOC0xMi0xMSAxMDowNDowNS4zODcsIGNyZWF0ZWRCeT05MDksIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.cuvMDoCBWkkYCiR5tEphqBHq2SkaNEAbhzRrP3G2Nlg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Financial Snapshot

{
    "ranges": [
        {
            "startPeriod": {
                "startDate": "2017-01-01",
                "endDate": "2017-01-31",
                "periodId": 201701,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": "2017-12-01",
                "endDate": "2017-12-31",
                "periodId": 201712,
                "name": "FP-12"
            },
            "type": "YEAR",
            "yearId": 2017,
            "name": "FY-2017"
        }
    ],
    "elements": [
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.income_statement",
                "value": "Income Statement"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.revenue",
                        "value": "Revenue"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 4849758.77,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.gross_profit_loss",
                        "value": "Gross Profit/(Loss)"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 1436158.68,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.ebitda",
                        "value": "EBITDA"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 489616.84,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.OPERATING_PROFIT",
                                "value": "Operating Profit/(Loss)"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -481616.84,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.GROSS_PROFIT",
                                        "value": "Gross Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -1436158.68,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_COSTS",
                                        "value": "Operating Expenses"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 954541.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 1293636.12,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 339094.28,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.null",
                                "value": ""
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 8000,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.depreciation",
                        "value": "Depreciation"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -8000,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.operating_profit",
                        "value": "Operating Profit/(Loss)"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 481616.84,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.GROSS_PROFIT",
                                "value": "Gross Profit/(Loss)"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -1436158.68,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.OPERATING_COSTS",
                                "value": "Operating Expenses"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 954541.84,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 1293636.12,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 339094.28,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.financial_charges_other_income",
                        "value": "Finance charges/Other Income"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -161144.28,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.income_loss_before_taxation",
                        "value": "Income/(Loss) Before Taxation"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 320472.56,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.OPERATING_PROFIT",
                                "value": "Operating Profit/(Loss)"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -481616.84,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.GROSS_PROFIT",
                                        "value": "Gross Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -1436158.68,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_COSTS",
                                        "value": "Operating Expenses"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 954541.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 1293636.12,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 339094.28,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.INTEREST_RECEIVABLE_BANK_CHARGES_AND_INTEREST_OTHER_INCOME",
                                "value": "report.title.interest_receivable_bank_charges_and_interest_other_income"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 161144.28,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.balance_sheet",
                "value": "Balance Sheet"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.total_assets",
                        "value": "Total Assets"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 2994035.05,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.null",
                                "value": ""
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 634081.81,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_ASSETS",
                                "value": "report.title.total_current_assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2359953.24,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.net_current_assets_liabilities",
                        "value": "Net Current Assets/(Liabilities)"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 816618.14,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_ASSETS",
                                "value": "report.title.total_current_assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2359953.24,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                "value": "report.title.total_current_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -1543335.1,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.bank_and_cash",
                        "value": "Bank and Cash"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": -128561.05,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.total_liabilities",
                        "value": "Total Liabilities"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 1586860.1,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                "value": "report.title.total_current_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -1543335.1,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_LONG_TERM_LIABILITIES",
                                "value": "report.title.total_long_term_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -43525,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.shareholders_funds_deficit",
                        "value": "Shareholders' Funds/(Deficit)"
                    },
                    "values": [
                        {
                            "type": "DECIMAL_AMOUNT",
                            "value": 1407174.95,
                            "displayFlipped": false
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.operating_ratios",
                "value": "Operating Ratios"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.gross_profit_margin",
                        "value": "Gross Profit Margin"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 29.61,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.GROSS_PROFIT",
                                "value": "Gross Profit/(Loss)"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -1436158.68,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.null",
                                "value": ""
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -4849758.77,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.gross_profit_markup",
                        "value": "Gross Profit Markup"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 42.07,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.GROSS_PROFIT",
                                "value": "Gross Profit/(Loss)"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1436158.68,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.null",
                                "value": ""
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 3413600.09,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.net_profit_margin",
                        "value": "Net Profit Margin"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 6.61,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.NET_PROFIT",
                                "value": "report.title.net_profit"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -320472.56,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_PROFIT",
                                        "value": "Operating Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -481616.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.GROSS_PROFIT",
                                                "value": "Gross Profit/(Loss)"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -1436158.68,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.OPERATING_COSTS",
                                                "value": "Operating Expenses"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 954541.84,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 1293636.12,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 339094.28,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.INTEREST_RECEIVABLE_BANK_CHARGES_AND_INTEREST_OTHER_INCOME",
                                        "value": "report.title.interest_receivable_bank_charges_and_interest_other_income"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 161144.28,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.null",
                                "value": ""
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -4849758.77,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.performance_ratios",
                "value": "Performance Ratios"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.return_on_total_assets",
                        "value": "Return on Total Assets"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 11.36,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.annualised-net-profit",
                                "value": "report.title.annualised-net-profit"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -320472.56,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_PROFIT",
                                        "value": "Operating Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -481616.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.GROSS_PROFIT",
                                                "value": "Gross Profit/(Loss)"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -1436158.68,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.OPERATING_COSTS",
                                                "value": "Operating Expenses"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 954541.84,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 1293636.12,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 339094.28,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.INTEREST_RECEIVABLE_BANK_CHARGES_AND_INTEREST_OTHER_INCOME",
                                        "value": "report.title.interest_receivable_bank_charges_and_interest_other_income"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 161144.28,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.avg-total-assets",
                                "value": "report.title.avg-total-assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2821934.52,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 632903.13,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.TOTAL_CURRENT_ASSETS",
                                        "value": "report.title.total_current_assets"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 2189031.39,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.return_on_capitial_employed",
                        "value": "Return on Capital Employed"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 31.53,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.annualised-operating-profit",
                                "value": "report.title.annualised-operating-profit"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -481616.84,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.GROSS_PROFIT",
                                        "value": "Gross Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -1436158.68,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_COSTS",
                                        "value": "Operating Expenses"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 954541.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 1293636.12,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 339094.28,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.avg-capital-employed",
                                "value": "report.title.avg-capital-employed"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1527627.61,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.TOTAL_ASSETS",
                                        "value": "Total Assets"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 2821934.52,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 632903.13,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.TOTAL_CURRENT_ASSETS",
                                                "value": "report.title.total_current_assets"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 2189031.39,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                        "value": "report.title.total_current_liabilities"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -1294306.91,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.activity_ratios",
                "value": "Activity Ratios"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.inventory_days",
                        "value": "Inventory Days"
                    },
                    "values": [
                        {
                            "type": "NUMBER",
                            "value": 28.7,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.avg-current-assets-stock",
                                "value": "report.title.avg-current-assets-stock"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 268430.76,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.annualisation-cost-of-sales",
                                "value": "report.title.annualisation-cost-of-sales"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 3413600.09,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.days_sales_outstanding",
                        "value": "Days Sales Outstanding"
                    },
                    "values": [
                        {
                            "type": "NUMBER",
                            "value": 120.82,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.avg-DEBTORS_CONTROL",
                                "value": "report.title.avg-debtors_control"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1605399.92,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.annualisation-sales",
                                "value": "report.title.annualisation-sales"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -4849758.77,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.days_payable_outstanding",
                        "value": "Days Payable Outstanding"
                    },
                    "values": [
                        {
                            "type": "NUMBER",
                            "value": 65.85,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.avg-creditors-control",
                                "value": "report.title.avg-creditors-control"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -655857.61,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.annualisation-purchase-ledger-activity",
                                "value": "report.title.annualisation-purchase-ledger-activity"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 3635550.28,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 4368141.93,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.null",
                                                "value": ""
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 3413600.09,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.OPERATING_COSTS",
                                                "value": "Operating Expenses"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 954541.84,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 1293636.12,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 339094.28,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 732591.65,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.liquidity_ratios",
                "value": "Liquidity Ratios"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.current_ratio",
                        "value": "Current Ratio"
                    },
                    "values": [
                        {
                            "type": "RATIO",
                            "value": 1.53,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_ASSETS",
                                "value": "report.title.total_current_assets"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2359953.24,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                "value": "report.title.total_current_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1543335.1,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.quick_ratio",
                        "value": "Quick Ratio"
                    },
                    "values": [
                        {
                            "type": "RATIO",
                            "value": 1.32,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.debit-bank-account-debtors-control-bad-debt-provision-investment",
                                "value": "report.title.debit-bank-account-debtors-control-bad-debt-provision-investment"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 2030238.88,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 347878.84,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 1681860.04,
                                            "displayFlipped": false
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.SHORT_TERM_INVESTMENTS_WDV",
                                        "value": "report.title.short_term_investments_wdv"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 500,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                "value": "report.title.total_current_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1543335.1,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        },
        {
            "title": {
                "type": "LABEL",
                "key": "report.title.debt_ratios",
                "value": "Debt Ratios"
            },
            "values": [],
            "children": [
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.debt_to_equity",
                        "value": "Debt to Equity"
                    },
                    "values": [
                        {
                            "type": "PERCENTAGE",
                            "value": 3.11,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TOTAL_LONG_TERM_LIABILITIES",
                                "value": "report.title.total_long_term_liabilities"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -43525,
                                    "displayFlipped": false
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.TANGIBLE_NET_WORTH",
                                "value": "report.title.tangible_net_worth"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": 1401174.95,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.NET_ASSETS",
                                        "value": "Net Assets"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 1407174.95,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.TOTAL_ASSETS",
                                                "value": "Total Assets"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 2994035.05,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 634081.81,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.TOTAL_CURRENT_ASSETS",
                                                        "value": "report.title.total_current_assets"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 2359953.24,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.TOTAL_LIABILITIES",
                                                "value": "Total Liabilities"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -1586860.1,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.TOTAL_CURRENT_LIABILITIES",
                                                        "value": "report.title.total_current_liabilities"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": -1543335.1,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.TOTAL_LONG_TERM_LIABILITIES",
                                                        "value": "report.title.total_long_term_liabilities"
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": -43525,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.INTANGIBLE_ASSETS",
                                        "value": "Intangible Assets"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 6000,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                },
                {
                    "title": {
                        "type": "LABEL",
                        "key": "report.title.interest_cover",
                        "value": "Interest Cover"
                    },
                    "values": [
                        {
                            "type": "RATIO",
                            "value": 43.93,
                            "displayFlipped": false
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.EBITDA",
                                "value": "EBITDA"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -489616.84,
                                    "displayFlipped": false
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.OPERATING_PROFIT",
                                        "value": "Operating Profit/(Loss)"
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": -481616.84,
                                            "displayFlipped": false
                                        }
                                    ],
                                    "children": [
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.GROSS_PROFIT",
                                                "value": "Gross Profit/(Loss)"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": -1436158.68,
                                                    "displayFlipped": false
                                                }
                                            ]
                                        },
                                        {
                                            "title": {
                                                "type": "LABEL",
                                                "key": "report.title.OPERATING_COSTS",
                                                "value": "Operating Expenses"
                                            },
                                            "values": [
                                                {
                                                    "type": "DECIMAL_AMOUNT",
                                                    "value": 954541.84,
                                                    "displayFlipped": false
                                                }
                                            ],
                                            "children": [
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 1293636.12,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                },
                                                {
                                                    "title": {
                                                        "type": "LABEL",
                                                        "key": "report.title.null",
                                                        "value": ""
                                                    },
                                                    "values": [
                                                        {
                                                            "type": "DECIMAL_AMOUNT",
                                                            "value": 339094.28,
                                                            "displayFlipped": false
                                                        }
                                                    ]
                                                }
                                            ]
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "type": "LABEL",
                                        "key": "report.title.null",
                                        "value": ""
                                    },
                                    "values": [
                                        {
                                            "type": "DECIMAL_AMOUNT",
                                            "value": 8000,
                                            "displayFlipped": false
                                        }
                                    ]
                                }
                            ]
                        },
                        {
                            "title": {
                                "type": "LABEL",
                                "key": "report.title.BANK_CHARGES_AND_INTEREST",
                                "value": "report.title.bank_charges_and_interest"
                            },
                            "values": [
                                {
                                    "type": "DECIMAL_AMOUNT",
                                    "value": -11144.28,
                                    "displayFlipped": false
                                }
                            ]
                        }
                    ],
                    "displayType": "HIDE_CHILDREN"
                }
            ],
            "displayType": "TITLE_ONLY"
        }
    ],
    "currency": {
        "id": 826,
        "iso3": "GBP",
        "decimals": 2,
        "name": "Pound Sterling",
        "symbol": null
    }
}

The Financial Snapshot is based on the customer’s data using the Validis Chart of Accounts (CoA). Please note that this report will change if the CoA is amended in DataShare View and this report may be wrong if there are unassigned accounts in the CoA. You will be notified will an error message if there unassigned accounts and you will be able to override this to get a response with the details as they are by using the acceptUnassigned optional parameter.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

Parameter Type Constraint Description Location
acceptUnassigned Boolean Optional See acceptUnassigned query string parameter

The following elements are returned in the GET Financial Snapshot response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

Quality Score (Beta)

Example request for GET Quality Score

curl -X GET \
  'https://api.sandbox.validis.com/v1/reports/quality-score/engagements/660?year=current \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDgwNjIyMzIsInVzZXJJZCI6NjI3LCJqdGkiOiI3MmE1Mzk4Mi0yNTEyLTQ4NDgtODMwMy1lMjg5ZTU5ODRlNzIiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTMzMzhlYmJkMzEwNzRhZWFiZjI4MWZjYWMzYjQ0ZmQxLCBjcmVhdGVkQXQ9MjAxOC0xMi0xMSAxMDowNDowNS4zODcsIGNyZWF0ZWRCeT05MDksIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.cuvMDoCBWkkYCiR5tEphqBHq2SkaNEAbhzRrP3G2Nlg' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Quality Score

{
    "view": {
        "name": "quality-score",
        "foundation": "custom",
        "rangeDefinitions": [
            {
                "type": "YTD",
                "fromRangeEnd": "0"
            },
            {
                "type": "YEAR",
                "fromRangeEnd": "-1"
            },
            {
                "type": "YEAR",
                "fromRangeEnd": "-2"
            }
        ],
        "autoSize": true,
        "fields": [],
        "showStartPeriod": true
    },
    "ranges": [
        {
            "startPeriod": {
                "startDate": [
                    2017,
                    1,
                    1
                ],
                "endDate": [
                    2017,
                    1,
                    31
                ],
                "periodId": 201701,
                "name": "FP-1"
            },
            "endPeriod": {
                "startDate": [
                    2017,
                    12,
                    1
                ],
                "endDate": [
                    2017,
                    12,
                    31
                ],
                "periodId": 201712,
                "name": "FP-12"
            },
            "type": "YEAR",
            "yearId": 2017,
            "name": "FY-2017"
        }
    ],
    "elements": [
        {
            "title": {
                "key": "report.quality-score.overall",
                "type": "LABEL"
            },
            "values": [
                {
                    "type": "OVERALL_QUALITY_SCORE",
                    "value": 0.8,
                    "penaltyScoreStatus": "EXCELLENT",
                    "originalValue": 0.8042,
                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.excellent"
                }
            ],
            "children": [
                {
                    "title": {
                        "key": "report.quality-score.account-receivable-score",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.avg-materiality",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "AMOUNT",
                                    "value": 4810745.1
                                }
                            ]
                        },
                        {
                            "title": {
                                "key": "report.quality-score.ar-ap-score.diff",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "key": "report.quality-score.ar-ap-score.gl-balance",
                                        "type": "LABEL"
                                    },
                                    "values": [
                                        {
                                            "value": 146255606,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 147294094,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 184433072,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 152714683,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 153786962,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 157541970,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 164038651,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 164508816,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 165688480,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 169285422,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 168100761,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 168696504,
                                            "type": "AMOUNT"
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "key": "report.quality-score.ar-ap-score.aged-balance",
                                        "type": "LABEL"
                                    },
                                    "values": [
                                        {
                                            "value": 146255606,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 147294094,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 184433072,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 152714683,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 153786962,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 157541970,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 164038651,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 164508816,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 165688480,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 169285422,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 168100761,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 168696504,
                                            "type": "AMOUNT"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.account-payable-score",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.avg-materiality",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "AMOUNT",
                                    "value": 4810745.1
                                }
                            ]
                        },
                        {
                            "title": {
                                "key": "report.quality-score.ar-ap-score.diff",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                },
                                {
                                    "type": "AMOUNT",
                                    "value": 0
                                }
                            ],
                            "children": [
                                {
                                    "title": {
                                        "key": "report.quality-score.ar-ap-score.gl-balance",
                                        "type": "LABEL"
                                    },
                                    "values": [
                                        {
                                            "value": 63533174,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 52575049,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 79410309,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 62299594,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 62659939,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 56525356,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 64906607,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 71439577,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 70171455,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 66399345,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 67236069,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 69105135,
                                            "type": "AMOUNT"
                                        }
                                    ]
                                },
                                {
                                    "title": {
                                        "key": "report.quality-score.ar-ap-score.aged-balance",
                                        "type": "LABEL"
                                    },
                                    "values": [
                                        {
                                            "value": 63533174,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 52575049,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 79410309,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 62299594,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 62659939,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 56525356,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 64906607,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 71439577,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 70171455,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 66399345,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 67236069,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 69105135,
                                            "type": "AMOUNT"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.wages",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 12.0746831229,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.wages",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 12.07,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.depreciation",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0.02,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0.01909,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "range:0",
                                "type": "LABEL"
                            },
                            "values": [],
                            "children": [
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201701,
                                            "closingBalance": 4305630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4305630,
                                            "periodDepExpectation": 17940.125143521,
                                            "cumulativeDepExpectation": 17940.125143521,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 0,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201702,
                                            "closingBalance": 4305630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4305630,
                                            "periodDepExpectation": 17940.125143521,
                                            "cumulativeDepExpectation": 35880.250287042,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 0,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201703,
                                            "closingBalance": 4105630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4205630,
                                            "periodDepExpectation": 17523.458473521,
                                            "cumulativeDepExpectation": 53403.708760563,
                                            "actualDepCharge": 200000,
                                            "cumulativeDepCharge": 200000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201704,
                                            "closingBalance": 4105630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4105630,
                                            "periodDepExpectation": 17106.791803521,
                                            "cumulativeDepExpectation": 70510.500564084,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 200000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201705,
                                            "closingBalance": 4105630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4105630,
                                            "periodDepExpectation": 17106.791803521,
                                            "cumulativeDepExpectation": 87617.292367605,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 200000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201706,
                                            "closingBalance": 3905630,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4005630,
                                            "periodDepExpectation": 16690.125133521,
                                            "cumulativeDepExpectation": 104307.417501126,
                                            "actualDepCharge": 200000,
                                            "cumulativeDepCharge": 400000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201707,
                                            "closingBalance": 4404858,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4155244,
                                            "periodDepExpectation": 17313.5168051748,
                                            "cumulativeDepExpectation": 121620.9343063008,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 400000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201708,
                                            "closingBalance": 4909569,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4657213.5,
                                            "periodDepExpectation": 19405.05640524045,
                                            "cumulativeDepExpectation": 141025.99071154125,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 400000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201709,
                                            "closingBalance": 4709569,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4809569,
                                            "periodDepExpectation": 20039.8709936523,
                                            "cumulativeDepExpectation": 161065.86170519355,
                                            "actualDepCharge": 200000,
                                            "cumulativeDepCharge": 600000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201710,
                                            "closingBalance": 4709569,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4709569,
                                            "periodDepExpectation": 19623.2043236523,
                                            "cumulativeDepExpectation": 180689.06602884585,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 600000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201711,
                                            "closingBalance": 4709569,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4709569,
                                            "periodDepExpectation": 19623.2043236523,
                                            "cumulativeDepExpectation": 200312.27035249815,
                                            "actualDepCharge": 0,
                                            "cumulativeDepCharge": 600000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                },
                                {
                                    "title": {
                                        "depreciationDto": {
                                            "periodId": 201712,
                                            "closingBalance": 4509569,
                                            "averageYealyBalance": 4398873.5833333334,
                                            "averagePeriodBalance": 4609569,
                                            "periodDepExpectation": 19206.5376536523,
                                            "cumulativeDepExpectation": 219518.80800615045,
                                            "actualDepCharge": 200000,
                                            "cumulativeDepCharge": 800000,
                                            "lastPeriodInFinancialYear": true
                                        },
                                        "type": "Depreciation"
                                    },
                                    "values": []
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.stock",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "rangeStockDto": {
                                    "range": {
                                        "startPeriod": {
                                            "startDate": [
                                                2017,
                                                1,
                                                1
                                            ],
                                            "endDate": [
                                                2017,
                                                1,
                                                31
                                            ],
                                            "periodId": 201701,
                                            "name": "FP-1"
                                        },
                                        "endPeriod": {
                                            "startDate": [
                                                2017,
                                                12,
                                                1
                                            ],
                                            "endDate": [
                                                2017,
                                                12,
                                                31
                                            ],
                                            "periodId": 201712,
                                            "name": "FP-12"
                                        },
                                        "type": "YEAR",
                                        "yearId": 2017,
                                        "name": "FY-2017"
                                    },
                                    "averageYearlyBalance": 26779559,
                                    "stockDtos": [
                                        {
                                            "periodId": 201701,
                                            "tangibleCostClosingBalance": 25544584,
                                            "valueOfTransactions": 2060700,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201702,
                                            "tangibleCostClosingBalance": 24315984,
                                            "valueOfTransactions": 1228600,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201703,
                                            "tangibleCostClosingBalance": 23652784,
                                            "valueOfTransactions": 663200,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201704,
                                            "tangibleCostClosingBalance": 29084884,
                                            "valueOfTransactions": 5432100,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201705,
                                            "tangibleCostClosingBalance": 26358984,
                                            "valueOfTransactions": 2725900,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201706,
                                            "tangibleCostClosingBalance": 24987684,
                                            "valueOfTransactions": 1371300,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201707,
                                            "tangibleCostClosingBalance": 27112684,
                                            "valueOfTransactions": 2125000,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201708,
                                            "tangibleCostClosingBalance": 28937784,
                                            "valueOfTransactions": 1825100,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201709,
                                            "tangibleCostClosingBalance": 28708384,
                                            "valueOfTransactions": 229400,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201710,
                                            "tangibleCostClosingBalance": 26835884,
                                            "valueOfTransactions": 1872500,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201711,
                                            "tangibleCostClosingBalance": 28066984,
                                            "valueOfTransactions": 1231100,
                                            "lastPeriodInFinancialYear": false
                                        },
                                        {
                                            "periodId": 201712,
                                            "tangibleCostClosingBalance": 27748084,
                                            "valueOfTransactions": 318900,
                                            "lastPeriodInFinancialYear": true
                                        }
                                    ],
                                    "costOfSales": 30936368
                                },
                                "type": "Stock"
                            },
                            "values": []
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.accruals",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0.11,
                            "penaltyScoreStatus": "POOR",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.poor"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.accruals",
                                "type": "LABEL"
                            },
                            "displayType": "TITLE_ONLY",
                            "children": [
                                {
                                    "title": {
                                        "key": "201701:201712",
                                        "type": "LABEL"
                                    },
                                    "values": [
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        },
                                        {
                                            "value": 0,
                                            "type": "AMOUNT"
                                        }
                                    ]
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.timeliness",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": -1,
                            "penaltyScoreStatus": "NON_APPLICABLE",
                            "originalValue": -1,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.non-applicable"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.timeliness-differences",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": -1,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.trial-balance",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.avg-materiality",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "AMOUNT",
                                    "value": 4810745.1
                                }
                            ]
                        },
                        {
                            "title": null,
                            "values": [
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                },
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.profit-loss-unexpected-transactions",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 501525,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.pl-ut-max-differences",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 501525,
                                    "type": "AMOUNT"
                                }
                            ]
                        },
                        {
                            "title": {
                                "key": "unExpected_materiality",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 4849758.77,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.balance-sheet-unexpected-transactions",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0,
                            "penaltyScoreStatus": "GOOD",
                            "originalValue": 0,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.pl-ut-max-differences",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 0,
                                    "type": "AMOUNT"
                                }
                            ]
                        },
                        {
                            "title": {
                                "key": "unExpected_materiality",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 4849758.77,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.profit-loss-unexpected-balance",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0.02,
                            "penaltyScoreStatus": "SATISFACTORY",
                            "originalValue": 15000000,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.satisfactory"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.pl-ub-max-differences",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 15000000,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.balance-sheet-unexpected-balance",
                        "type": "LABEL"
                    },
                    "values": [
                        {
                            "type": "QUALITY_SCORE",
                            "value": 0.06,
                            "penaltyScoreStatus": "SATISFACTORY",
                            "originalValue": 32508563,
                            "penaltyScoreStatusCustomizationKey": "report.quality-score.status.satisfactory"
                        }
                    ],
                    "children": [
                        {
                            "title": {
                                "key": "report.quality-score.pl-ub-max-differences",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "value": 32508563,
                                    "type": "AMOUNT"
                                }
                            ]
                        }
                    ]
                },
                {
                    "title": {
                        "key": "report.quality-score.all-penalties-debug",
                        "type": "LABEL"
                    },
                    "values": [],
                    "children": [
                        {
                            "title": {
                                "key": "penalties for range: 0",
                                "type": "LABEL"
                            },
                            "values": [
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 12.0746831229,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0.02,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0.01909,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0.11,
                                    "penaltyScoreStatus": "POOR",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.poor"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": -1,
                                    "penaltyScoreStatus": "NON_APPLICABLE",
                                    "originalValue": -1,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.non-applicable"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 501525,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0,
                                    "penaltyScoreStatus": "GOOD",
                                    "originalValue": 0,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.good"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0.02,
                                    "penaltyScoreStatus": "SATISFACTORY",
                                    "originalValue": 15000000,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.satisfactory"
                                },
                                {
                                    "type": "QUALITY_SCORE",
                                    "value": 0.06,
                                    "penaltyScoreStatus": "SATISFACTORY",
                                    "originalValue": 32508563,
                                    "penaltyScoreStatusCustomizationKey": "report.quality-score.status.satisfactory"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

The Quality Score is based on the customer’s data using the Validis Chart of Accounts (CoA). Please note that this report will change if the CoA is amended in DataShare View and this report may be wrong if there are unassigned accounts in the CoA. You will be notified will an error message if there unassigned accounts and you will be able to override this to get a response with the details as they are by using the acceptUnassigned optional parameter.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header
ranges String Either ranges or year is required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). query string parameter
year String Either ranges or year is required Options to input are: Current – Current financial year to date, Previous1 – Last full financial year, Previous2 – Penultimate full financial year, Previous3 – etc. You will only be able to request the number of financial years that you have purchased. Can only have ranges or year and must have at least one stated. query string parameter

Optional Parameters

Parameter Type Constraint Description Location
acceptUnassigned Boolean Optional See acceptUnassigned query string parameter

The following elements are returned in the GET Quality Score response

Field Format Description
startDate ISO Date Start date of the financial period in the format “yyyy-mm-dd”
endDate ISO Date End date of the financial period in the format “yyyy-mm-dd”
periodId Integer The Id of the financial period
name String The name of the field
yeadId Integer The Id of the financial year
key String The unique identifier for the category/tag
type String See Types
value Varies See Types
displayFlipped Boolean This shows if the value should be reversed (positive/negative) to the value given to display it in the same way as the Validis report.
Id Integer The Id of currency for the upload
Iso3 ISO Currency 3 character ISO code for the currency
decimals Integer Number of decimal places that needs to be applied to the value (the value will be shown in the lowest common denominator e.g. GBP will be in pence / USD will be in cents, the decimals will show how to convert the value into the currency value)
symbol String The character symbol for the currency

General Ledger (JSON)

Overview

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/accounts
Methods Supported GET
URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/accountSummaries
Methods Supported GET
URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/journals
Methods Supported GET

These endpoints give you access to the General Ledger (GL) transactions from the accounting package. Although the data is standardised into a Validis defined format, the transactions are shown as close to the original data source as possible. This means as each package has different ways of handling scenarios, you will see the transactions as the accounting package has processed them.

Accounts (Beta)

Example request for GET GL Accounts

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/accounts \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzc2MzYsInVzZXJJZCI6NjI3LCJqdGkiOiIxMzg5OGNiMi0zMmI0LTQzYzItOGZmMy1mYjU5ZDJmMDJmZDciLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.50vGryBQSZbuRgcD2HpZae3eirTDBTzAJiVuuQWhaJI' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET GL Accounts

[
    {
        "accountId": "186",
        "remotePk": "2775",
        "code": "2775",
        "name": "Asset finance - long term",
        "primaryCategory": "LONG_TERM_LIABILITIES",
        "tag": "OTHER_CAPITAL_OBLIGATIONS_LONG_TERM",
        "currencyIso": "GBP",
        "createdTimestamp": "2018-11-15T11:26:17.471",
        "modifiedTimestamp": "2018-11-15T11:26:17.471",
        "status": "POSTING"
    },
    {
        "accountId": "187",
        "remotePk": "2801",
        "code": "2801",
        "name": "Grant",
        "primaryCategory": "CURRENT_LIABILITIES",
        "tag": "GRANTS_RECEIVABLE",
        "currencyIso": "GBP",
        "createdTimestamp": "2018-11-15T11:26:17.471",
        "modifiedTimestamp": "2018-11-15T11:26:17.471",
        "status": "POSTING"
    },
    {
        "accountId": "188",
        "remotePk": "2802",
        "code": "2802",
        "name": "Grants",
        "primaryCategory": "CURRENT_LIABILITIES",
        "tag": "GRANTS_RECEIVABLE",
        "currencyIso": "GBP",
        "createdTimestamp": "2018-11-15T11:26:17.471",
        "modifiedTimestamp": "2018-11-15T11:26:17.471",
        "status": "POSTING"
    }
]

The GL Accounts endpoint gives you the mapping between the accounting packages accounts and how they map to the Validis defined Chart of Accounts (CoA).

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
primaryCategories String Optional Primary categories (comma separated) in which account must belongs query parameter
tags String Optional Tags (comma separated) in which account must belongs query parameter
status Account Status Optional Comma separated list of Account Status query parameter

The following elements are returned in the GET GL Accounts response

Field Format Description
accountId String DataShare internal unique identifier
remotePk String Accounting package reference
code String Account code
name String Account name
primaryCategory String Validis defined [category] (#Primary_Category) (Validis Chart of Accounts)
tag String Validis defined [tag] (#tags) (Validis Chart of Accounts)
currencyIso String ISO code of account currency (3 chars)
createdTimestamp Timestamp Time when account has been created
modifiedTimestamp Timestamp Last time when account has been updated
status Sting The status of the account

Account Summaries (Beta)

Example request

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/accountSummaries?ranges\
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzc2MzYsInVzZXJJZCI6NjI3LCJqdGkiOiIxMzg5OGNiMi0zMmI0LTQzYzItOGZmMy1mYjU5ZDJmMDJmZDciLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.50vGryBQSZbuRgcD2HpZae3eirTDBTzAJiVuuQWhaJI' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response

[
    {
        "accountId": "110",
        "code": "1100",
        "name": "Accounts Receivable",
        "primaryCategory": "CURRENT_ASSETS",
        "tag": "DEBTORS_CONTROL",
        "summaries": [
            {
                "range": {
                    "rangeId": "201801:201806",
                    "fromDate": "2018-01-01",
                    "toDate": "2018-06-30"
                },
                "debit": 2620998.64,
                "credit": -2521171.51,
                "movement": 99827.13,
                "openingBalance": 1686965.04,
                "closingBalance": 1786792.17
            },
            {
                "range": {
                    "rangeId": "201701:201706",
                    "fromDate": "2017-01-01",
                    "toDate": "2017-06-30"
                },
                "debit": 2285852.03,
                "credit": -2157181.18,
                "movement": 128670.85,
                "openingBalance": 1446748.85,
                "closingBalance": 1575419.7
            }
        ]
    }
]

The GL Accounts summaries endpoint gives you opening and closing balances, movement and the split between the debtis and credits for each account including the Validis defined Chart of Accounts (CoA) category and tag.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
ranges String Required Starting and Ending Period Identifier separated by a colon (can be multiple ranges when comma separated). Can only have ranges or year and must have at least one stated. query string parameter
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
primaryCategories String Optional Primary categories (comma separated) in which account must belongs query parameter
tags String Optional Tags (comma separated) in which account must belongs query parameter
status Account Status Optional Comma separated list of Account Status query parameter

The following elements are returned in the GET GL Account Summaries response

Field Format Description
accountId String DataShare internal unique identifier
code String Account code
name String Account name
primaryCategory String Validis defined [category] (#Primary_Category) (Validis Chart of Accounts)
tag String Validis defined [tag] (#tags) (Validis Chart of Accounts)
summaries Summary see below

Summary

Field Format Description
range Range See below
debit Decimal Sum of all debit transactions during the range
credit Decimal Sum of all credit transactions during the range
movement Decimal Sum of all transactions during the range
openingBalance Decimal Balance at the beginning of the range
closingBalance Decimal Balance at the end of the range

Range

Field Format Description
rangeId String identifier as in the request: <startPeriod>:<endPeriod>
fromDate Date First day of the start period
toDate Date Last day of the end period

Journals (Beta)

Request example

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/journals?fromPeriodId=201801&toPeriodId=201812 \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzc2MzYsInVzZXJJZCI6NjI3LCJqdGkiOiIxMzg5OGNiMi0zMmI0LTQzYzItOGZmMy1mYjU5ZDJmMDJmZDciLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.50vGryBQSZbuRgcD2HpZae3eirTDBTzAJiVuuQWhaJI' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response

{
    "page": 0,
    "hasNext": true,
    "content": [
        {
            "journalId": "96264",
            "remotePk": "96264",
            "journalRef": "96264",
            "journalType": "sales",
            "transactionDate": "2018-01-16",
            "financialPeriod": {
                "periodId": 201801,
                "startDate": "2018-01-01",
                "endDate": "2018-01-31"
            },
            "description": "2459",
            "entryTimestamp": "2018-01-31T00:00:00",
            "entryUser": "MANAGER",
            "postingTimestamp": "2018-01-31T00:00:00",
            "postingUser": "MANAGER",
            "bankRec": false,
            "vatRec": true,
            "systemGenerated": false,
            "source": "SALES",
            "modifiedTimestamp": "1970-01-01T00:00:01.12",
            "modifiedUser": "MANAGER",
            "lines": [
                {
                    "lineId": "34336222",
                    "remotePk": "1100:96264",
                    "account": {
                        "accountId": "110",
                        "remotePk": "1100",
                        "code": "1100",
                        "name": "Accounts Receivable",
                        "primaryCategory": "CURRENT_ASSETS",
                        "tag": "DEBTORS_CONTROL"
                    },
                    "baseValue": 1109.08,
                    "transactionValue": 1109.08,
                    "currencyIso": "GBP",
                    "reportingCurrencyIso": "GBP",
                    "transactionExchangeRate": 1,
                    "reportingValue": 1109.08,
                    "reportingExchangeRate": 1,
                    "source": "SALES",
                    "description": "Sales"
                },
                {
                    "lineId": "34336223",
                    "remotePk": "4005:96264",
                    "account": {
                        "accountId": "214",
                        "remotePk": "4005",
                        "code": "4005",
                        "name": "Sales London/South East",
                        "primaryCategory": "SALES",
                        "tag": "SALES_TAG"
                    },
                    "baseValue": -924.23,
                    "transactionValue": -924.23,
                    "currencyIso": "GBP",
                    "reportingCurrencyIso": "GBP",
                    "transactionExchangeRate": 1,
                    "reportingValue": -924.23,
                    "reportingExchangeRate": 1,
                    "source": "SALES",
                    "description": "Sales"
                },
                {
                    "lineId": "34336224",
                    "remotePk": "2200:96264",
                    "account": {
                        "accountId": "159",
                        "remotePk": "2200",
                        "code": "2200",
                        "name": "Sales Tax Control Account",
                        "primaryCategory": "CURRENT_LIABILITIES",
                        "tag": "NET_VAT_LIABILITY"
                    },
                    "baseValue": -184.85,
                    "transactionValue": -184.85,
                    "currencyIso": "GBP",
                    "reportingCurrencyIso": "GBP",
                    "transactionExchangeRate": 1,
                    "reportingValue": -184.85,
                    "reportingExchangeRate": 1,
                    "source": "SALES",
                    "description": "Sales"
                }
            ]
        }
    ]
}

The GL Journals endpoint will show the GL transactions from the accounting package and they will be associated with the Validis CoA. You can filter by periods or dates and types to access the transactions you require.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Page number to retrieve, starting at 0. Default is 0 query parameter
size Integer Optional Number of elements by page, might be restricted if too high. Default is 200 query parameter
fromPeriodId Integer Optional Inclusive period id from which journals should be retrieve query parameter
toPeriodId Integer Optional Inclusive period id up to which journals should be retrieve query parameter
fromDate Date Optional Inclusive transaction date, in ISO format, from when journals are selected query parameter
toDate Date Optional Inclusive transaction date, in ISO format, up to when journals are selected query parameter
types String Optional Comma separated list of Journal Types query parameter

The following elements are returned in the GET GL Journals response

Field Format Description
journalId String DataShare internal unique identifier
remotePk String Accounting package reference
journalRef String Transaction number / Journal number
journalType JournalType See Journal Type
transactionDate Date Transaction / Document date of the transaction
financialPeriod Financial Period Financial period in which journal has been reported, see below
description String General ledger transaction narrative/description
entryTimestamp Timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
entryUser String User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
postingTimestamp Timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
postingUser String User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
bankRec Boolean Indicator to show if the transaction has been reconciled with a bank account (not applicable, unreconciled or reconciled)
vatRec Boolean Indicator to show if the transaction has been reconciled with a vat account (not applicable, unreconciled or reconciled)
systemGenerated Boolean Indicator to show if the transaction was automatically generated by the system
source String Transaction type held within the general ledger
modifiedTimestamp Timestamp Time the transaction was last modified on the system (only applies to certain accounting packages)
modifiedUser String User/Username who last modified the journal (may be the same as the entry user for certain accounting packages)
lines JournalEntry see below
     
page integer Requested page number
hasNext Boolean True when this is not the last page and other elements can be retrieved with page=<thisPage+1>

FinancialPeriod

Field Format Description
periodId Number DataShare internal unique identifier
startDate Date Period first day (inclusive)
endDate Date Period last day (inclusive)

JournalEntry

Field Format Description
lineId String DataShare internal unique identifier
remotePk String Accounting package reference
account AccountRef See below
baseValue Decimal Journal entry amount in the base currency (base currency set in accounting package)
transactionValue Decimal Journal entry amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
currencyIso String Currency ISO code (3 chars)
reportingCurrencyIso String Currency ISO code (3 chars)
transactionExchangeRate String Transaction exchange rate calculated from transactionValue / baseValue
reportingValue Decimal Reporting amount in reporting currency (only applies to certain accounting packages)
reportingExchangeRate Decimal Reporting exchange rate calculated from REPORTING_VALUE/BASE VALUE (if reporting currency is different to base currency – only applies to certain accounting packages)
source String Transaction type held within the general ledger
description String General ledger transaction additional narrative, reference fields

AccountRef

Field Format Description
accountId String DataShare internal unique identifier
primaryCategory String Account [primary category] (#Primary_Category)
tag String Account [tag] (#tags)
remotePk String Transaction number / Journal number
code String Account code
name String Account name

Journal Types

JournalTypes are in a static list as follow:

Type Description
JOURNAL Journal transaction
BANK Bank transaction
CASH Short term cash transaction
WAGES Wage related transaction
PURCHASES Purchases
SALES Sales
CAPEX Other
SALE_CREDIT Capital expenditure
PURCHASE_CREDIT Sale credit
VAT Purchase credit
STOCK VAT transaction
OPENING_BALANCE Stock movement
BALANCE_FORWARD Opening balance
YEAR_END Year end
CREDIT_CARD Credit card
PURCHASE_LINK Purchase link
SALES_LINK Sales link
YE_BS Year end – balance sheet
YE_PL Year end – profit and loss
OTHER Balance forward transaction

Accounts Receivable (JSON)

Overview

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/receivableItems
Methods Supported GET
URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/customers
Methods Supported GET

These endpoints give you access to the Accounts Receivable(AR) transactions and their associated customers from the accounting package. Although the data is standardised into a Validis defined format, the transactions are shown as close to the original data source as possible. This means as each package has different ways of handling scenarios, you will see the transactions as the accounting package has processed them.

Item types

ItemTypes are in a static list as follow:

Type Description
INVOICE Invoice
PAYMENT Payment
CREDIT_NOTE Credit note
DISCOUNT Discount
WRITE_OFF Write-off
REFUND Refund
CURRENCY_GAIN_LOSS Currency gain or loss
ADJUSTMENT Adjustment
BALANCE_FORWARD Balance carried forward

Receivable Items (Beta)

Example request for GET Receivable Items

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/receivableItems?openItems=True&showLinks=True&showAllocations=True \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzk1MTUsInVzZXJJZCI6NjI3LCJqdGkiOiI0MzczODkxNy0xMzIyLTRjOWUtYjQxZi05NzZiNmQyYjYxMGMiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.q_EqXILOjvCkLeRlC3u_q5ypFPQaVrDyQtXGhZcj8MA' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Receivable Items

{
  "page": 0,
  "hasNext": true,
  "content": [
        {
            "itemId": "41697",
            "itemType": "INVOICE",
            "documentId": "1",
            "contactDocumentId": "Sales",
            "transactionDate": "2010-07-02",
            "transactionValue": 66.72,
            "baseValue": 66.72,
            "taxValue": 9.72,
            "currencyIso": "GBP",
            "exchangeRate": 1,
            "entryTimestamp": "2010-11-18T00:00:00",
            "entryUser": "MANAGER",
            "postingTimestamp": null,
            "postingUser": "MANAGER",
            "bankRec": "NOT_APPLICABLE",
            "vatRec": "UNRECONCILED",
            "holdFlag": null,
            "disputeFlag": null,
            "voidFlag": false,
            "reversalFlag": null,
            "reversalId": null,
            "modifiedTimestamp": null,
            "modifiedUser": null,
            "paymentMethod": null,
            "dueDate": "2010-08-01",
            "baseBalance": 0,
            "transactionBalance": 0,
            "financialPeriod": {
                "periodId": 201007,
                "startDate": "2010-07-01",
                "endDate": "2010-07-31"
            },
            "allocations": [
                {
                    "allocationDate": "2010-07-29",
                    "allocationValue": 66.72,
                    "baseValue": 66.72,
                    "items": [
                        {
                            "itemId": "42324",
                            "remotePk": "42324",
                            "baseValue": 5728.68,
                            "transactionValue": 5728.68,
                            "currencyIso": "GBP"
                        }
                    ]
                }
            ],
            "links": [
                {
                    "journalId": "41697",
                    "remotePk": "41697",
                    "journalRef": "41697"
                }
            ],
            "customer": {
                "customerId": "4",
                "code": "A1D001",
                "name": "A1 Design Services",
                "contacts": [
                    {
                        "address1": null,
                        "address2": null,
                        "address3": null,
                        "townCity": null,
                        "stateCounty": null,
                        "postZipCode": null,
                        "countryCode": "GBR",
                        "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                    },
                    {
                        "address1": null,
                        "address2": null,
                        "address3": null,
                        "townCity": null,
                        "stateCounty": null,
                        "postZipCode": null,
                        "countryCode": "GBR",
                        "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                    }
                ]
            }
        }
    ]
 }

The Receivable Item endpoint will show the AR transactions from the accounting package. You can filter by periods, only showing open items, showing the links to the GL transactions that were created from the AR transactions and any associated AR Transactions that have been allocated to this transaction.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Page number to retrieve, starting at 0. Default is 0 query parameter
size Integer Optional Number of elements by page, might be restricted if too high. Default is 200 query parameter
fromPeriodId Integer Optional Select items within or later selected financial period query string parameter
toPeriodId Integer Optional Select items within or before selected financial period query string parameter
customerId Number Optional Internal identifier for the customer query string parameter
openItems Boolean Optional Filter out settle items to only return those that have a 0 balance. If false, the default, includes all items settled or not. query string parameter
itemtypes ItemType Optional Filter items by their type, comma separated query string parameter
showLinks Boolean Optional Add GL links array to the response query string parameter
showAllocations Boolean Optional Add allocation array to the response query string parameter
DisplayAbsolute Boolean Optional Default is True. Change to false to recieved signed data query string parameter

The following elements are returned in the GET Receivable Items response

Field Format Description
itemId String DataShare internal unique ID
itemType String Type of Receivable/Purchase item
documentId String Invoice number from the accounting package
customerDocumentId String Customer external document reference or description of invoice
transactionDate Date Transaction date
financialPeriod FinancialPeriod see below
transactionValue Decimal Item amount in foreign currency
baseValue Decimal Item amount in accounting package currency
taxValue Decimal VAT value of the transaction
currencyIso String Currency ISO code (3 chars)
exchangeRate Decimal Currency exchange rate between local and foreign currencies
entryTimestamp Timestamp Date and time the transaction was first created on the system
entryUser String The user that created the entry on the accounting package
postingTimestamp Timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
postingUser String User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
dueDate Date Date payment is due for the transaction
bankRec String Indicator to show if the transaction has been reconciled with a bank account (not applicable, unreconciled or reconciled)
vatRec String Indicator to show if the transaction has been reconciled with a vat account (not applicable, unreconciled or reconciled)
holdFlag Boolean Indicator to show if the transaction has been set to be on hold
disputeFlag Boolean Indicator to show if the transaction has been set to be disputed
voidFlag Boolean Indicator to show if the transaction has been set to be voided
reversalFlag String Indicator to show if the transaction has been reversed (NO, REVERSED, or REVERSING)
reversalId String TransactionID of the reversal transaction
modifiedTimestamp Timestamp Time the transaction was last modified on the system (may be the same as the entry timestamp for certain accounting packages)
modifiedUser String User/Username who last modified the transaction (may be the same as the entry user for certain accounting packages)
paymentMethod String The payment method for the Transaction
dueDate Date Payment due date
allocations Allocation[] List of allocations with other items - see below
links GlLink[] Links to GL journals - see below
customer CustomerRef see below
     
page integer Requested page number
hasNext Boolean True when this is not the last page and other elements can be retrieved with page=<thisPage+1>

FinancialPeriod

Field Format Description
periodId integer DataShare internal unique ID
startDate Date Start date of the financial period in the format “yyyy-mm-dd”
endDate Date End date of the financial period in the format “yyyy-mm-dd”

CustomerRef

Field Format Description
customerId String DataShare internal unique ID
code String Customer/Supplier code
name String Customer/Supplier name

Allocation

Field Format Description
allocationDate Date Date when allocation was made
allocationValue Decimal Amount of this allocation, in foreign currency
baseValue Decimal Amount of this allocation, in accounting package currency
items ReceivableItemRef Reference to another sale or purchase item - see below

ReceivableItemRef

Field Format Description
itemId String DataShare internal unique ID
remotePk String Accounting package internal ID
baseValue Decimal Amount of this item, in accounting package currency
transactionValue Decimal Amount of this item, in foreign currency
currencyIso String Currency ISO code (3 chars)

Gl Link

Field Format Description
journalId String DataShare internal unique ID
remotePk String Accounting package internal ID
journalRef String Journal reference
baseValue String Amount in accounting package currency

Customers (Beta)

Request example

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/customers \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MDcwNzQsInVzZXJJZCI6NjI3LCJqdGkiOiIxNWM0NzU4Yi02OGQ3LTRlODAtOGMxMi1lNGNmOTJkMDAzMWYiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.Jo4kAt42gi5WUBDdgjAv2pJzHpsIXEr24lc7bJJ6tjo' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response

{
  "page": 0,
  "hasNext": true,
  "content": [
        {
             "customerId": "34",
             "code": "MAC001",
             "name": "Macolm Hall Associates",
             "contacts": [
                 {
                     "address1": "Macolm houise",
                     "address2": "malcolm street",
                     "address3": "gopdalming",
                     "townCity": null,
                     "stateCounty": "mac010",
                     "postZipCode": null,
                     "countryCode": "GBR",
                     "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                 },
                 {
                     "address1": null,
                     "address2": null,
                     "address3": null,
                     "townCity": null,
                     "stateCounty": null,
                     "postZipCode": null,
                     "countryCode": "GBR",
                     "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                 }
             ]
         }
    ]
}

The Customers endpoint will show the details for all customers on the accounting package. This will be used in conjunction with the Receivable Items endpoint matching the transaction to the customer details.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Page number to retrieve, starting at 0. Default is 0 query parameter
size Integer Optional Number of elements by page, might be restricted if too high. Default is 200 query parameter

The following elements are returned in the GET Customers response

Field Format Description
customerId String Internal unique identifier for the customer
code String Customer Code as exported from the accounting package
name String Customer Name as exported from the accounting package
contacts Contact[] List of contacts - see below
     
page integer Requested page number
hasNext Boolean True when this is not the last page and other elements can be retrieved with page=<thisPage+1>

Contact

Field Format Description
address1 String Address first line as exported from the accounting package
address2 String Address second line as exported from the accounting package
address3 String Address third line as exported from the accounting package
townCity String Town as exported from the accounting package
stateCounty String State/County as exported from the accounting package
postZipcode String Postcode/Zip code as exported from the accounting package
countryCode String Country ISO code (3 chars)
countryName String Country name as exported from the accounting package

Accounts Payable (JSON)

Overview

URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/payableItems
Methods Supported GET
URL https://api.{environment}.validis.com/v1/engagements/{engagementId}/suppliers
Methods Supported GET

These endpoints give you access to the Accounts Payable (AP) transactions and the associated suppliers from the accounting package. Although the data is standardised into a Validis defined format, the transactions are shown as close to the original data source as possible. This means as each package has different ways of handling scenarios, you will see the transactions as the accounting package has processed them.

Item types

ItemTypes are in a static list as follow:

Type Description
INVOICE Invoice
PAYMENT Payment
CREDIT_NOTE Credit note
DISCOUNT Discount
WRITE_OFF Write-off
REFUND Refund
CURRENCY_GAIN_LOSS Currency gain or loss
ADJUSTMENT Adjustment
BALANCE_FORWARD Balance carried forward

Payable Items (Beta)

Request example

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/payableItems?openItems=True&showLinks=True&showAllocations=True \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzk1MTUsInVzZXJJZCI6NjI3LCJqdGkiOiI0MzczODkxNy0xMzIyLTRjOWUtYjQxZi05NzZiNmQyYjYxMGMiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.q_EqXILOjvCkLeRlC3u_q5ypFPQaVrDyQtXGhZcj8MA' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response

{
    "page": 0,
    "hasNext": true,
    "content": [
        {
            "itemId": "96282",
            "itemType": "INVOICE",
            "documentId": "101/10",
            "contactDocumentId": "Shop - Jan Rent",
            "transactionDate": "2018-01-01",
            "transactionValue": 3221.84,
            "baseValue": 3221.84,
            "taxValue": 536.97,
            "currencyIso": "GBP",
            "exchangeRate": 1,
            "entryTimestamp": "2018-01-31T00:00:00",
            "entryUser": "MANAGER",
            "postingTimestamp": null,
            "postingUser": "MANAGER",
            "bankRec": "NOT_APPLICABLE",
            "vatRec": "RECONCILED",
            "holdFlag": null,
            "disputeFlag": null,
            "voidFlag": false,
            "reversalFlag": null,
            "reversalId": null,
            "modifiedTimestamp": null,
            "modifiedUser": null,
            "paymentMethod": null,
            "dueDate": "2018-01-31",
            "baseBalance": 0,
            "transactionBalance": 0,
            "financialPeriod": {
                "periodId": 201801,
                "startDate": "2018-01-01",
                "endDate": "2018-01-31"
            },
            "allocations": [
                {
                    "allocationDate": "2018-04-03",
                    "allocationValue": 3221.84,
                    "baseValue": 3221.84,
                    "items": [
                        {
                            "itemId": "97416",
                            "remotePk": "97416",
                            "baseValue": 10286.49,
                            "transactionValue": 10286.49,
                            "currencyIso": "GBP"
                        }
                    ]
                }
            ],
            "links": [
                {
                    "journalId": "96282",
                    "remotePk": "96282",
                    "journalRef": "96282"
                }
            ],
            "supplier": {
                "supplierId": "59",
                "code": "PLA001",
                "name": "Plana Centres plc",
                "contacts": [
                    {
                        "address1": "plana number",
                        "address2": "plana street",
                        "address3": "plana town",
                        "townCity": null,
                        "stateCounty": "abc123",
                        "postZipCode": null,
                        "countryCode": "ARE",
                        "countryName": "United Arab Emirates (the)"
                    },
                    {
                        "address1": null,
                        "address2": null,
                        "address3": null,
                        "townCity": null,
                        "stateCounty": null,
                        "postZipCode": null,
                        "countryCode": "ARE",
                        "countryName": "United Arab Emirates (the)"
                    }
                ]
            }
        }
    ]
}

The Payable Item endpoint will show the AP transactions from the accounting package. You can filter by periods, only showing open items, showing the links to the GL transactions that were created from the AP transactions and any associated AP Transactions that have been allocated to this transaction.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Page number to retrieve, starting at 0. Default is 0 query parameter
size Integer Optional Number of elements by page, might be restricted if too high. Default is 200 query parameter
fromPeriodId Integer Optional Select items within or later selected financial period query string parameter
toPeriodId Integer Optional Select items within or before selected financial period query string parameter
supplierId String Optional Internal identifier for the customer query string parameter
openItems Boolean Optional Filter out settle items to only return those that have a 0 balance. If false, the default, includes all items settled or not. query string parameter
itemtypes ItemType Optional Filter items by their type, comma separated query string parameter
showLinks Boolean Optional Add GL links array to the response query string parameter
showAllocations Boolean Optional Add allocation array to the response query string parameter
DisplayAbsolute Boolean Optional Default is True. Change to false to recieved signed data query string parameter

The following elements are returned in the GET Payable Items response

Field Format Description
itemId String Datashare internal unique ID
itemType String Type of Receivable/Purchase item
documentId String Invoice number from the accounting package
customerDocumentId String Customer external document reference or description of invoice
transactionDate Date Transaction date
financialPeriod FinancialPeriod see below
transactionValue Decimal Item amount in foreign currency
baseValue Decimal Item amount in accounting package currency
taxValue Decimal VAT value of the transaction
currencyIso String Currency ISO code (3 chars)
exchangeRate Decimal Currency exchange rate between local and foreign currencies
entryTimestamp Timestamp Date and time the transaction was first created on the system
entryUser String The user that created the entry on the accounting package
postingTimestamp Timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
postingUser String User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
dueDate Date Date payment is due for the transaction
bankRec String Indicator to show if the transaction has been reconciled with a bank account (not applicable, unreconciled or reconciled)
vatRec String Indicator to show if the transaction has been reconciled with a vat account (not applicable, unreconciled or reconciled)
holdFlag Boolean Indicator to show if the transaction has been set to be on hold
disputeFlag Boolean Indicator to show if the transaction has been set to be disputed
voidFlag Boolean Indicator to show if the transaction has been set to be voided
reversalFlag String Indicator to show if the transaction has been reversed (NO, REVERSED, or REVERSING)
reversalId String TransactionID of the reversal transaction
modifiedTimestamp Timestamp Time the transaction was last modified on the system (may be the same as the entry timestamp for certain accounting packages)
modifiedUser String User/Username who last modified the transaction (may be the same as the entry user for certain accounting packages)
paymentMethod String The payment method for the Transaction
dueDate Date Payment due date
allocations Allocation[] List of allocations with other items - see below
links GlLink[] Links to GL journals - see below
supplier SupplierRef see below
     
page integer Requested page number
hasNext Boolean True when this is not the last page and other elements can be retrieved with page=<thisPage+1>

FinancialPeriod

Field Format Description
periodId integer DataShare internal unique ID
startDate Date Start date of the financial period in the format “yyyy-mm-dd”
endDate Date End date of the financial period in the format “yyyy-mm-dd”

SupplierRef

Field Format Description
supplierId String DataShare internal unique ID
code String Customer/Supplier code
name String Customer/Supplier name

Allocation

Field Format Description
allocationDate Date Date when allocation was made
allocationValue Decimal Amount of this allocation, in foreign currency
baseValue Decimal Amount of this allocation, in accounting package currency
items ReceivableItemRef Reference to another sale or purchase item - see below

ReceivableItemRef

Field Format Description
itemId String Datashare internal unique ID
remotePk String Accounting package internal ID
baseValue Decimal Amount of this item, in accounting package currency
transactionValue Decimal Amount of this item, in foreign currency
currencyIso String Currency ISO code (3 chars)

GlLink

Field Format Description
journalId String Datashare internal unique ID
remotePk String Accounting package internal ID
journalRef String Journal reference
baseValue String Amount in accounting package currency

Suppliers (Beta)

Example request for GET Suppliers

curl -X GET \
  https://api.sandbox.validis.com/v1/engagements/660/suppliers \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDQ0Mzk1MTUsInVzZXJJZCI6NjI3LCJqdGkiOiI0MzczODkxNy0xMzIyLTRjOWUtYjQxZi05NzZiNmQyYjYxMGMiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.q_EqXILOjvCkLeRlC3u_q5ypFPQaVrDyQtXGhZcj8MA' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Suppliers

{
    "page": 0,
    "hasNext": true,
    "content": [
        {
            "supplierId": "9",
            "code": "BEN001",
            "name": "Benand Imports",
            "contacts": [
                {
                    "address1": "bernard number",
                    "address2": "bernard steet",
                    "address3": "bernard town",
                    "townCity": null,
                    "stateCounty": "ben urt 123",
                    "postZipCode": null,
                    "countryCode": "GBR",
                    "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                },
                {
                    "address1": null,
                    "address2": null,
                    "address3": null,
                    "townCity": null,
                    "stateCounty": null,
                    "postZipCode": null,
                    "countryCode": "GBR",
                    "countryName": "United Kingdom of Great Britain and Northern Ireland (the)"
                }
            ]
        }
    ]
}

The Supliers endpoint will show the details for all suppliers on the accounting package. This will be used in conjunction with the Payable Items endpoint matching the transaction to the customer details.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

Parameter Type Constraint Description Location
page Integer Optional Page number to retrieve, starting at 0. Default is 0 query parameter
size Integer Optional Number of elements by page, might be restricted if too high. Default is 200 query parameter

The following elements are returned in the GET Customers response

Field Format Description
supplierId String Internal unique identifier for the customer
code String Customer Code as exported from the accounting package
name String Customer Name as exported from the accounting package
contacts Contact[] List of contacts - see below
     
page integer Requested page number
hasNext Boolean True when this is not the last page and other elements can be retrieved with page=<thisPage+1>

Contact

Field Format Description
address1 String Address first line as exported from the accounting package
address2 String Address second line as exported from the accounting package
address3 String Address third line as exported from the accounting package
townCity String Town as exported from the accounting package
stateCounty String State/County as exported from the accounting package
postZipcode String Postcode/Zip code as exported from the accounting package
countryCode String Country ISO code (3 chars)
countryName String Country name as exported from the accounting package

Extracts (CSV)

Overview

URL https://api.{environment}.validis.com/v1/extracts/general-ledger/engagements/{engagementId}
Methods Supported GET
URL https://api.{environment}.validis.com/v1/extracts/accounts-receivable/engagements/{engagementId}
Methods Supported GET
URL https://api.{environment}.validis.com/v1/extracts/accounts-payable/engagements/{engagementId}
Methods Supported GET

These endpoints give you access to the General Ledger (GL) Accounts Receivable(AR) and Accounts Payable (AP) transactions and associated data from the accounting package in a zipped folder in CSV format. Although the data is standardised into a Validis defined format, the transactions are shown as close to the original data source as possible. This means as each package has different ways of handling scenarios, you will see the transactions as the accounting package has processed them. The customers and suppliers are shown in a seperate response as they are repeated throughout the transaction response.

General Ledger

Example request for GET Extract GL

curl -X GET \
  https://api.sandbox.validis.com/v1/extracts/general-ledger/engagements/660 \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MTY3NTAsInVzZXJJZCI6NjI3LCJqdGkiOiJiOWU5YjFlZC01YzE3LTRlYzMtYTU0OC1mYmUzNjU0ZGZmYzkiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.3HkitLHptGqr3SVxoBR988baonlRj-UvFd6aM_om0IQ' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Extract GL

{
    "fileUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdg.zip",
    "sasToken": "sig=%3BH6d40puWV7cXO2sJtjp1IHI%2BXMvCmaID%2BeC8AUjf9U%3D&se=2018-11-06T10%3A48%3A14Z&sv=2016-05-31&sp=rdl&sr=b",
    "fileAccessUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdg.zip?sig=%3BH6d40puWV7cXO2sJtjp1IHI%2BXMvCmaID%2BeC8AUjf9U%3D&se=2018-11-06T10%3A48%3A14Z&sv=2016-05-31&sp=rdl&sr=b"
}

The GL Extract will create a zipped folder at the time of upload to be downloaded at a later time. As this is already created it will be accessible when required, but any changes to the Chart of Accounts post the latest upload will not be reflected in this file. This will include all the data that has been set up for you (You are able to set the number of financial year’s data you would like to receive).

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Extract GL response

Field Format Description
fileUrl String Location of zip file
sasToken String Access token
fileAccessUrl String URI required to access file. This can be used to download the file directly.

GL Extract Zip Folder

The Zip folder will contain 4 CSV files as follows:

File Description
GL Transactions.csv General Ledger Transactions
GL Period Balances.csv General Ledger Period Balances
GL Period Balances Summarised.csv General Ledger Period Balances summarised in the Validis chart of accounts
Company Details.csv Company Details for the SME that completed the upload

GL Transactions

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE Timestamps Date the data was uploaded to Validis
GL_TX_ID Number Unique identifier for the GL Transaction (to link to original AR or AP Transaction)
ACCOUNT_ID Number Unique identifier for the Account
ACCOUNT_CODE string Code of the account as exported from the accounting package
ACCOUNT_NAME string Name of the account as exported from the accounting package
PRIMARY_CATEGORY_CODE string Validis defined [category] (#primary_category) (Validis Chart of Accounts)
PRIMARY_CATEGORY string Validis defined [category name] (#primary_category) (Validis Chart of Accounts)
TAG_CODE string Validis defined [tag] (#tags) (Validis Chart of Accounts)
SHEET_ID Number Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET string Type of account name
JOURNAL_ID string Transaction number / Journal number
TRANSACTION_DATE date Transaction / Document date of the transaction
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
PERIOD_ID number Validis defined financial period ID
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
HEADER_DESCRIPTION string General ledger transaction narrative/description
HEADER_TIMESTAMP timestamp Time the transaction was posted on the system
HEADER_ENTRY_USER string User/Username who created the transaction
POSTING_TIMESTAMP timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER string User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
HEADER_SOURCE string Transaction type held within the general ledger
MODIFIED_TIMESTAMP timestamp Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER string User/Username who last modified on the system (only applies to certain accounting packages)
REMOTE_PK string Validis internal keys only - used for joining tables
LINE_SOURCE string Transaction type stored at the line level
LINE_DESCRIPTION string General ledger transaction additional narrative, reference fields
BASE_VALUE decimal Transaction amount in base currency (base currency set in accounting package)
TRANSACTION_VALUE decimal Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_CURRENCY string Transaction currency ISO code (3 chars)
TRANSACTION_EXCHANGE_RATE decimal Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
REPORTING_VALUE decimal Reporting amount in reporting currency (if reporting currency is different to base currency – only applies to certain accounting packages)
REPORTING_CURRENCY string Reporting currency ISO code (3 chars) (if reporting currency is different to base currency – only applies to certain accounting packages)
REPORTING_EXCHANGE_RATE decimal Reporting exchange rate calculated from REPORTING_VALUE/BASE VALUE (if reporting currency is different to base currency – only applies to certain accounting packages)

GL Period Balances

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
ACCOUNT_ID number Unique identifier for the Account
ACCOUNT_CODE string Code of the account as exported from the accounting package
ACCOUNT_NAME string Name of the account as exported from the accounting package
PRIMARY_CATEGORY_CODE string Validis defined [category] (#primary_category) code (Validis Chart of Accounts)
PRIMARY_CATEGORY string Validis defined [category name] (#primary_category) (Validis Chart of Accounts)
TAG_CODE string Validis defined [tag] (#tags) (Validis Chart of Accounts)
SHEET_ID number Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET string Type of account name
CURRENCY_CODE string currency ISO code (3 chars)
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
OPENING decimal Opening balance for the Validis defined PERIOD_ID
CLOSING decimal Closing balance for the Validis defined PERIOD_ID
CREDITS decimal Total credits for the Validis defined PERIOD_ID
DEBITS decimal Total debits for the Validis defined PERIOD_ID

GL Period Balances Summarised

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
PRIMARY_CATEGORY_CODE string Validis defined [category] (#primary_category) code (Validis Chart of Accounts)
PRIMARY_CATEGORY string Validis defined [category name] (#primary_category) (Validis Chart of Accounts)
TAG_CODE string Validis defined [tag] (#tags) (Validis Chart of Accounts)
SHEET_ID number Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET string Type of account name
CURRENCY_CODE string currency ISO code (3 chars)
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
OPENING decimal Opening balance for the Validis defined PERIOD_ID
CLOSING decimal Closing balance for the Validis defined PERIOD_ID
CREDITS decimal Total credits for the Validis defined PERIOD_ID
DEBITS decimal Total debits for the Validis defined PERIOD_ID

Company Details

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
ADDRESS_1 string Address first line as exported from the accounting package
ADDRESS_2 string Address second line as exported from the accounting package
ADDRESS_3 string Address third line as exported from the accounting package
TOWN_CITY string Town as exported from the accounting package
STATE_COUNTY string State/County as exported from the accounting package
POST_ZIPCODE string Postcode/Zip code as exported from the accounting package
COUNTRY_CODE string Country ISO code (3 chars)
COUNTRY_NAME string Country name as exported from the accounting package
CURRENCY_CODE string Currency ISO code (3 chars) for Base currency

Accounts Receivable

Example request for GET Extract AR

curl -X GET \
  https://api.sandbox.validis.com/v1/extracts/accounts-receivable/engagements/660 \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MTY3NTAsInVzZXJJZCI6NjI3LCJqdGkiOiJiOWU5YjFlZC01YzE3LTRlYzMtYTU0OC1mYmUzNjU0ZGZmYzkiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.3HkitLHptGqr3SVxoBR988baonlRj-UvFd6aM_om0IQ' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Extract AR

{
    "fileUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdr.zip",
    "sasToken": "sig=%5FtfEl4gNdOUWFL2Ia1zsL4gYkqAq8r2owXOLeVK6Ojw%3D&se=2018-11-06T10%3A48%3A16Z&sv=2016-05-31&sp=rdl&sr=b",
    "fileAccessUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdr.zip?sig=%5FtfEl4gNdOUWFL2Ia1zsL4gYkqAq8r2owXOLeVK6Ojw%3D&se=2018-11-06T10%3A48%3A16Z&sv=2016-05-31&sp=rdl&sr=b"
}

The AR Extract will create a zipped folder at the time of upload to be downloaded at a later time. This will include all the data that has been set up for you (You are able to set the number of financial year’s data you would like to receive). The AR Links file will link the AR transactions to allocated AR Transactions. The AR GL Links file will link the AR transactions to the associated GL transactions.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Extract AR response

Field Format Description
fileUrl String Location of zip file
sasToken String Access token
fileAccessUrl String URI required to access file. This can be used to download the file directly.

AR Extract Zip Folder

The Zip folder will contain 5 CSV files as follows:

File Description
AR Transactions.csv Accounts Receivable Transactions
AR Period Balances.csv Accounts Receivable Period Balances
AR Customer Master.csv Debtor details
AR Links Accounts Receivable transactions links
AR GL Links Accounts Receivable transactions links to the associated General Ledger transactions

AR Transactions

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
SALES_TX_ID number Internal ID
REMOTE_PK string Validis internal keys only - used for joining tables
TRANSACTION_TYPE_ID number Type of transactions, list subject to increase: 0 Invoice 1 Payment 2 Credit Note 3 Discount 4 Write off 5 Refund 6 Currency Gain Loss 7 Journal Adjustment 8 Balance Forward
TRANSACTION_TYPE_NAME string Indicative name for the type (see above)
DOCUMENT_ID string Invoice number from the accounting package
CUSTOMER_DOCUMENT_ID string Customer external document reference or description of invoice
CUSTOMER_ID number Internal identifier for the customer
CUSTOMER_CODE string Customer Code as exported from the accounting package
CUSTOMER_NAME string Customer Name as exported from the accounting package
TRANSACTION_DATE date Transaction / Document date of the transaction
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
TRANSACTION_VALUE decimal Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_BALANCE decimal Outstanding amount in the foreign currency at time of the upload
BASE_VALUE decimal Transaction amount in base currency (base currency set in accounting package)
BASE_BALANCE decimal Outstanding amount in the local currency at time of the upload
TAX_VALUE decimal VAT value of the transaction
CURRENCY_CODE string currency ISO code (3 chars)
EXCHANGE_RATE decimal Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
ENTRY_TIMESTAMP timestamp Date and time the transaction was first created on the system
ENTRY_USER string The user that created the entry on the accounting package
POSTING_TIMESTAMP timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER string User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
DUE_DATE date Date payment is due for the transaction
SETTLED_TIMESTAMP timestamp Date from which outstanding balance become zero
BANK_REC number Code: 0 not applicable 1 unreconciled 2 reconciled
VAT_REC number Code: 0 not applicable 1 unreconciled 2 reconciled
HOLD_FLAG boolean Hold transaction identifier (only applies to certain accounting packages)
DISPUTE_FLAG boolean Disputed transaction identifier (only applies to certain accounting packages)
VOID_FLAG boolean Voided transaction identifier (only applies to certain accounting packages)
REVERSAL_FLAG number Code: 0 no 1 reversed 2 reversing
REVERSAL_ID number Reversal transaction identifier (only applies to certain accounting packages)
MODIFIED_TIMESTAMP timestamp Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER string User/Username who last modified on the system (only applies to certain accounting packages)
PAYMENT_METHOD number Code: 0 cash 1 cheque 2 credit card 3 debit card 4 credit note 5 draft 6 electronic transfer 7 giro 8 intercompany transfer

AR Period Balances

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
SALES_PERIOD_ID number Internal ID
CUSTOMER_ID number Internal identifier for the customer
CUSTOMER_CODE string Customer Code as exported from the accounting package
CUSTOMER_NAME string Customer Name as exported from the accounting package
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
OPENING decimal Opening balance for the Validis defined PERIOD_ID
CLOSING decimal Closing balance for the Validis defined PERIOD_ID

AR Customer Master

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
CUSTOMER_ID number Internal identifier for the customer
CUSTOMER_CODE string Customer Code as exported from the accounting package
CUSTOMER_NAME string Customer Name as exported from the accounting package
REMOTE_PK string Validis internal keys only - used for joining tables
ADDRESS_1 string Address first line as exported from the accounting package
ADDRESS_2 string Address second line as exported from the accounting package
ADDRESS_3 string Address third line as exported from the accounting package
TOWN_CITY string Town as exported from the accounting package
STATE_COUNTY string State/County as exported from the accounting package
POST_ZIPCODE string Postcode/Zip code as exported from the accounting package
COUNTRY_CODE string Country ISO code (3 chars)
COUNTRY_NAME string Country name as exported from the accounting package
Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
LINK_ID number Unique identifier for the link
REMOTE_PK string Validis internal keys only - used for joining tables
ITEM1_ID number First SALES_TX_ID that is being linked
ITEM2_ID number Second SALES_TX_ID that is being linked
TRANSACTION_VALUE decimal Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
BASE_VALUE decimal Amount in local currency
LINK_DATE timestamp Date the link was made in the accounting package
Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
ID number Unique identifier for the link
SALES_TX_ID number Validis internal keys only - used for joining tables
GL_TX_ID number First SALES_TX_ID that is being linked

Accounts Payable

Example request for GET Extract AP

curl -X GET \
  https://api.sandbox.validis.com/v1/extracts/accounts-payable/engagements/660 \
  -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXNlbGxlcklkIjoiN2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2IiwiY2xpZW50SWQiOiJiZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDAiLCJwZXJtaXNzaW9ucyI6WyJMRjZVWDQiLCI4RjI0UFAiLCI5QzJET1AiLCIzRjk5NzIiLCJCQjNBQjAiLCI0NUVCMEEiLCJaVVFSWDAiLCJGRjc0NTEiLCIxQkU2NjQiXSwicm9sZXMiOlsiY2xpZW50LmFwaSJdLCJleHAiOjE1NDE0MTY3NTAsInVzZXJJZCI6NjI3LCJqdGkiOiJiOWU5YjFlZC01YzE3LTRlYzMtYTU0OC1mYmUzNjU0ZGZmYzkiLCJjbGllbnRfaWQiOiJ2YXBpIiwidXNlcm5hbWUiOiJBcGlLZXlEdG8oa2V5PTJhNzQ3Y2RlNGEyOTQ1M2I4MmJkMGE1ZTY5NDZiNjM1LCBjcmVhdGVkQXQ9MjAxOC0wNS0xMSAxMzoxNTo1Mi40MzQsIGNyZWF0ZWRCeT02MTcsIHVzZXJJZD02MjcsIHJlc2VsbGVySWQ9N2NjMGMyZjUtODkwOC00N2U1LThhMjMtZTI3NTc1ZDQ4NGM2LCBjbGllbnRJZD1iZmRhNDk5Ny0wMmQyLTRiMjktOWRiOC02MGIyZTNkODFiZDApIiwidmNvbm5lY3RDbGllbnRJZCI6ImJmZGE0OTk3LTAyZDItNGIyOS05ZGI4LTYwYjJlM2Q4MWJkMCJ9.3HkitLHptGqr3SVxoBR988baonlRj-UvFd6aM_om0IQ' \
  -H 'Ocp-Apim-Subscription-Key: {your api key}' \

Example successful response for GET Extract AP

{
    "fileUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdp.zip",
    "sasToken": "sig=8DKtBRH6aZRg7dcnRD5KzJRdzz4wEX0uqxp2V2dU340%3D&se=2018-11-06T10%3A48%3A18Z&sv=2016-05-31&sp=rdl&sr=b",
    "fileAccessUrl": "https://validemo1strg.blob.core.windows.net/extract-processed-upload/bfda4997-02d2-4b29-9db8-60b2e3d81bd0/013f8c93-75cb-4e37-a977-28b488c4e8cdp.zip?sig=8DKtBRH6aZRg7dcnRD5KzJRdzz4wEX0uqxp2V2dU340%3D&se=2018-11-06T10%3A48%3A18Z&sv=2016-05-31&sp=rdl&sr=b"
}

The AP Extract will create a zipped folder at the time of upload to be downloaded at a later time. This will include all the data that has been set up for you (You are able to set the number of financial year’s data you would like to receive). The AP Links file will link the AP transactions to allocated AP Transactions. The AP GL Links file will link the AP transactions to the associated GL transactions.

Required Parameters

Parameter Type Constraint Description Location
engagementId Integer Required The unique identifier for the Engagement Path
authorization String Required Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key String Required API Key fetched from vAdmin Header

Optional Parameters

There are no optional parameters for this endpoint.

The following elements are returned in the GET Extract AP response

Field Format Description
fileUrl String Location of zip file
sasToken String Access token
fileAccessUrl String URI required to access file. This can be used to download the file directly.

AP Extract Zip Folder

The Zip folder will contain 5 CSV files as follows:

File Description
AP Transactions.csv Accounts Payable Transactions
AP Period Balances.csv Accounts Payable Period Balances
AP Supplier Master.csv Creditor details
AP Links Accounts Payable transactions links
AP GL Links Accounts Payable transactions links to the associated General Ledger transactions

AP Transactions

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
PURCHASES_TX_ID number Internal ID
REMOTE_PK string Validis internal keys only - used for joining tables
TRANSACTION_TYPE_ID number Type of transactions, list subject to increase: 0 Invoice 1 Payment 2 Credit Note 3 Discount 4 Write off 5 Refund 6 Currency Gain Loss 7 Journal Adjustment 8 Balance Forward
TRANSACTION_TYPE_NAME string Indicative name for the type (see above)
DOCUMENT_ID string Invoice number from the accounting package
SUPPLIER_DOCUMENT_ID string Supplier external document reference
SUPPLIER_ID number Internal identifier for the supplier
SUPPLIER_CODE string Supplier Code as exported from the accounting package
SUPPLIER_NAME string Supplier Company Name as exported from the accounting package
TRANSACTION_DATE date Transaction / Document date of the transaction
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
TRANSACTION_VALUE decimal Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_BALANCE decimal Outstanding amount in the foreign currency at time of the upload
BASE_VALUE decimal Transaction amount in base currency (base currency set in accounting package)
BASE_BALANCE decimal Outstanding amount in the local currency at time of the upload
TAX_VALUE decimal VAT value of the transaction
CURRENCY_CODE string currency ISO code (3 chars)
EXCHANGE_RATE decimal Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
ENTRY_TIMESTAMP timestamp Date and time the transaction was first created on the system
ENTRY_USER string The user that created the entry on the accounting package
POSTING_TIMESTAMP timestamp Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER string User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
DUE_DATE date Date payment is due for the transaction
SETTLED_TIMESTAMP timestamp Date from which outstanding balance become zero
BANK_REC number Code: 0 not applicable 1 unreconciled 2 reconciled
VAT_REC number Code: 0 not applicable 1 unreconciled 2 reconciled
HOLD_FLAG boolean Hold transaction identifier (only applies to certain accounting packages)
DISPUTE_FLAG boolean Disputed transaction identifier (only applies to certain accounting packages)
VOID_FLAG boolean Voided transaction identifier (only applies to certain accounting packages)
REVERSAL_FLAG number Code: 0 no 1 reversed 2 reversing
REVERSAL_ID number Reversal transaction identifier (only applies to certain accounting packages)
MODIFIED_TIMESTAMP timestamp Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER string User/Username who last modified on the system (only applies to certain accounting packages)
PAYMENT_METHOD number Code: 0 cash 1 cheque 2 credit card 3 debit card 4 credit note 5 draft 6 electronic transfer 7 giro 8 intercompany transfer

AP Period Balances

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
SALES_PERIOD_ID number Internal ID
SUPPLIER_ID number Internal identifier for the supplier
SUPPLIER_CODE string Supplier Code as exported from the accounting package
SUPPLIER_NAME string Supplier Company Name as exported from the accounting package
PERIOD_ID number Validis defined financial period ID
FINANCIAL_YEAR_NAME string Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME string Financial period name as exported from the accounting package
PERIOD_START_DATE date Validis period start date
PERIOD_END_DATE date Validis period end date
OPENING decimal Opening balance for the Validis defined PERIOD_ID
CLOSING decimal Closing balance for the Validis defined PERIOD_ID

AR Supplier Master

Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
COMPANY_NAME string Company Name as exported from the accounting package
UPLOAD_DATE timestamp Date the data was uploaded to Validis
SUPPLIER_ID number Internal identifier for the supplier
SUPPLIER_CODE string Supplier Code as exported from the accounting package
SUPPLIER_NAME string Supplier Company Name as exported from the accounting package
REMOTE_PK string Validis internal keys only - used for joining tables
ADDRESS_1 string Address first line as exported from the accounting package
ADDRESS_2 string Address second line as exported from the accounting package
ADDRESS_3 string Address third line as exported from the accounting package
TOWN_CITY string Town as exported from the accounting package
STATE_COUNTY string State/County as exported from the accounting package
POST_ZIPCODE string Postcode/Zip code as exported from the accounting package
COUNTRY_CODE string Country ISO code (3 chars)
COUNTRY_NAME string Country name as exported from the accounting package
Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
LINK_ID number Unique identifier for the link
REMOTE_PK string Validis internal keys only - used for joining tables
ITEM1_ID number First PURCHASES_TX_ID that is being linked
ITEM2_ID number Second PURCHASES_TX_ID that is being linked
TRANSACTION_VALUE decimal Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
BASE_VALUE decimal Amount in local currency
LINK_DATE timestamp Date the link was made in the accounting package
Field Type Description
UPLOAD_ID UUID Unique identifier for the upload
ID number Unique identifier for the link
PUCHASES_TX_ID number Validis internal keys only - used for joining tables
GL_TX_ID number First SALES_TX_ID that is being linked

FAQS

Q: How to I perform end to end testing with XERO?

A: For XERO partner, please provide us with your keys and secret so that we can set it up on your database. If you are not a XERO partner, we can support you to obtain XERO partnership, as we have direct links to the XERO team.

For XERO Public, please create a XERO app. NOTE all finance companies must register for XERO partner before they are live.

Q: How to I perform end to end testing with Sage 50?

A: You will need to download a Sage 50 free trial and restore an anomymised backup that we provide.

Q: How to I perform end to end testing with Quickbooks Online?

A: You will need to obtain a Quickbooks Online Sandbox and we will provide a connector to facilitate testing.

Q: How does lastUploadDate Work?

A: lastUploadDate is a timestamp (seconds from 1970) and is only available if there were a last upload.

Q: Can we get a time estimation at the start of the data upload process, so we can communicate to the user when we expect to have their accounting data?

A: The Webhook can only provide loading statuses e.g. Loading, Aborted, Processing, Failed, Or Completed.

 

Q: If I have to use the periods do you have an easy way to identify the companies year end/start date?

A: The Get Periods endpoint can provide this information (https://developer.validis.com/#get-periods) as long as it is set in the source accounting package.

Useful Information

Types

The following types will be shown in the API responses:

Type Description Value type
Label This is a name of the value. It will include the key and display value for the element. Both the key and display value will be Strings.
Amount This is a numeric value. It will include the value and an indicator Integer
Percentage This is a percentage value. The format of the value will be the actual percentage, not a decimal value e.g. 0.5 is 0.5% and not 50% which is the decimal value. Decimal
Ratio This is a percentage value. The format of the value will be the decimal percentage, not the actual value e.g. 0.5 is 50% and not 0.5% which is the decimal value. Decimal

Validis Chart of Account

As part of the normalisation process, DataShare maps the general ledger accounts to the Validis Chart of Accounts (CoA). The CoA comprises of Primary Categories and Tags.

Primary Category

Each general ledger account is associated to a primary category allowing to identify its position within Income Statement or Balance Sheet reports. There are 8 Primary Categories which are divided into the ones included in the Income Statement and Balance Sheet:

Income Statement (Profit and Loss):

Primary Category Primary Category Description
SALES Revenue
COST_OF_SALES Cost of Revenue
OPERATING_EXPENSES Expenses

Balance Sheet:

Primary Category Primary Category Description
FIXED_ASSETS Non Current Assets
CURRENT_ASSETS Current Assets
CURRENT_LIABILITIES Current Liabilities
LONG_TERM_LIABILITIES Non Current Liabilities
CAPITAL_AND_RESERVES Capital & Reserves

Tags

Each general ledger account is associated with a tag allowing to identify it and present more granular reports. Here is a list of tags and their associated Primary categories that are used:

Primary Category Tag
Primary Category Tag
SALES CONTRIBUTION_REVENUES
SALES GRANT_REVENUES
SALES IN_KIND_REVENUES
SALES PROGRAM_REVENUES
SALES RENTAL_INCOME
SALES SALES_TAG
COST_OF_SALES COST_OF_SALES_DEPRECIATION
COST_OF_SALES OTHER_DIRECT_LABOUR
COST_OF_SALES DIRECTORS_DIRECT_LABOUR
COST_OF_SALES EMPLOYEE_BENEFITS
COST_OF_SALES IN_KIND_EXPENSES
COST_OF_SALES OTHER_COST_OF_SALES
COST_OF_SALES PAYROLL_TAXES
OPERATING_EXPENSES PL_AMORTISATION
OPERATING_EXPENSES BAD_DEBTS
OPERATING_EXPENSES CORPORATE_TAX
OPERATING_EXPENSES DEPRECIATION
OPERATING_EXPENSES DIRECTORS_REMUNERATION
OPERATING_EXPENSES DISPOSAL
OPERATING_EXPENSES DIVIDENDS
OPERATING_EXPENSES EMPLOYEE_BENEFITS
OPERATING_EXPENSES EXCHANGE_DIFFERENCES
OPERATING_EXPENSES BANK_CHARGES_AND_INTEREST
OPERATING_EXPENSES IN_KIND_EXPENSES
OPERATING_EXPENSES INTEREST_RECEIVABLE
OPERATING_EXPENSES PL_IMPAIRMENT
OPERATING_EXPENSES INVESTMENT_INCOME
OPERATING_EXPENSES OTHER_INCOME
OPERATING_EXPENSES OCCUPANCY_COSTS
OPERATING_EXPENSES OTHER_OPERATING_EXPENSES_TAG
OPERATING_EXPENSES OTHER_GROSS_WAGES
OPERATING_EXPENSES PAYROLL_TAXES
OPERATING_EXPENSES PROFESSIONAL_FEES
OPERATING_EXPENSES REPAIRS_AND_MAINTENANCE
OPERATING_EXPENSES RESEARCH_AND_DEVELOPMENT
OPERATING_EXPENSES SALES_AND_MARKETING
OPERATING_EXPENSES SUSPENSE_AND_MISPOSTINGS
OPERATING_EXPENSES TELECOMMUNICATIONS
OPERATING_EXPENSES UTILITIES
FIXED_ASSETS CONTRIBUTIONS_RECEIVABLE
FIXED_ASSETS DEFERRED_TAX_ASSETS_LONG_TERM
FIXED_ASSETS GOODWILL_ASSETS_COST
FIXED_ASSETS GOODWILL_ASSETS_AMORT
FIXED_ASSETS GRANTS_RECEIVABLE
FIXED_ASSETS CORPORATION_TAX_DUE
FIXED_ASSETS INVESTMENT_ASSETS_COST
FIXED_ASSETS INVESTMENT_ASSETS_DEPR
FIXED_ASSETS LAND_AND_BUILDING_COST
FIXED_ASSETS LAND_AND_BUILDING_DEP
FIXED_ASSETS OTHER_INTANGIBLE_ASSETS_AMORT
FIXED_ASSETS OTHER_INTANGIBLE_ASSETS_COST
FIXED_ASSETS TANGIBLE_ASSETS_COST
FIXED_ASSETS TANGIBLE_ASSETS_DEPR
FIXED_ASSETS PLANT_AND_MACHINERY_COST
FIXED_ASSETS PLANT_AND_MACHINERY_DEP
FIXED_ASSETS PROGRAM_REVENUES_RECEIVABLE
FIXED_ASSETS RELATED_COMPANY_BALANCES
CURRENT_ASSETS DEBTORS_CONTROL
CURRENT_ASSETS BAD_DEBT_PROVISION
CURRENT_ASSETS BANK_LOANS_SHORT_TERM
CURRENT_ASSETS BANK_ACCOUNT
CURRENT_ASSETS CONTRIBUTIONS_RECEIVABLE
CURRENT_ASSETS DEFERRED_TAX_ASSETS_SHORT_TERM
CURRENT_ASSETS DIRECTORS_LOANS_SHORT_TERM
CURRENT_ASSETS GRANTS_RECEIVABLE
CURRENT_ASSETS CORPORATION_TAX_DUE
CURRENT_ASSETS CURRENT_ASSETS_STOCK
CURRENT_ASSETS RAW_MATERIALS
CURRENT_ASSETS INVESTMENT_ASSETS_SHORT_TERM_COST
CURRENT_ASSETS INVESTMENT_ASSETS_SHORT_TERM_DEPR
CURRENT_ASSETS NET_VAT_LIABILITY
CURRENT_ASSETS OTHER_CURRENT_ASSETS_TAG
CURRENT_ASSETS OTHER_LOANS_SHORT_TERM
CURRENT_ASSETS DEBTORS_OTHER
CURRENT_ASSETS PAYE_OUTSTANDING
CURRENT_ASSETS PREPAYMENTS
CURRENT_ASSETS PROGRAM_REVENUES_RECEIVABLE
CURRENT_ASSETS RELATED_COMPANY_BALANCES
CURRENT_ASSETS SUSPENSE_AND_MISPOSTINGS
CURRENT_LIABILITIES CREDITORS_CONTROL
CURRENT_LIABILITIES ACCRUALS
CURRENT_LIABILITIES BAD_DEBT_PROVISION
CURRENT_LIABILITIES BANK_LOANS_SHORT_TERM
CURRENT_LIABILITIES BANK_ACCOUNT
CURRENT_LIABILITIES CONTRIBUTIONS_RECEIVABLE
CURRENT_LIABILITIES DEFERRED_TAX_LIABILITIES_SHORT_TERM
CURRENT_LIABILITIES DIRECTORS_LOANS_SHORT_TERM
CURRENT_LIABILITIES DIVIDENDS_DUE
CURRENT_LIABILITIES GRANTS_RECEIVABLE
CURRENT_LIABILITIES HIRE_PURCHASE_SHORT_TERM
CURRENT_LIABILITIES CORPORATION_TAX_DUE
CURRENT_LIABILITIES LEASES_SHORT_TERM
CURRENT_LIABILITIES NET_VAT_LIABILITY
CURRENT_LIABILITIES OTHER_CAPITAL_OBLIGATIONS_SHORT_TERM
CURRENT_LIABILITIES OTHER_CURRENT_LIABILITIES_TAG
CURRENT_LIABILITIES OTHER_LOANS_SHORT_TERM
CURRENT_LIABILITIES CREDITORS_OTHER
CURRENT_LIABILITIES PAYE_OUTSTANDING
CURRENT_LIABILITIES PROGRAM_REVENUES_RECEIVABLE
CURRENT_LIABILITIES RELATED_COMPANY_BALANCES
CURRENT_LIABILITIES SUSPENSE_AND_MISPOSTINGS
LONG_TERM_LIABILITIES BANK_LOANS_LONG_TERM
LONG_TERM_LIABILITIES CONTRIBUTIONS_RECEIVABLE
LONG_TERM_LIABILITIES DEFERRED_TAX_LIABILITIES_LONG_TERM
LONG_TERM_LIABILITIES DIRECTORS_LOANS_LONG_TERM
LONG_TERM_LIABILITIES GRANTS_RECEIVABLE
LONG_TERM_LIABILITIES HIRE_PURCHASE
LONG_TERM_LIABILITIES CORPORATION_TAX_DUE
LONG_TERM_LIABILITIES LEASES
LONG_TERM_LIABILITIES OTHER_CAPITAL_OBLIGATIONS_LONG_TERM
LONG_TERM_LIABILITIES OTHER_LOANS_LONG_TERM
LONG_TERM_LIABILITIES OTHER_LONG_TERM_LIABILITIES_TAG
LONG_TERM_LIABILITIES PROGRAM_REVENUES_RECEIVABLE
LONG_TERM_LIABILITIES RELATED_COMPANY_BALANCES
CAPITAL_AND_RESERVES SHARE_CAPITAL
CAPITAL_AND_RESERVES DIVIDENDS_BS
CAPITAL_AND_RESERVES DRAWINGS
CAPITAL_AND_RESERVES CORPORATE_TAX_BS
CAPITAL_AND_RESERVES OTHER_RESERVES
CAPITAL_AND_RESERVES PREFERENCE_SHARE_CAPITAL
CAPITAL_AND_RESERVES RETAINED_EARNINGS
CAPITAL_AND_RESERVES REVALUATION_RESERVE
CAPITAL_AND_RESERVES SUSPENSE_AND_MISPOSTINGS

Activity Diagrams

Get API Key

Purpose: obtain API Key that is required for all queries in Ocp-Apim-Subscription-Key header, and to authenticate

Requirements: having a client provisioned and being a system admin for it

Get API Key

Authenticate

Purpose: obtain an access token (JWT) that will be required on all other call in Authorization header

Requirements: valid API Key

Authenticate

Get Engagement Id

Purpose: obtain and select engagement IDs that will be required to get financial data and reports

Requirements: authenticated and have the client id

Get Engagement Id

Upload API

Purpose: create an engagement which represent the relation between the client, and the SME (represented by contacts)

Requirements: authenticated and have the client id

Upload API

Initiate an upload

Purpose: initiate an upload for an online or offline package

Requirements: authenticated and have the engagement id

Initiate an Upload

Upload Tracking

Purpose: track uploads, or being notified when an upload has completed (successfully, or with an error)

Requirements: authenticated and have the client id

Pull Option

Pull Option

Notification Option

Notification Option

Access Financial Reports

Purpose: Get reports (income statement, balance sheet, or financial snapshot) of an SME

Requirements: authenticated and have the engagement id

Access Financial Reports

Access CSV Extracts

Purpose: Get a full or subset of uploaded financial data (available: general ledger, accounts receivable, or accounts payable)

Requirements: authenticated and have the engagement id

Access CSV Extracts

DataShare Postman Scripts

We offer Postman Scripts to help you start integrating with the DataShare APIs. Postman is a REST client that provides an intuitive user interface to send requests, save responses, add tests, and create workflows.

Download the Scripts and the Environment Variables to get started, all you need to do is add your API key to the variables and you are started!

Postman files to download

Quick guide to getting started with Postman.

1. If you do not have Postman, download it from here and install it.

2. Open Postman and add the postman collection and environment.

To add the collection, clink on the Import button in the top left corner.

Import Postman Collection

Click on the Choose Files button and select the postman collection and environment file you downloaded earlier.

Import Choose Files

3. Add in the API key to the environment variables.

Click on the Manage Environments button and select the Environment you have just added. Add your API key to the datashareApiKey Current Value

Environment Add API Key

4. Authenticate with the Authenticatation endpoint. This will input the clientId and the JWT Token and will allow you use any of the other endpoints.