Hero

API Docs

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

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