> ## Documentation Index
> Fetch the complete documentation index at: https://developer.findity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started
Step-by-step guide for building an export integration with Findity's Connect API to receive approved expense data in your bookkeeping, payroll, or payment system.
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](/docs/get-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](#common-integration-patterns) for details.
3. Read the [Voucher structure](/docs/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 by default to "Transfer" 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
```
| Parameter | Type | Description |
| - | - | - |
| `organizationId` | string | Your organization's ID in the Findity platform |
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](/reference/get_organizations-organizationid-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}
```
| Parameter | Type | Description |
| - | - | - |
| `organizationId` | string | Your organization's ID |
| `exportId` | string | The `id` of the export returned from the list call |
This returns details about the export, including the recipient configuration and status.
→ See the [Get export](/reference/get_organizations-organizationid-exports-exportid) 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:
| Format | `verificationListsType` | Description |
| - | - | - |
| One voucher per report | `REPORT_PER_EXPENSE` | Each report becomes one voucher with all expenses as rows |
| One voucher per report (grouped) | `REPORT_PER_ACCOUNT` | Same as above, but rows are aggregated per account number |
| One voucher per user | `USER_PER_EXPENSE` | All reports for a user combined into a single voucher |
| One voucher per expense | `EXPENSE` | Each individual expense gets its own voucher |
| One row per report (no accounting) | `REPORT_PER_REPORT_PAID` | Aggregated per report — for payment recipients |
→ See the [Voucher structure](/docs/voucher-structure) guide for a full explanation of all eight output formats.
→ See the [Get export vouchers](/reference/get_organizations-organizationid-exports-exportid-export) 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.
Use the `voucherId` returned by the [Get export vouchers](/reference/get_organizations-organizationid-exports-exportid-export) response as input when calling the process export procedure.
```
PUT /v1/connect/organizations/{organizationId}/exports/{exportId}/updatestatus
```
→ See the [Process export](/reference/put_organizations-organizationid-exports-exportid-updatestatus) 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 (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.
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.
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
| Error scenario | Likely cause | Resolution |
| - | - | - |
| No exports returned | No approved expenses have been bulk-sent yet | Verify that an admin has approved and sent expense reports in the Findity platform |
| `ORGANIZATION_NOT_FOUND` | Invalid `organizationId` | Confirm your organization ID matches the one in Findity Admin |
| `EXPORT_NOT_FOUND` | Invalid `voucherId` or export belongs to a different organization | Verify the `voucherId` was returned from the list exports call for the same organization |
| `RECIPIENT_NOT_FOUND` | API report recipient not configured | Set up the recipient in **Findity Admin > Settings > Expense management > Integrations** |
| `401 Unauthorized` | Expired or invalid Bearer token | Refresh your access token — see the [Authentication guide](/docs/accessing) |