Meta Data
Overview
Meta Data sourced from during the upload process provides you with auditable information, and a log of events.
Common Parameters
Required Parameters
| 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 Engagement | Path |
authorization string |
Valid access token (JSON Web Token) | Header |
Ocp-Apim-Subscription-Key string |
API Key fetched from DataShare Admin | Header |
Reviewing Engagements
This endpoint allows you to 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.
GET /v1/clients/{clientId}/engagements
Optional Parameters
| Parameter | Description | Location |
|---|---|---|
externalEngagementId string |
Comma-separated list of externalEngagementIds | query string parameter |
page string |
Starting page (page numbering starts at 0) | query string parameter |
size Integer |
Size of each page | query string parameter |
orderBy string |
Comma-separated list of fields to sort by. Use -{field name} to sort in descending order | query string parameter |
curl -X GET \
https://api.{environment}.validis.com/v1/clients/{clientId}/engagements \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Engagements response
| Field | Description |
|---|---|
Id integer |
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 |
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 boolean |
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) |
dataRefreshEnabled boolean |
Indicator to show whether Data Refresh is activated on the engagement |
Retrieve Company Details
GET Company Details
The company details gives you details of the company uploading that is stored in the accounting package, such as the base currency.
GET /v1/engagements/{engagementId}/companyDetails
curl -X GET \
https://api.{environment}.validis.com/v1/engagements/
{engagementId}/companyDetails \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Company Details response
| Field | 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
This endpoint provides the financial periods as set in the accounting package. If they are not available, DataShare will create monthly periods. These periods may be used in returning information for reports etc. The periodIds are not consistent across accountancy package and may not be consistent between uploads.
GET /v1/engagements/{engagementId}/periods/
curl -X GET \
https://api.{environment}.validis.com/v1/engagements/
{engagementId}/periods \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Periods response
| Field | Description |
|---|---|
uploadId 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
This endpoint shows all the meta data information associated with the last upload for engagements.
The webhook is neccesary for an event driven workflow. Whereas Get Uploads is useful for batch processing.
GET /v1/engagements/{engagementId}/connectors/{connectorName}/uploads
Optional Parameters
| Parameter | Description | Location |
|---|---|---|
engagementId integer |
To filter the uploads for a Validis defined Engagement id (long) (Comma-separated list of ids) | query string parameter |
uploadId UUID |
To filter the details of a single upload using the Id of the upload | query string parameter |
createdDateFrom string |
To filter of all uploads that were created after the specified time (format is yyyy-mm-ddThh:mm:ss) | query string parameter |
createdDateTo string |
To filter of all uploads that were created after the specified time (format is yyyy-mm-ddThh:mm:ss) | query string parameter |
completedDateFrom string |
To filter of all uploads that were completed after the specified time (format is yyyy-mm-ddThh:mm:ss) | query string parameter |
completedDateTo string |
To filter of all uploads that were ```completed after the specified time (format is yyyy-mm-ddThh:mm:ss) | query string parameter |
page integer |
Starting page (page numbering starts at 0) | query string parameter |
size integer |
Size of each page | query string parameter |
orderBy string |
Comma-separated list of fields to sort by. Use -{field name} to sort in descending order. | query string parameter |
curl -X GET \
https://api.{environment}.validis.com/v1/clients/{clientId}/uploads \
-H 'Authorization: bearer {Your_Auth_Token}\
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Uploads response
| Field | Description |
|---|---|
uploadId UUID |
The Id of the upload |
uploadStatus string |
The status of the upload |
clientId UUID |
The unique identifier of your DataShare system, as provided by the Authentication endpoint |
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
This endpoint returns the last upload performed by an engagements.
GET v1/clients/{clientId}/lastUploads?engagementIds=
Required Parameters
| Parameter | Description | Location |
|---|---|---|
engagementIds integer |
To filter the uploads for a Validis defined Engagement id (long) (Comma-separated list of ids) | query string parameter |
Optional Parameters
| Parameter | Description | Location |
|---|---|---|
page integer |
Starting page (page numbering starts at 0) | query string parameter |
size integer |
Size of each page | query string parameter |
curl -X GET \
https://api.{environment}.validis.com/v1/clients/{clientId}/
lastUploads?engagementIds={engagementId(s)} \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Last Upload response
| Field | Description |
|---|---|
uploadId UUID |
The Id of the upload |
status string |
The status of the upload |
resellerId UUID |
The unique identifier of the reseller |
clientId UUID |
The unique identifier of your DataShare system, as provided by the Authentication endpoint |
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 |
Get Users
This endpoint returns a list of the users on your datashare instance.
GET v1/clients/{clientId}/users
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}/users \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Last Upload response
| Field | Description |
|---|---|
firstName string |
First name of the user |
lastName string |
Last name of the user |
email string |
Email of the user |
phone integer |
Phone of the user |
title string |
Title of the user |
resellerId string |
The unique identifier of the reseller |
profiles.id integer |
The Id of the role |
profiles.name string |
The name of the role |
profiles.description string |
The description of the role |
profiles.key string |
The key of the role |
ssoId string |
ID used for SSO |
id integer |
The unique id for |
status integer |
Status of user, 0 or 1 or 2 |
createdAt integer |
The time the user was created |
lastLoginDate integer |
The last login date |
statusCode string |
Status of user, ACTIVE or INVITING or DISABLED |
clientId uuid |
The unique identifier of your DataShare system |
resellerUuid uuid |
The unique identifier of the reseller |
clientUuid uuid |
The unique identifier of your DataShare system |
userType string |
Type of user SME or Client(Staff) |
Get Audit Workflow
This endpoint returns dataflow
GET v1/workflows/engagements/{engagementId}/uploads/{uploadId}
Required Parameters
| Parameter | Description | Location |
|---|---|---|
engagementId integer |
The unique identifier for the Engagement | Path |
uploadId integer |
The unique identifier for the upload | Path |
curl -X GET \
https://api.{environment}.validis.com/v1/workflows/engagements/
{engagementId}/uploads/{uploadId} \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
The following elements are returned in the GET Last Upload response
| Field | Description |
|---|---|
uploadId UUID |
The Id of the upload |
created datetime |
Date time of upload creation |
started datetime |
Date time of upload starting |
clientId UUID |
The unique identifier of your DataShare system, as provided by the Authentication endpoint |
engagementId integer |
The Id of the Engagement that defines the upload |
connector string |
The name of connector used for upload |
smeId integer |
The Id of the SME that has completed the upload |
userId integer |
The Id of the user that started the upload |
status string |
The status of the upload |
lastUpdate datetime |
Date time of last update of upload progression |
usePassthrough boolean |
Whether the upload was a passthrough upload |
steps.stepId integer |
The Id of the step |
steps.created datetime |
Date time of upload creation of the step |
steps.started datetime |
Date time of upload starting of the step |
steps.status string |
The status of the upload of the step |
steps.lastUpdate datetime |
Date time of last update of the step |
steps.name string |
Date time of last update of upload progression |
steps.sorting integer |
The step in the process |