Hero

API Docs

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

Accounts Receivable (JSON)

Overview

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.

Receivable Items

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.

GET v1/engagements/{engagementId}/receivableItems

Optional Parameters

Parameter Description Location
page
integer
Page number to retrieve, starting at 0. Default is 0 query parameter
size
integer
Number of elements by page. Default is 200. Max is 2000. query parameter
fromPeriodId
integer
Select items within or later selected financial period query string parameter
toPeriodId
integer
Select items within or before selected financial period query string parameter
customerId
Number
Internal identifier for the customer query string parameter
openItems
boolean
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
Filter items by their type, Comma-separated query string parameter
showLinks
boolean
Add GL links array to the response query string parameter
showAllocations
boolean
Add allocation array to the response query string parameter
DisplayAbsolute
boolean
Default is True. Change to false to recieved signed data query string parameter
curl -X GET \
  https://api.{environment}.validis.com/v1/engagements/{engagementId}/r
  eceivableItems?openItems=True&showLinks=True&showAllocations=True \
 -H 'Authorization: bearer {Your_Auth_Token} \
  -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \

The following elements are returned in the GET Receivable Items response

Field 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 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 Description
customerId
string
DataShare internal unique ID
code
string
Customer/Supplier code
name
string
Customer/Supplier name

ReceivableItemRef

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

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.

GET v1/engagements/{engagementId}/customers

Optional Parameters

Parameter Type Description Location
page
integer
Page number to retrieve, starting at 0. Default is 0 query parameter  
size
integer
Number of elements by page. Default is 200. Max is 2000. query parameter  
     curl -X GET \ 
     https://api.{environment}.validis.com/v1/engagements/{engagementId}/customers \ 
     -H 'Authorization: bearer {Your_Auth_Token} \ 
     -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

The following elements are returned in the GET Customers response

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

Accounts Payable (JSON)

Overview

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.

Payable Items

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.

v1/engagements/{engagementId}/payableItems

Optional Parameters

Parameter Description Location
page
integer
Page number to retrieve, starting at 0. Default is 0 query parameter
size
integer
Number of elements by page. Default is 200. Max is 2000. query parameter
fromPeriodId
integer
Select items within or later selected financial period query string parameter
toPeriodId
integer
Select items within or before selected financial period query string parameter
supplierId
string
Internal identifier for the customer query string parameter
openItems
boolean
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
Filter items by their type, Comma-separated query string parameter
showLinks
boolean
Add GL links array to the response query string parameter
showAllocations
boolean
Add allocation array to the response query string parameter
DisplayAbsolute
boolean
Default is True. Change to false to recieved signed data query string parameter
 curl -X GET \ 
   https://api.{environment}.validis.com/v1/engagements/{engagementId}/
   payableItems?openItems=True&showLinks=True&showAllocations=True \ 
   -H 'Authorization: bearer {Your_Auth_Token} \ 
   -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

The following elements are returned in the GET Payable Items response

Field 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 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 Description
supplierId
string
DataShare internal unique ID
code
string
Customer/Supplier code
name
string
Customer/Supplier name

ReceivableItemRef

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

Suppliers

The Suppliers 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.

v1/engagements/{engagementId}/suppliers

Optional Parameters

Parameter Description Location
page
integer
Page number to retrieve, starting at 0. Default is 0 query parameter
size
integer
Number of elements by page. Default is 200. Max is 2000. query parameter
 curl -X GET \ 
   https://api.{environment}.validis.com/v1/engagements/{engagementId}/suppliers \ 
   -H 'Authorization: bearer {Your_Auth_Token} \ 
   -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

The following elements are returned in the GET Customers response

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

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

Common Data Structures

Allocation

Field 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

Contact

Field 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

GlLink

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

Range

Field 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