How to retrieve a large volume of expenses through the Expensya API?
Expensya provides public APIs that allow you to retrieve, add, and modify data instantly.
In this article, we will see how to retrieve a large volume of expenses using Expensya's APIs, whether it is for URSSAF controls or simple accounting checks.
How to use Expensya's public APIs?
This link will redirect you to the article explaining how to connect to Expensya's APIs.
Which APIs will allow you to retrieve a large volume of expenses?
We provide two APIs that allow you to retrieve expenses in large volume.
The choice of the API depends on your specific need:
- If you want to retrieve raw data in JSON format to manipulate in your program as needed, you should use the GetExpenses API, located under the Expenses section. This API will return a list of expenses based on the specified parameters.
- If you want to retrieve data in the format of an active export on your Expensya account (e.g., standard Excel Expensya, standard PDF Expensya, Full CSV Expensya), you should use the ExportExpenses API, located under the Export section. You must first contact Expensya's support team in order to obtain the unique identifier of the desired export (the identifier is in Guid format).
A - API GetExpenses:
To retrieve a large volume of expenses, consider the following parameters to obtain precise results:
- If you want to retrieve expenses related to a specific entity, you need to have access to the analytical axes parameters found on the collaborator's profile:
- ownerPayId2: The first analytical axis of the collaborator, typically used to identify the collaborator's entity.
- ownerPayId3: The second analytical axis of the collaborator.
- ownerPayId4: The third analytical axis of the collaborator.
- ownerPayId5: The fourth analytical axis of the collaborator.
- ownerPayId6: The fifth analytical axis of the collaborator.
- If you want to retrieve expenses within a specific period, you need to add parameters to refine your search:
dateFilterType: This parameter allows you to select the target date through a list of values in the 'enum' format:
- InvoiceDate = 1: Expense date.
- ValidationDate = 2: Expense validation date.
- AccountingValidationDate=3: Accounting validation date (Expense archiving).
- SubmissionDate = 4: Expense submission date.
- CreationDate=6: Expense creation date.
- UserModificationDate=9: Modification date made by the collaborator.
- ValidatorModificationDate=10: Modification date made by the validator.
StartDate: Start date based on the value provided in dateFilterType (Format - date-time in RFC3339 format)
EndDate: End date based on the value provided in dateFilterType (Format - date-time in RFC3339 format)
- If you want to retrieve expenses with a specific state:
ReportState: The state of the expense report, with a list of values in 'enum' format:
- Submitted=2: Submitted state
- Rejected=3: Rejected state
- Validated=4: Approved state
- Closed=5: Archived state
- ValidatedAndExported=6: Approved and exported state
- PreSubmitted=8: In validation state
Best practices recommended by Expensya:
- Use the pageSize parameter to limit the number of results per page (up to 100 per page).
- Use the page parameter to navigate between pages (default is 0).
- Expensya's recommendation: Do not exceed 100 API calls per minute.
- The best time to retrieve such a volume of expenses is between 2:00 AM and 4:00 AM (Paris Time Zone).
Result of the GetExpenses API
B - API ExportExpenses:
After obtaining the export identifier from Expensya support, you must provide it in the parameter below:
- exportId: unique identifier of the export format. Contact Expensya support to receive this unique identifier.
- If you want to retrieve expenses related to a specific entity, you have access to the 'analytical axes' parameters found on the collaborator's profile:
- payId2: the first analytical axis of the collaborator, typically used to identify the collaborator's entity.
- payId3: the second analytical axis of the collaborator.
- If you want to retrieve expenses within a specific period, you also have parameters to refine your search:
- dateFilterType: This parameter allows you to select the target date through a list of values in 'enum' format:
- InvoiceDate = 1: Expense date.
- ValidationDate = 2: Expense validation date.
- AccountingValidationDate = 3: Accounting validation date (Expense archiving).
- SubmissionDate = 4: Expense submission date.
- CreationDate = 6: Expense creation date.
- UserModificationDate = 9: Modification date made by the collaborator.
- ValidatorModificationDate = 10: Modification date made by the validator.
- startDate: start date based on the value provided in dateFilterType (Format - date-time in RFC3339 format).
- endDate: end date based on the value provided in dateFilterType (Format - date-time in RFC3339 format).
- If you want to retrieve expenses with a specific state:
- reportState: The state of the expense report, with a list of values in 'enum' format:
- Submitted = 2: Submitted state
- Rejected = 3: Rejected state
- Validated = 4: Approved state
- Closed = 5: Archived state
- ValidatedAndExported = 6: Approved and exported state
- PreSubmitted = 8: In validation state
- If you also want to retrieve expense receipts:
- includeReceipts: Add the expense receipts (the parameter is of boolean type, so you should specify 'true' for yes and 'false' for no).
Result of the API ExportExpenses :
Description of the elements in the ResultItem:
- FileUrl: Download link for the expenses export file.
- FileExtension: The file extension of the export.
- FileName: The name of the export file.
