General Ledger (JSON)
Overview
These endpoints give you access to the General Ledger (GL) transactions 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.
Accounts
The GL Accounts endpoint gives you the mapping between the accounting packages accounts and how they map to the Validis defined Chart of Accounts (CoA).
v1/engagements/{engagementId}/accounts
curl -X GET \
https://api.{environment}.validis.com/v1/engagements/{engagementId}/accounts \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
Optional Parameters
| Parameter | Type | Description | Location |
|---|---|---|---|
primaryCategories string |
Primary categories (Comma-separated) in which account must belongs | query parameter | |
tags string |
Tags (Comma-separated) in which account must belongs | query parameter | |
status Account Status |
Comma-separated list of Account Status | query parameter |
The following elements are returned in the GET GL Accounts response
| Field | Format | Description |
|---|---|---|
accountId string |
DataShare internal unique identifier | |
remotePk string |
Accounting package reference | |
code string |
Account code | |
name string |
Account name | |
primaryCategory string |
Validis defined [category] (#Primary_Category) (Validis Chart of Accounts) | |
tag string |
Validis defined [tag] (#tags) (Validis Chart of Accounts) | |
currencyIso string |
ISO code of account currency (3 chars) | |
createdTimestamp timestamp |
Time when account has been created | |
modifiedTimestamp timestamp |
Last time when account has been updated | |
status string |
The status of the account |
Account Summaries
The GL Accounts summaries endpoint gives you opening and closing balances, movement and the split between the debtis and credits for each account including the Validis defined Chart of Accounts (CoA) category and tag.
v1/engagements/{engagementId}/accountSummaries
curl -X GET \
https://api.{environment}.validis.com/v1/engagements/{engagementId}/
accountSummaries?ranges\
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
Required Parameters
| Parameter | Description | Location | |
|---|---|---|---|
ranges string |
Required | Starting and Ending Period Identifier separated by a colon (can be multiple ranges when Comma-separated). Can only have ranges or year and must have at least one stated. | query string parameter |
Optional Parameters
| Parameter | Description | Location |
|---|---|---|
primaryCategories string |
Primary categories (Comma-separated) in which account must belongs | query parameter |
tags string |
Tags (Comma-separated) in which account must belongs | query parameter |
status Account Status |
Comma-separated list of Account Status | query parameter |
The following elements are returned in the GET GL Account Summaries response
| Field | Description |
|---|---|
accountId string |
DataShare internal unique identifier |
code string |
Account code |
name string |
Account name |
primaryCategory string |
Validis defined [category] (#Primary_Category) (Validis Chart of Accounts) |
tag string |
Validis defined [tag] (#tags) (Validis Chart of Accounts) |
summaries summary |
see below |
Summary
| Field | Description |
|---|---|
range range |
See below |
debit decimal |
Sum of all debit transactions during the range |
credit decimal |
Sum of all credit transactions during the range |
movement decimal |
Sum of all transactions during the range |
openingBalance decimal |
Balance at the beginning of the range |
closingBalance decimal |
Balance at the end of the range |
Journals
The GL Journals endpoint will show the GL transactions from the accounting package and they will be associated with the Validis CoA. You can filter by periods or dates and types to access the transactions you require.
v1/engagements/{engagementId}/journals
curl -X GET \
https://api.{environment}.validis.com/v1/engagements/{engagementId}/journals \
-H 'Authorization: bearer {Your_Auth_Token} \
-H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \
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 |
Inclusive period id from which journals should be retrieve | query parameter |
toPeriodId integer |
Inclusive period id up to which journals should be retrieve | query parameter |
fromDate date |
Inclusive transaction date, in ISO format, from when journals are selected | query parameter |
toDate date |
Inclusive transaction date, in ISO format, up to when journals are selected | query parameter |
types string |
Comma-separated list of Journal Types | query parameter |
The following elements are returned in the GET GL Journals response
| Field | Description |
|---|---|
journalId string |
DataShare internal unique identifier |
remotePk string |
Accounting package reference |
journalRef string |
Transaction number / Journal number |
journalType JournalType |
See Journal Type |
transactionDate date |
Transaction / Document date of the transaction |
financialPeriod Financial Period |
Financial period in which journal has been reported, see below |
description string |
General ledger transaction narrative/description |
entryTimestamp timestamp |
Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages) |
entryUser string |
User/Username who posted the transaction (may be the same as the entry user for certain accounting packages) |
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) |
bankRec boolean |
Indicator to show if the transaction has been reconciled with a bank account (not applicable, unreconciled or reconciled) |
vatRec boolean |
Indicator to show if the transaction has been reconciled with a vat account (not applicable, unreconciled or reconciled) |
systemGenerated boolean |
Indicator to show if the transaction was automatically generated by the system |
source string |
Transaction type held within the general ledger |
modifiedTimestamp timestamp |
Time the transaction was last modified on the system (only applies to certain accounting packages) |
modifiedUser string |
User/Username who last modified the journal (may be the same as the entry user for certain accounting packages) |
lines JournalEntry |
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 number |
DataShare internal unique identifier |
startDate date |
Period first day (inclusive) |
endDate date |
Period last day (inclusive) |
JournalEntry
| Field | Description |
|---|---|
lineId string |
DataShare internal unique identifier |
remotePk string |
Accounting package reference |
account AccountRef |
See below |
baseValue decimal |
Journal entry amount in the base currency (base currency set in accounting package) |
transactionValue decimal |
Journal entry amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency) |
currencyIso string |
Currency ISO code (3 chars) |
reportingCurrencyIso string |
Currency ISO code (3 chars) |
transactionExchangeRate string |
Transaction exchange rate calculated from transactionValue / baseValue |
reportingValue decimal |
Reporting amount in reporting currency (only applies to certain accounting packages) |
reportingExchangeRate decimal |
Reporting exchange rate calculated from REPORTING_VALUE/BASE VALUE (if reporting currency is different to base currency – only applies to certain accounting packages) |
source string |
Transaction type held within the general ledger |
description string |
General ledger transaction additional narrative, reference fields |
AccountRef
| Field | Description |
|---|---|
accountId string |
DataShare internal unique identifier |
primaryCategory string |
Account [primary category] (#Primary_Category) |
tag string |
Account [tag] (#tags) |
remotePk string |
Transaction number / Journal number |
code string |
Account code |
name string |
Account name |
Journal Types
JournalTypes are in a static list as follow:
| Type | Description |
|---|---|
| JOURNAL | Journal transaction |
| BANK | Bank transaction |
| CASH | Short term cash transaction |
| WAGES | Wage related transaction |
| PURCHASES | Purchases |
| SALES | Sales |
| CAPEX | Other |
| SALE_CREDIT | Capital expenditure |
| PURCHASE_CREDIT | Sale credit |
| VAT | Purchase credit |
| STOCK | VAT transaction |
| OPENING_BALANCE | Stock movement |
| BALANCE_FORWARD | Opening balance |
| YEAR_END | Year end |
| CREDIT_CARD | Credit card |
| PURCHASE_LINK | Purchase link |
| SALES_LINK | Sales link |
| YE_BS | Year end – balance sheet |
| YE_PL | Year end – profit and loss |
| OTHER | Balance forward transaction |