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 |