Hero

API Docs

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

Extracts

Overview

These endpoints give you access to a variety of granular reports containing all of the transactions assoicated with an upload. They can be provided as either JSON or CSV.

Obtaining Extracts

After the initial call to an endpoint, a 202 response will be given, and after subsequent call to the same endpoint, you will recieve the below files links. The extract cache is invalidated whenever there is an upload or the charts of accounts is changed. Best practice is to implement 30 second retries, majority of data is available within 90seconds.

Common Parameters

Required Parameters

Parameter Description Location
engagementId
integer
The unique identifier for the Engagement Path
authorization
integer
Valid access token (JSON Web Token) Header
Ocp-Apim-Subscription-Key
integer
API Key fetched from DataShare Admin Header
includeFutureYears
boolean
Include future dated invoices query string parameter
Format
string
JSON or CSV query string parameter

General Ledger

The GL Extract will create a zipped folder containing:

File Description
GL Transactions General Ledger Transactions
GL Period Balances General Ledger Period Balances
GL Period Balances Summarised General Ledger Period Balances summarised in the Validis chart of accounts
Company Details Company Details for the SME that completed the upload
GET v2/extracts/general-ledger/engagements/{engagementId}
     curl -X GET \ 
     https://api.{environment}.validis.com/v1/extracts/general-ledger/
     engagements/{engagementId} \ 
     -H 'Authorization: bearer {Your_Auth_Token} \ 
     -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

GL Transactions

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamps
Date the data was uploaded to Validis
GL_TX_ID
number
Unique identifier for the GL Transaction (to link to original AR or AP Transaction)
ACCOUNT_ID
number
Unique identifier for the Account
ACCOUNT_CODE
integer
Code of the account as exported from the accounting package
ACCOUNT_NAME
integer
Name of the account as exported from the accounting package
PRIMARY_CATEGORY_CODE
integer
Validis defined category (Validis Chart of Accounts)
PRIMARY_CATEGORY
integer
Validis defined category name (Validis Chart of Accounts)
TAG_CODE
integer
Validis defined tag (Validis Chart of Accounts)
SHEET_ID
number
Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET
integer
Type of account name
JOURNAL_ID
integer
Transaction number / Journal number
TRANSACTION_DATE
date
Transaction / Document date of the transaction
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
PERIOD_ID
number
Validis defined financial period ID
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
HEADER_DESCRIPTION
integer
General ledger transaction narrative/description
HEADER_TIMESTAMP
timestamp
Time the transaction was posted on the system
HEADER_ENTRY_USER
integer
User/Username who created the transaction
POSTING_TIMESTAMP
timestamp
Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER
integer
User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
HEADER_SOURCE
integer
Transaction type held within the general ledger
MODIFIED_TIMESTAMP
timestamp
Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER
integer
User/Username who last modified on the system (only applies to certain accounting packages)
REMOTE_PK
integer
Validis internal keys only - used for joining tables
LINE_SOURCE
integer
Transaction type stored at the line level
LINE_DESCRIPTION
integer
General ledger transaction additional narrative, reference fields
BASE_VALUE
decimal
Transaction amount in base currency (base currency set in accounting package)
TRANSACTION_VALUE
decimal
Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_CURRENCY
integer
Transaction currency ISO code (3 chars)
TRANSACTION_EXCHANGE_RATE
decimal
Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
REPORTING_VALUE
decimal
Reporting amount in reporting currency (if reporting currency is different to base currency – only applies to certain accounting packages)
REPORTING_CURRENCY
integer
Reporting currency ISO code (3 chars) (if reporting currency is different to base currency – only applies to certain accounting packages)
REPORTING_EXCHANGE_RATE
decimal
Reporting exchange rate calculated from REPORTING_VALUE/BASE VALUE (if reporting currency is different to base currency – only applies to certain accounting packages)
var1
integer
Required for the valid8 integration (QuickBooks Desktop, QuickBooks Online (US API), Sage 50 US (Peachtree), Dynamics GP)

GL Period Balances

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
ACCOUNT_ID
number
Unique identifier for the Account
ACCOUNT_CODE
integer
Code of the account as exported from the accounting package
ACCOUNT_NAME
integer
Name of the account as exported from the accounting package
PRIMARY_CATEGORY_CODE
integer
Validis defined category (Validis Chart of Accounts)
PRIMARY_CATEGORY
integer
Validis defined category name (Validis Chart of Accounts)
TAG_CODE
integer
Validis defined tag (Validis Chart of Accounts)
SHEET_ID
number
Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET
integer
Type of account name
CURRENCY_CODE
integer
currency ISO code (3 chars)
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
OPENING
decimal
Opening balance for the Validis defined PERIOD_ID
CLOSING
decimal
Closing balance for the Validis defined PERIOD_ID
CREDITS
decimal
Total credits for the Validis defined PERIOD_ID
DEBITS
decimal
Total debits for the Validis defined PERIOD_ID

GL Period Balances Summarised

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
PRIMARY_CATEGORY_CODE
integer
Validis defined category (Validis Chart of Accounts)
PRIMARY_CATEGORY
integer
Validis defined category name (Validis Chart of Accounts)
TAG_CODE
integer
Validis defined tag (Validis Chart of Accounts)
SHEET_ID
number
Type of account: 1: balance sheet 2: profit and loss 0: unassigned
SHEET
integer
Type of account name
CURRENCY_CODE
integer
currency ISO code (3 chars)
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
OPENING
decimal
Opening balance for the Validis defined PERIOD_ID
CLOSING
decimal
Closing balance for the Validis defined PERIOD_ID
CREDITS
decimal
Total credits for the Validis defined PERIOD_ID
DEBITS
decimal
Total debits for the Validis defined PERIOD_ID

Company Details

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
ADDRESS_1
integer
Address first line as exported from the accounting package
ADDRESS_2
integer
Address second line as exported from the accounting package
ADDRESS_3
integer
Address third line as exported from the accounting package
TOWN_CITY
integer
Town as exported from the accounting package
STATE_COUNTY
integer
State/County as exported from the accounting package
POST_ZIPCODE
integer
Postcode/Zip code as exported from the accounting package
COUNTRY_CODE
integer
Country ISO code (3 chars)
COUNTRY_NAME
integer
Country name as exported from the accounting package
CURRENCY_CODE
integer
Currency ISO code (3 chars) for Base currency

Accounts Receivable

The AR Extract will create a zipped folder containing:

File Description
AR Transactions Accounts Receivable Transactions
AR Period Balances Accounts Receivable Period Balances
AR Customer Master Debtor details
AR Links Accounts Receivable transactions links
AR GL Links Accounts Receivable transactions links to the associated General Ledger transactions
GET v2/extracts/accounts-receivable/engagements/{engagementId}
 curl -X GET \ 
   https://api.{environment}.validis.com/v2/extracts/accounts-receivable/
   engagements/{engagementId} \ 
   -H 'Authorization: bearer {Your_Auth_Token} \ 
   -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

AR Transactions

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
SALES_TX_ID
number
Internal ID
REMOTE_PK
integer
Validis internal keys only - used for joining tables
TRANSACTION_TYPE_ID
number
Type of transactions, list subject to increase: 0 Invoice 1 Payment 2 Credit Note 3 Discount 4 Write off 5 Refund 6 Currency Gain Loss 7 Journal Adjustment 8 Balance Forward
TRANSACTION_TYPE_NAME
integer
Indicative name for the type (see above)
DOCUMENT_ID
integer
Invoice number from the accounting package
CUSTOMER_DOCUMENT_ID
integer
Customer external document reference or description of invoice
CUSTOMER_ID
number
Internal identifier for the customer
CUSTOMER_CODE
integer
Customer Code as exported from the accounting package
CUSTOMER_NAME
integer
Customer Name as exported from the accounting package
TRANSACTION_DATE
date
Transaction / Document date of the transaction
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
TRANSACTION_VALUE
decimal
Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_BALANCE
decimal
Outstanding amount in the foreign currency at time of the upload
BASE_VALUE
decimal
Transaction amount in base currency (base currency set in accounting package)
BASE_BALANCE
decimal
Outstanding amount in the local currency at time of the upload
TAX_VALUE
decimal
VAT value of the transaction
CURRENCY_CODE
integer
currency ISO code (3 chars)
EXCHANGE_RATE
decimal
Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
ENTRY_TIMESTAMP
timestamp
Date and time the transaction was first created on the system
ENTRY_USER
integer
The user that created the entry on the accounting package
POSTING_TIMESTAMP
timestamp
Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER
integer
User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
DUE_DATE
date
Date payment is due for the transaction
SETTLED_TIMESTAMP
timestamp
Date from which outstanding balance become zero
BANK_REC
number
Code: 0 not applicable 1 unreconciled 2 reconciled
VAT_REC
number
Code: 0 not applicable 1 unreconciled 2 reconciled
HOLD_FLAG
boolean
Hold transaction identifier (only applies to certain accounting packages)
DISPUTE_FLAG
boolean
Disputed transaction identifier (only applies to certain accounting packages)
VOID_FLAG
boolean
Voided transaction identifier (only applies to certain accounting packages)
REVERSAL_FLAG
number
Code: 0 no 1 reversed 2 reversing
REVERSAL_ID
number
Reversal transaction identifier (only applies to certain accounting packages)
MODIFIED_TIMESTAMP
timestamp
Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER
integer
User/Username who last modified on the system (only applies to certain accounting packages)
PAYMENT_METHOD
number
Code: 0 cash 1 cheque 2 credit card 3 debit card 4 credit note 5 draft 6 electronic transfer 7 giro 8 intercompany transfer

AR Period Balances

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
SALES_PERIOD_ID
number
Internal ID
CUSTOMER_ID
number
Internal identifier for the customer
CUSTOMER_CODE
integer
Customer Code as exported from the accounting package
CUSTOMER_NAME
integer
Customer Name as exported from the accounting package
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
OPENING
decimal
Opening balance for the Validis defined PERIOD_ID
CLOSING
decimal
Closing balance for the Validis defined PERIOD_ID

AR Customer Master

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
CUSTOMER_ID
number
Internal identifier for the customer
CUSTOMER_CODE
integer
Customer Code as exported from the accounting package
CUSTOMER_NAME
integer
Customer Name as exported from the accounting package
REMOTE_PK
integer
Validis internal keys only - used for joining tables
ADDRESS_1
integer
Address first line as exported from the accounting package
ADDRESS_2
integer
Address second line as exported from the accounting package
ADDRESS_3
integer
Address third line as exported from the accounting package
TOWN_CITY
integer
Town as exported from the accounting package
STATE_COUNTY
integer
State/County as exported from the accounting package
POST_ZIPCODE
integer
Postcode/Zip code as exported from the accounting package
COUNTRY_CODE
integer
Country ISO code (3 chars)
COUNTRY_NAME
integer
Country name as exported from the accounting package
Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
LINK_ID
number
Unique identifier for the link
REMOTE_PK
integer
Validis internal keys only - used for joining tables
ITEM1_ID
number
First SALES_TX_ID that is being linked
ITEM2_ID
number
Second SALES_TX_ID that is being linked
TRANSACTION_VALUE
decimal
Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
BASE_VALUE
decimal
Amount in local currency
LINK_DATE
timestamp
Date the link was made in the accounting package
GROUP_ID
number
Allocation detail for group payments. Where there is a direct link between two saleHeaders, item1Id and item2Id will be populated and groupId will be null. Where group allocation has occurred then item2id will be null and groupId will be populated. Note that the groupId does not relate to a specific saleHeader but indicates a relationship between multiple saleHeaders.
Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
ID
number
Unique identifier for the link
SALES_TX_ID
number
Validis internal keys only - used for joining tables
GL_TX_ID
number
First SALES_TX_ID that is being linked

Accounts Payable

The AP Extract will create a zipped folder containing:

File Description
AP Transactions Accounts Payable Transactions
AP Period Balance Accounts Payable Period Balances
AP Supplier Master Creditor details
AP Links Accounts Payable transactions links
AP GL Links Accounts Payable transactions links to the associated General Ledger transactions
GET v2/extracts/accounts-payable/engagements/{engagementId}
 curl -X GET \ 
   https://api.{environment}.validis.com/v1/extracts/accounts-payable/
   engagements/{engagementId} \ 
   -H 'Authorization: bearer {Your_Auth_Token} \ 
   -H 'Ocp-Apim-Subscription-Key: {Your_API_Key}' \ 

AP Transactions

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
PURCHASES_TX_ID
number
Internal ID
REMOTE_PK
integer
Validis internal keys only - used for joining tables
TRANSACTION_TYPE_ID
number
Type of transactions, list subject to increase: 0 Invoice 1 Payment 2 Credit Note 3 Discount 4 Write off 5 Refund 6 Currency Gain Loss 7 Journal Adjustment 8 Balance Forward
TRANSACTION_TYPE_NAME
integer
Indicative name for the type (see above)
DOCUMENT_ID
integer
Invoice number from the accounting package
SUPPLIER_DOCUMENT_ID
integer
Supplier external document reference
SUPPLIER_ID
number
Internal identifier for the supplier
SUPPLIER_CODE
integer
Supplier Code as exported from the accounting package
SUPPLIER_NAME
integer
Supplier Company Name as exported from the accounting package
TRANSACTION_DATE
date
Transaction / Document date of the transaction
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
TRANSACTION_VALUE
decimal
Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
TRANSACTION_BALANCE
decimal
Outstanding amount in the foreign currency at time of the upload
BASE_VALUE
decimal
Transaction amount in base currency (base currency set in accounting package)
BASE_BALANCE
decimal
Outstanding amount in the local currency at time of the upload
TAX_VALUE
decimal
VAT value of the transaction
CURRENCY_CODE
integer
currency ISO code (3 chars)
EXCHANGE_RATE
decimal
Transaction exchange rate calculated from TRANSACTION_VALUE/BASE VALUE
ENTRY_TIMESTAMP
timestamp
Date and time the transaction was first created on the system
ENTRY_USER
integer
The user that created the entry on the accounting package
POSTING_TIMESTAMP
timestamp
Time the transaction was posted on the system (may be the same as the entry timestamp for certain accounting packages)
POSTING_USER
integer
User/Username who posted the transaction (may be the same as the entry user for certain accounting packages)
DUE_DATE
date
Date payment is due for the transaction
SETTLED_TIMESTAMP
timestamp
Date from which outstanding balance become zero
BANK_REC
number
Code: 0 not applicable 1 unreconciled 2 reconciled
VAT_REC
number
Code: 0 not applicable 1 unreconciled 2 reconciled
HOLD_FLAG
boolean
Hold transaction identifier (only applies to certain accounting packages)
DISPUTE_FLAG
boolean
Disputed transaction identifier (only applies to certain accounting packages)
VOID_FLAG
boolean
Voided transaction identifier (only applies to certain accounting packages)
REVERSAL_FLAG
number
Code: 0 no 1 reversed 2 reversing
REVERSAL_ID
number
Reversal transaction identifier (only applies to certain accounting packages)
MODIFIED_TIMESTAMP
timestamp
Time the transaction was last modified on the system (only applies to certain accounting packages)
MODIFIED_USER
integer
User/Username who last modified on the system (only applies to certain accounting packages)
PAYMENT_METHOD
number
Code: 0 cash 1 cheque 2 credit card 3 debit card 4 credit note 5 draft 6 electronic transfer 7 giro 8 intercompany transfer

AP Period Balances

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
SALES_PERIOD_ID
number
Internal ID
SUPPLIER_ID
number
Internal identifier for the supplier
SUPPLIER_CODE
integer
Supplier Code as exported from the accounting package
SUPPLIER_NAME
integer
Supplier Company Name as exported from the accounting package
PERIOD_ID
number
Validis defined financial period ID
FINANCIAL_YEAR_NAME
integer
Financial year name as exported from the accounting package
FINANCIAL_PERIOD_NAME
integer
Financial period name as exported from the accounting package
PERIOD_START_DATE
date
Validis period start date
PERIOD_END_DATE
date
Validis period end date
OPENING
decimal
Opening balance for the Validis defined PERIOD_ID
CLOSING
decimal
Closing balance for the Validis defined PERIOD_ID

AR Supplier Master

Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
COMPANY_NAME
integer
Company Name as exported from the accounting package
UPLOAD_DATE
timestamp
Date the data was uploaded to Validis
SUPPLIER_ID
number
Internal identifier for the supplier
SUPPLIER_CODE
integer
Supplier Code as exported from the accounting package
SUPPLIER_NAME
integer
Supplier Company Name as exported from the accounting package
REMOTE_PK
integer
Validis internal keys only - used for joining tables
ADDRESS_1
integer
Address first line as exported from the accounting package
ADDRESS_2
integer
Address second line as exported from the accounting package
ADDRESS_3
integer
Address third line as exported from the accounting package
TOWN_CITY
integer
Town as exported from the accounting package
STATE_COUNTY
integer
State/County as exported from the accounting package
POST_ZIPCODE
integer
Postcode/Zip code as exported from the accounting package
COUNTRY_CODE
integer
Country ISO code (3 chars)
COUNTRY_NAME
integer
Country name as exported from the accounting package
Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
LINK_ID
number
Unique identifier for the link
REMOTE_PK
integer
Validis internal keys only - used for joining tables
ITEM1_ID
number
First PURCHASES_TX_ID that is being linked
ITEM2_ID
number
Second PURCHASES_TX_ID that is being linked
TRANSACTION_VALUE
decimal
Transaction amount in the foreign currency (this can be the same as the base currency if the transaction is in base currency)
BASE_VALUE
decimal
Amount in local currency
LINK_DATE
timestamp
Date the link was made in the accounting package
Field Description
UPLOAD_ID
UUID
Unique identifier for the upload
ID
number
Unique identifier for the link
PUCHASES_TX_ID
number
Validis internal keys only - used for joining tables
GL_TX_ID
number
First SALES_TX_ID that is being linked