Getting started

Build an export integration that receives approved expense data from Findity and imports it into your bookkeeping, payroll, or payment system.

With all travel data, expenses, receipts, and other data that employees enter into the expense platform, Findity prepares the data to be received by an external system. The data is structured with account numbers, salary codes, and dimensions to map each entry to the correct destination. Since the chart of accounts is linked to categories, financial transactions can be booked without manual interaction.

Prerequisites

1. Complete the Getting started with the Findity API guide — this walks you through obtaining your API credentials and choosing your environment.
2. Configure an API report recipient in Findity Admin > Settings > Expense management > Integrations. Optionally, enter a webhook URL where Findity will send a notification when a new export is ready for download. If you cannot receive webhooks, your integration can poll the list exports endpoint on a schedule instead — see Common integration patterns for details.
3. Read the Voucher structure guide to understand how expense data is grouped into vouchers.

Export lifecycle overview

The export flow follows this sequence:

1. An employee submits an expense report
2. An approver approves the report — the expenses move to "ready for send" status
3. An admin triggers a bulk send, which generates an export package
4. Findity sends a webhook notification to your configured URL
5. Your integration fetches the export and its voucher data via the API
6. After processing, your integration updates the export status to confirm receipt

Step 1: List unprocessed exports

After an admin has approved and sent expenses, call the list exports endpoint to retrieve exports that have not yet been processed by your integration.

GET /v1/connect/organizations/{organizationId}/exports

The response returns an array of export objects. Each export includes an id that you use in subsequent steps to fetch voucher data and update the status.

→ See the List exports API reference for full request and response details.

Step 2: Fetch export details

Use the export id from Step 1 to retrieve metadata about a specific export.

GET /v1/connect/organizations/{organizationId}/exports/{exportId}

This returns details about the export, including the recipient configuration and status.

→ See the Get export API reference for full request and response details.

Step 3: Download the voucher data

This is the core step — fetch the actual financial data (vouchers and voucher rows) that your bookkeeping or payment system needs.

GET /v1/connect/organizations/{organizationId}/exports/{exportId}/export

The response contains a voucher package structured according to the recipient's configured output format. Each voucher contains:

• ownerId — the user who owns the expense
• expenseReportId — the parent report
• voucherRows — line items with amount, taxAmount, account, dimension, text, and expenseRecordId

📄

To download a PDF with booking data and receipt images, use the basisUrl from each voucher node and append ?format=pdf to the URL.

The voucher grouping depends on the verificationListsType configured on the recipient. Common formats include:

→ See the Voucher structure guide for a full explanation of all eight output formats.

→ See the Get export vouchers API reference for full request and response details.

Step 4: Update the export status

After your system has processed the voucher data, update the export status to confirm receipt. This prevents the export from appearing as unprocessed in future list calls.

PUT /v1/connect/organizations/{organizationId}/exports/{exportId}/updatestatus

→ See the Process export API reference for the request body format and response details.

⚠️

Always update the export status after processing. If your system encounters an error during import, report the failure status so administrators can investigate and re-trigger the export.

Optional: Update export content

If you need to attach a custom file (e.g., a transformed accounting file) back to the export, use the content endpoints:

PUT /v1/connect/organizations/{organizationId}/exports/{exportId}/content

GET /v1/connect/organizations/{organizationId}/exports/{exportId}/content

This is useful when your integration generates a formatted file (SIE, CSV, etc.) that administrators need to access from the Findity platform.

Common integration patterns

Webhook-driven vs polling

Webhook-driven (recommended): Configure a webhook URL on the API recipient. Findity sends a notification when a new export is ready, and your integration fetches and processes it immediately. This minimizes latency and avoids unnecessary API calls.

Polling: If you cannot receive webhooks, poll the list exports endpoint on a schedule (e.g., every 15 minutes) to check for new unprocessed exports. Filter by unprocessed status to avoid re-fetching completed exports.

Idempotent processing

Design your integration to handle the same export being fetched more than once. Use the exportId as a unique key in your system to detect and skip duplicates. This protects against network retries or webhook redeliveries.

PDF receipt archival

For each voucher, append ?format=pdf to the basisUrl to download a PDF containing the booking data and receipt images. Store these alongside the voucher data in your system for audit purposes.

Troubleshooting