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 number |
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 |
AR Links
| 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. |
AR GL Links
| 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 |
AP Links
| 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 |
AP GL Links
| 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 |