Hero

API Docs

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

Uploading Data

Overview

To upload data, a record to store the data needs to be created, this is called an engagement in DataShare. The engagement stores the most recent successful upload, and allows you to add your own reference called an externalEngagementId.

Common Parameters

Required Parameters

Parameter Description Location
authorization
string
Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key
string
API Key fetched from DataShare Admin Header

Creating a Engagement

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.

POST v1/clients/{clientId}/engagements

Required Parameters

Parameter Description Location
clientId
UUID
The unique identifier of your DataShare system, as provided by the Authentication endpoint Path
sme_Name
string
The name of the Engagement for the request Body

Optional Parameters

Parameter Description Location
externalEngagementId
string
External system client Identifier Body
usePortal
boolean
Default is false, when true an SME Contact is created with the provided First Name, Last Name, Email Address Path
usePassthrough
boolean
Default is false, when true an SME Contact is created with the provided First Body


curl -X POST \
https://api.{environment}.validis.com/v1/clients/{clientId}/engagements \
-H 'Authorization: Bearer {authorization} \
-H 'Content-Type: application/json' \
-H 'Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}' \
-d '{ 
"sme": { 
    "name": "Example Customer 2"
    },
"externalEngagementId": "Example2",
"usePassthrough":"false"
}'


The following elements are returned in the POST Engagements response

Field Description
Id
string
The unique identifier for the user/engagement
externalEngagementId
string
External system engagement identifier
clientId
UUID
The unique identifier of your DataShare system, as provided by the Authentication endpoint
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
boolean
Indicator to show if they are able to use the reconciliation module

Reviewing Connectors

This endpoint shows the available accounting packages for extraction, and their applicable scope.

GET v1/clients/{clientId}/connectors

Required Parameters

Parameter Description Location
clientId
UUID
The unique identifier of your DataShare system, as provided by the Authentication endpoint Path


curl -X GET \
  https://api.{environment}.validis.com/v1/clients/{clientId}/connectors 
  -H 'Authorization: bearer {authorization}' \
  -H 'Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}' \     


The following elements are returned in the GET Connectors response

Field Description
id
string
The Id of the connector
name
stringString
Code for the connector
description
string
Description of the connector version
type
string
0 Online connector, 1 Offline connector
title
string
Name of the connector
isRefreshable
boolean
Whether the connector can be used with the data refresh product
scopes
array
The type of data extraction available

Performing a Upload

This endpoint allows you to create an extractor to upload data.

POST /v1/engagements/{engagementId}/connectors/{connectorName}/upload

Required Parameters

Parameter Description Location
engagementId
integer
The unique identifier for the Client Path
connectorName
string
Accounting Package identifier Path

Optional Parameters

Parameter Description Location
scopeName
string
Choose whether to upload all the data or just the receivables and payables. Use ‘Full’ for all, ‘Collateral’ for receiveables and payables Path


curl -X POST \ 
  https://api.{environment}.validis.com/engagements/{engagementId}/
  connectors/{connectorName}/upload \
  -H 'Authorization: bearer {authorization}' \
  -H 'Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}' \  


The following elements are returned in the POST Upload response

Field 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.

Performing a Data Refresh

This endpoint allows you to pull the management accounts data from an online accounting package without customer involvement.

Required Parameters

Parameter Description Location
engagementId
integer
The unique identifier for the Client Path
connectorName
string
Accounting Package identifier Path


curl -X POST \ 
  https://api.{environment}.validis.com/engagements/{engagementId}/
  connectors/{connectorName}/refresh \
  -H 'Authorization: bearer {authorization}' \
  -H 'Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}' \  



The following elements are returned in the POST Upload response

Field Description
action
string
“No Action Required” where the request is successful
url
string
“null” where the request is successful

Scheduling an Upload

Data refresh can be scheduled in line with your contractual agreements, reducing the manual effort for your customers.

Parameter Description Location
clientId
UUID
The unique identifier of your DataShare system, as provided by the Authentication endpoint Path
engagementId
integer
The unique identifier for the Client Path
scheduleFrequency
string
0 - NOT_SCHEDULED, 1 - ANNUALLY, 2 - MONTHLY, 3 - WEEKLY, 4 - DAILY, 5 - QUARTERLY Body
scheduleStartDate
string
Date to start automated uploads Body


curl -X POST \ 
  https://api.{environment}.validis.com/v1/clients/
  /engagements//schedule \
  -H 'Authorization: bearer {authorization}' \
  -H 'Ocp-Apim-Subscription-Key: {Ocp-Apim-Subscription-Key}' \   


The following elements are returned in the POST Upload response

Field Description
action
string
“NO_ACTION_REQUIRED”
url
string
null