Expense reports

Group expenses into reports, manage the report lifecycle, and submit reports for approval using either dynamic Fields or direct JSON payloads.

Overview

Expense reports collect one or more expense records into a single submission unit. Users typically create a report, add eligible expenses, review totals and required fields, then submit the report for approval.

Report lifecycle

Expense reports move through a lifecycle as users submit them and approvers process them:

Use processStatus to query broad lifecycle groups:

API endpoints

Step 1: List reports

List reports for an organization by processStatus:

curl -X GET "https://stage-api.findity.com/api/v1/expense/expensereports?organizationId={orgId}&processStatus=DRAFT&include=meta.abbreviation,meta.capabilities,expenseRecords" \
  -H "Authorization: Bearer {access_token}"

Use this to build report tabs such as Draft, Submitted, Approved, and Rejected.

Common include values:

Step 2: Initialize report fields

Use the report fields endpoint when your application renders the report form dynamically:

curl -X GET "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensereports/fields" \
  -H "Authorization: Bearer {access_token}"

To edit an existing report, pass the report ID:

curl -X GET "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensereports/fields?expenseReportId={expenseReportId}" \
  -H "Authorization: Bearer {access_token}"

The response contains fields such as:

⚠️

Always send the complete fields array when updating report fields — including hidden fields and fields the user did not modify.

Step 3: Add expenses to a report

A report groups expense records by ID. In a Fields-based UI, users typically select expenses through the expenseRecords field. In JSON format, you provide the expense record IDs directly.

To list expenses that can be added to a report, use the canBeAddedToReport filter:

curl -X GET "https://stage-api.findity.com/api/v1/expense/expenses?organizationId={orgId}&filter=canBeAddedToReport&include=meta.abbreviation,meta.capabilities" \
  -H "Authorization: Bearer {access_token}"

JSON example

curl -X POST "https://stage-api.findity.com/api/v1/expense/expensereports" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ff808181963979e20196397a2098004b",
    "name": "March expenses",
    "comment": "Expenses from March customer visits",
    "expenseRecords": [
      { "id": "expense-record-id-1" },
      { "id": "expense-record-id-2" }
    ]
  }'

Fields example

curl -X POST "https://stage-api.findity.com/api/v1/expense/expensereports?format=fields&organizationId={orgId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [...complete report fields array...] }'

Step 4: Manage report lifecycle

Use meta.capabilities to decide which actions to show in your UI. Capabilities may change based on report status, organization settings, and whether the report contains validation errors.

Common capabilities include:

Update a report

Using Fields:

curl -X PUT "https://stage-api.findity.com/api/v1/expense/expensereports/{expenseReportId}?format=fields" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [...complete report fields array...] }'

Using JSON:

curl -X PUT "https://stage-api.findity.com/api/v1/expense/expensereports/{expenseReportId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated March expenses",
    "comment": "Updated after review",
    "expenseRecords": [
      { "id": "expense-record-id-1" },
      { "id": "expense-record-id-2" }
    ]
  }'

Delete a draft report

curl -X DELETE "https://stage-api.findity.com/api/v1/expense/expensereports/{expenseReportId}" \
  -H "Authorization: Bearer {access_token}"

Step 5: Submit for approval

Submit the report when it is complete:

curl -X PUT "https://stage-api.findity.com/api/v1/expense/expensereports/{expenseReportId}?action=send" \
  -H "Authorization: Bearer {access_token}"

⚠️

Do not send a request body when using action=send. The API returns 400 BODY_NOT_ALLOWED if the submit request includes a body.

After submission, the report enters the approval workflow configured for the organization. The report status typically changes to APPROVAL, and approvers can review, approve, or reject the included expenses.

💡

Check meta.capabilities.canBeSentIn before showing a submit button. If submission fails, the API may return validation errors that explain which expense or report field must be corrected.

Retract a submitted report

If the workflow state allows it, retract a submitted report from approval:

curl -X PUT "https://stage-api.findity.com/api/v1/expense/expensereports/{expenseReportId}?action=retract" \
  -H "Authorization: Bearer {access_token}"

Only show this action when meta.capabilities.canBeRetracted is true. Retracting a report returns it from the approval flow so the user can make changes before submitting it again.

Best practices