Voucher structure

How expense data is structured into vouchers for export to bookkeeping, payroll, and payment systems via the Connect API. Understand how Findity structures approved expense data into vouchers for export to your bookkeeping, payroll, or payment system. When expenses are approved and sent, Findity packages them into an export containing vouchers and voucher rows. The voucher output format determines how expenses are grouped — by report, user, or individual expense — and whether full accounting detail (debit/credit/VAT rows) or simplified payment totals are included.

Key concepts

Concept	Description
Export	A package generated when an admin triggers a bulk send of approved expenses
Voucher	A grouping unit within the export — based on a report, user, or individual expense
VoucherRow	A line item within a voucher containing the financial data: amount, account, tax, dimensions, etc.
Recipient	The integration target configured in Findity Admin — its settings control the voucher output format

A single expense generates at least one voucher row, but typically produces multiple rows. For example, a standard receipt expense creates:

One debit row (the expense account)
One credit row (if bookkeeping is enabled)
One VAT row (if applicable)

Voucher output formats

The voucher grouping is configured on the API recipient and determines how expenses are packaged into vouchers. There are 8 possible formats, split into two categories.

Formats with accounting

These include full bookkeeping detail — debit rows, credit rows, VAT rows, account numbers, salary codes, and dimensions.

Format	`verificationListsType`	Description
One voucher per report	`REPORT_PER_EXPENSE`	Each report becomes one voucher. All its expenses appear as voucher rows.
One voucher per report (grouped)	`REPORT_PER_ACCOUNT`	Same as above, but voucher rows are aggregated per account number, tax number, or salary type.
One voucher per user	`USER_PER_EXPENSE`	All reports for a user are combined into a single voucher. Common for salary recipients.
One voucher per user (grouped)	`USER_PER_ACCOUNT`	Same as per-user, but with rows aggregated by account.
One voucher per expense	`EXPENSE`	Each individual expense, mileage, or per diem gets its own voucher.

Formats without accounting (payment)

These provide simplified output without bookkeeping detail — useful for payment recipients or outputs where no accounting is needed.

Format	`verificationListsType`	Description
One voucher row per report	`REPORT_PER_REPORT_PAID`	One voucher and one row per report — aggregates all expenses for that report.
One voucher row per user	`USER_PER_REPORT_PAID`	One voucher and one row per user — aggregates all expenses for the user.
One voucher row per expense	`REPORT_PER_EXPENSE_PAID`	One voucher per report with one row per expense, without accounting.

The voucher output format is configured by Findity when setting up a new branded integration. You can find it in the API recipient settings. If the configuration option you need is not available, contact support@findity.com.

Where to find the format in the JSON

The configured format appears in two places in the export JSON:

Recipient configuration — under organizations → recipients → verificationListsType
Each voucher — in the listType field

{
  "organizations": [
    {
      "recipients": [
        {
          "verificationListsType": "REPORT_PER_EXPENSE",
          "pluginName": "ce-integration-example",
          "id": "8ab28c4f6e238a35016e25d39e00004b"
        }
      ]
    }
  ],
  "vouchers": [
    {
      "listType": "REPORT_PER_EXPENSE",
      "id": "70673d31e9704f768d70748c173ad7c1",
      "ownerId": "8ab28c4f6e238a35016e25ee3b2c0084",
      "organizationId": "8ab28c4f6e238a35016e25d39cc60048",
      "expenseReportId": "36690003376e49f597956c64d7ea7381",
      "voucherRows": []
    }
  ]
}

Each voucher in the vouchers array contains the following key fields:

Field	Type	Description
`id`	string	Unique voucher identifier
`listType`	string	The grouping format (matches the recipient’s `verificationListsType`)
`ownerId`	string	The person (user) who owns the expenses
`organizationId`	string	The organization the expenses belong to
`organizationName`	string	Name of the organization
`expenseReportId`	string	The parent expense report ID
`expenseRecordIds`	string[]	IDs of individual expense records included in this voucher
`description`	string	Description of the voucher
`date`	string	Date of the voucher
`bookingDate`	string	The booking date for the voucher
`totalDebitAmount`	number	Total debit amount across all rows
`totalCreditAmount`	number	Total credit amount across all rows
`vatType`	string	How VAT is handled (e.g., `SEPARATELY`, `INCLUDED_AND_GROSS_AMOUNT`)
`recipientId`	string	The recipient this voucher is destined for
`recipientName`	string	Name of the recipient
`basisUrl`	string	URL to the accounting basis document (append `?format=pdf` for PDF)
`voucherRows`	array	The line items — see below
`integrationModuleResult`	object	Status of previous processing attempts (if any)

Voucher row structure

Each entry in the voucherRows array represents one accounting line:

Field	Type	Description
`id`	string	Unique row identifier
`type`	string	`DEBIT` or `CREDIT`
`amount`	number	The row amount (excluding tax)
`taxAmount`	number	The tax/VAT amount
`amountIncludingTax`	number	The total amount including tax
`description`	string	Description of the expense
`expenseRecordId`	string	Reference to the source expense record
`expenseReportId`	string	Reference to the parent expense report
`accountingNumber`	object	The account — contains `number`, `text`, `type` (e.g., `SALARY_CODE`), and `visible`
`dimensionValues`	array	Custom dimension values attached to this row
`unit`	string	Unit of measure (e.g., `PCS`)
`sortOrder`	number	Order of this row within the voucher
`group`	string	Row group (e.g., `NORMAL`)

Fetching voucher data

Use the Connect API to retrieve the voucher package for a specific export:

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

→ See the Get export vouchers API reference for full request and response details. → See the Export integration guide for the complete step-by-step workflow.

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

Processing vouchers

After fetching and importing the voucher data into your system, update the export status to confirm receipt. Send a voucherUpdates array with the processing result for each voucher:

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

Field	Type	Description
`id`	string	The voucher `id`
`status`	string	`SUCCESS` or `FAILED`
`bookingDate`	string	The date the voucher was booked in your system (ISO 8601)
`voucherNumber`	string	The voucher number assigned by your system
`informationText`	string	Optional informational message
`errorText`	string	Error description if status is `FAILED`

{
  "voucherUpdates": [
    {
      "id": "70673d31e9704f768d70748c173ad7c1",
      "status": "SUCCESS",
      "bookingDate": "2024-02-21T13:58:00Z",
      "voucherNumber": "123",
      "informationText": null,
      "errorText": null
    }
  ]
}

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

Choosing the right format

Use case	Recommended format	Why
General bookkeeping / ERP import	`REPORT_PER_EXPENSE`	Full detail per expense with accounting rows — most common format
Bookkeeping with aggregated accounts	`REPORT_PER_ACCOUNT`	Reduces row count by grouping amounts per account
Salary / payroll systems	`USER_PER_EXPENSE`	Groups all expenses per user for salary code-based processing
Payment systems (no accounting)	`REPORT_PER_REPORT_PAID`	Simple totals per report — no debit/credit rows
Per-expense payment tracking	`REPORT_PER_EXPENSE_PAID`	One row per expense without accounting — for granular payment matching

Integration tips

Test all format variants before going live

The voucher structure varies significantly between formats. Build and test your integration against each format you plan to support to ensure your parser handles all field variations correctly.

Handle missing fields gracefully

Depending on the format and expense type, some fields may be null. For example, payment formats (*_PAID) do not include accountingNumber on voucher rows, and totalCreditAmount may be null when credit accounting is not enabled.

Use expenseRecordIds for traceability

In grouped formats (REPORT_PER_ACCOUNT, USER_PER_ACCOUNT), individual voucher rows are aggregated. Use the expenseRecordIds array on the voucher to trace back to the original expense records when needed for auditing or reconciliation.

Archive PDFs for compliance

Append ?format=pdf to each voucher’s basisUrl to download a PDF containing the booking data and receipt images. Store these alongside your accounting records for audit compliance.

Home

MCP Server