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 |