List expense reports

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

partnerId

string

required

The id of the partner for which we retrieve expense reports UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

Query Parameters

statuses

string[]

Comma separated list of statuses to include, to exclude a status use ! before the status. Statuses: APPROVAL, APPROVED, BULK_TRANSFER, DELETED, ERROR, NEW, NORMAL, ON_HOLD, PAID, READY_TO_SEND, REJECTED, REVIEW, SEND, SENT, TRANSFER, TRANSFER_TO_RECIPIENT.

Pattern:

^!?(APPROVAL|APPROVED|BULK_TRANSFER|DELETED|ERROR|NEW|NORMAL|ON_HOLD|PAID|READY_TO_SEND|REJECTED|REVIEW|SEND|SENT|TRANSFER|TRANSFER_TO_RECIPIENT)$

include

enum<string>[]

Comma-separated list of strings used to include additional data in the response. Accepted values:

expenseRecords: Include all expense records in the report
approvalChain: Include approval chain information (hasRejectedExpenseRecords, hasIncorrectApprovalChains, currentApproverInfo, approvalAllowed, requiresNextStepApproverSelection)
sendChain: Include send chain information (sendChain, hasIncorrectApprovalChains)
employeeId: Include the employee ID of the report owner
validationErrors: Include the validation errors of the report and of its expenses
tag: Include tag information (simulatedCardReport, integrationTest, dimensions)
externalReports: Include reports an integration module is still working on, under meta.externalReports
meta.violations: Include the report's policy violations
meta.messages: Include the direct messages attached to the report
meta.autoApproval: Include the AI review guidance verdict for the report
meta.ids: Include the ids of every report matching the filter, ignoring pagination, under meta.ids

Available options:

expenseRecords,

approvalChain,

sendChain,

employeeId,

validationErrors,

tag,

externalReports,

meta.violations,

meta.messages,

meta.autoApproval,

meta.ids

max

integer<int>

default:10

max records to return

Required range: 1 <= x <= 1000

offset

integer<int>

default:0

the offset to be used in list

Required range: x >= 0

string

Parameter used in the search

reportGroup

integer

Zero based index of the report group to return, used by the Ready to send tab to split a large listing into slices. Reports are assigned to a group by their creation time, so the groups are stable and disjoint. Only applied when the owner is configured with more than one group (an organization's reportGroupSettings.numberOfRTSGroups, or a partner's numberOfReportGroups); otherwise the parameter is ignored and the full listing is returned.

Required range: x >= 0

sort

string[]

Specifies the property and direction for sorting the results. Each sorting criterion must use the property:direction format (e.g., name:asc or date:desc). You can apply multiple sorts by providing a comma-separated list (?sort=name:desc,date:asc) or by repeating the parameter (?sort=name:desc&sort=date:asc). Defaults to lastUpdated:desc when omitted.

Pattern: ^[a-zA-Z]+:(asc|desc)$

Response

meta

object

Hide child attributes

meta.count

integer

meta.total

integer

meta.totalAmount

number

Aggregated amount across the whole filtered set, ignoring pagination. Only returned for companyCardOnly listings.

meta.totalExpenses

integer

Aggregated expense record count across the whole filtered set, ignoring pagination. Only returned for companyCardOnly listings.

meta.externalReports

object[]

Expense reports an integration module has not finished yet, so they are not in data. Returned for include=externalReports. Empty when the integration has nothing in progress or is unavailable.

Hide child attributes

meta.externalReports.id

string

Id of the report inside the integration module. String, required.

meta.externalReports.name

string

Display name of the report. String, optional.

meta.externalReports.downloadUrl

string

Absolute url for downloading the report. String.

meta.externalReports.sendUrl

string

Absolute url for making the integration send the report. String.

meta.externalReports.status

enum<string>

Always READY_TO_SEND. String, enum.

Available options:

READY_TO_SEND

meta.externalReports.integrationPluginName

string

Name of the integration plugin the report came from. String.

meta.ids

string[]

The ids of every expense report matching the filter, ignoring pagination and max, so a client can offer "select all on all pages" without paging through the whole result. Returned for include=meta.ids. There is no upper bound, so the array grows with the size of the filtered set - ask for it only when the listing actually offers a bulk selection, and narrow the filter first on organizations with a lot of reports.

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data

object[]

Hide child attributes

data.comment

string

data.dateCreated

string

read-only

data.emailRecipients

string

data.expenseRecords

object[]

Hide child attributes

data.expenseRecords.id

string

data.expenseRecords.status

enum<string>

read-only

Available options:

NEW,

NORMAL,

APPROVAL,

APPROVED,

REJECTED

data.expenseRecords.personId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.expenseRecords.dateCreated

string

read-only

data.expenseRecords.lastUpdated

string

read-only

data.expenseRecords.organizationId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.expenseRecords.categoryId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.expenseRecords.rejectComment

string

read-only

data.expenseRecords.expenseReportId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.expenseRecords.reimbursement

number

read-only

data.expenseRecords.reimbursementCurrency

string

read-only

data.expenseRecords.meta

object

Hide child attributes

data.expenseRecords.meta.categoryIconUrl

string

Example:

"https://expense.findity.com/api/resources/8a5f867e9b204742a8cc2ca2b6c57358"

data.id

string

data.lastUpdated

string

data.name

string

data.organizationId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.personId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.previewUrl

string

read-only

data.reportNumber

string

data.sent

string

read-only

data.paid

string<date-time>

read-only

Date when the expense report was paid. ISO-8601 format (e.g., 2024-01-15T10:30:00Z). Read-only.

data.approved

string<date-time>

read-only

Date when the expense report was approved. ISO-8601 format (e.g., 2024-01-15T10:30:00Z). Read-only.

data.status

enum<string>

read-only

Available options:

APPROVAL,

APPROVED,

READY_TO_SEND,

BULK_TRANSFER,

ERROR,

NEW,

NORMAL,

ON_HOLD,

PAID,

REJECTED,

SEND,

SENT,

TRANSFER,

TRANSFER_TO_RECIPIENT,

REVIEW

data.processStatus

enum<string>

read-only

Available options:

DRAFT,

PROCESSING,

PROCESSED,

REJECTED

data.reimbursement

number

read-only

data.reimbursementCurrency

string

read-only

data.type

enum<string>

read-only

Available options:

AUTOMATIC,

MANUAL,

COMPANY_CARD

data.ownerName

string

data.firstName

string

First name of the expense report owner

data.lastName

string

Last name of the expense report owner

data.adminErrorInformation

string

Error information from admin operations

data.organizationName

string

data.organizationNumber

string

data.organizationLanguage

string

data.organizationUseNewDimensions

boolean

data.organizationRequiresAttestation

boolean

data.organizationUsesPaymentBasis

boolean

data.organizationReviewType

enum<string>

Review type for the organization. None, before approval, or after approval. The AFTER_SEND value actually means before approval.

Available options:

NONE,

AFTER_SEND,

AFTER_APPROVAL

data.expenseRecordCount

integer

Number of expense records in this report

data.totalAmount

number

Total amount of all expense records in the report

data.userCanModifyReports

boolean

data.userCanSendReports

boolean

data.reportGroup

integer

data.onHoldStatus

object

read-only

On-hold status information

Hide child attributes

data.onHoldStatus.cards

object[]

List of active cards associated with the expense report

Hide child attributes

data.onHoldStatus.cards.bank

string

Bank identifier

data.onHoldStatus.cards.cardNumber

string

Card number (masked)

data.onHoldStatus.cardMissingConfig

object[]

List of cards missing configuration

Hide child attributes

data.onHoldStatus.cardMissingConfig.erId

string

Expense record ID

data.onHoldStatus.cardMissingConfig.bank

string

Bank identifier

data.onHoldStatus.cardMissingConfig.cardNumber

string

Card number (masked)

data.onHoldStatus.cardMissingConfig.cardExternalId

string

External card ID

data.onHoldStatus.transactionWithAuthStatus

string[]

List of expense record IDs with authorization status transactions

data.onHoldStatus.cardDeleted

object[]

List of deleted cards

Hide child attributes

data.onHoldStatus.cardDeleted.erId

string

Expense record ID

data.onHoldStatus.cardDeleted.bank

string

Bank identifier

data.onHoldStatus.cardDeleted.cardNumber

string

Card number (masked)

data.onHoldStatus.cardDeleted.cardExternalId

string

External card ID

data.onHoldStatus.allTransactionsEligibleForClearing

boolean

Whether all transactions are eligible for manual clearing

data.bank

string

Bank information for payment

data.dueDate

string<date-time>

Payment due date. ISO-8601 format (e.g., 2024-01-15T10:30:00Z).

data.cardNumber

string

Card number (masked)

data.invoiceRef

string

Invoice reference

data.invoiceNumber

string

Invoice number

data.invoiceDate

string<date-time>

Invoice date. ISO-8601 format (e.g., 2024-01-15T10:30:00Z).

data.externalVoucherNumber

string

External voucher number from integration

data.externalVoucherInformation

string

External voucher information

data.externalVoucherErrorInformation

string

Error information from external voucher system

data.externalVoucherId

string

External voucher ID

data.reminderSentToUser

boolean

Whether a reminder has been sent to the user

data.hasExpenseViolations

boolean

Whether any expense in the report has an unhandled policy violation (duplicate receipt or other)

data.message

object

The latest direct message of the report, used for the message icon in the report list. Always returned when the report has a message, omitted otherwise. Use the 'meta.messages' include to get the report's messages (on the single-report endpoints only the messages sent to the report owner).

Hide child attributes

data.message.text

string

required

The text of the latest direct message on the report. Plain text with no fixed maximum length.

data.message.isAdminView

boolean

required

Whether the message was written from the admin view

data.approverReminded

boolean

Whether an approver has been reminded

data.reminderSentToApprover

boolean

deprecated

Deprecated, use approverReminded. Whether an approver has been reminded

data.employeeId

string

Employee ID (included when 'employeeId' is in include parameter)

data.validationErrors

object[]

Validation errors of the report and of its expenses (included when 'validationErrors' is in include parameter). Errors on an expense carry the expenseRecordId of that expense; errors on the report itself have no expenseRecordId.

Hide child attributes

data.validationErrors.errorMessage

string

required

Translated, human-readable text of the error

data.validationErrors.errorCode

string

required

Code of the error, for example REQUIRED_FIELD

data.validationErrors.checkType

enum<string>

required

Severity of the error. ERROR - the document cannot be saved, BLOCKER - the report cannot be sent, WARNING - informational only

Available options:

ERROR,

BLOCKER,

WARNING

data.validationErrors.property

string

The field the error applies to, or the custom field definition id for custom fields. Omitted when the error is not tied to a field.

data.validationErrors.expenseRecordId

string

The expense the error belongs to. Omitted for errors on the report itself.

data.hasRejectedExpenseRecords

boolean

Whether the report has rejected expense records (included when 'approvalChain' is in include parameter)

data.hasIncorrectApprovalChains

boolean

Whether the report has incorrect approval chains (included when 'approvalChain' or 'sendChain' is in include parameter)

data.approvalAllowed

boolean

Whether the calling user may approve or reject this report, as the current approver or as a report/organization administrator when both the client application and the organization allow report/organization administrators to approve. Never true for the caller's own report unless the caller is the current approver. Only evaluated for a report with a single approval chain that has one active step, no incorrect approval chains and no pending next step approver selection (see currentApproverInfo.approvalChainId); otherwise false (included when 'approvalChain' is in include parameter)

data.requiresNextStepApproverSelection

boolean

Whether an approver for the next approval step has to be selected before the report can be approved. Only present for reports in status APPROVAL (included when 'approvalChain' is in include parameter)

data.currentApproverInfo

object

Information about the current approver (included when 'approvalChain' is in include parameter)

Hide child attributes

data.currentApproverInfo.singleApprover

boolean

Whether the report has a single approver

data.currentApproverInfo.hasIncorrectApprovalChains

boolean

Whether the report has incorrect approval chains

data.currentApproverInfo.approvalChainId

string

The approval chain ID. Set when the report has exactly one approval chain with one active step, also when the caller may approve as an administrator without being one of the step's approvers. Not set when hasIncorrectApprovalChains or requiresNextStepApproverSelection is true. Send it as approvalChainId when approving or rejecting the report.

data.currentApproverInfo.fullName

string

Full name of the current approver, or of the temporary approver when one is set for the step. When the step has several approvers, only set if the calling user is one of them (it is then the caller's own name).

data.currentApproverInfo.email

string

Email address of the current approver, or of the temporary approver when one is set for the step. When the step has several approvers, only set if the calling user is one of them (it is then the caller's own email).

data.sendChain

object

Send chain information (included when 'sendChain' is in include parameter)

Hide child attributes

data.sendChain.isComplete

boolean

Whether every active step in the chain has been sent

data.sendChain.senders

object[]

List of senders in the chain

Hide child attributes

data.sendChain.senders.status

string

Status of this step in the chain. The step a report is currently waiting on is the one with the lowest sortOrder among the steps still in TRANSFER_TO_RECIPIENT, which is what the recipientId filter matches on.

data.sendChain.senders.recipient

object

The recipient this step sends to

Hide child attributes

data.sendChain.senders.recipient.id

string

Id of the recipient, the value the recipientId filter takes

data.sendChain.senders.recipient.integrationPluginName

string

The integration plugin that delivers to this recipient, if the recipient is served by one

data.sendChain.senders.sortOrder

integer

Position of this step in the chain, ascending

data.sendChain.senders.collectReport

boolean

Whether this step collects the report instead of sending it on

data.sendChain.senders.recordInstances

object[]

The per expense record send instances belonging to this step

Hide child attributes

data.sendChain.senders.recordInstances.id

string

External id of the record send instance

data.sendChain.senders.recordInstances.expenseRecordId

string

The expense record this instance belongs to

data.sendChain.senders.recordInstances.externalVoucherNumber

string

Voucher number the recipient booked the record under

data.sendChain.senders.recordInstances.externalVoucherId

string

The recipient's own id for the voucher

data.sendChain.senders.recordInstances.externalVoucherUrl

string

Link to the voucher in the recipient system

data.sendChain.senders.recordInstances.externalVoucherInformation

string

Message returned by the recipient for this record

data.sendChain.senders.recordInstances.externalVoucherErrorInformation

string

Error returned by the recipient for this record

data.sendChain.senders.recordInstances.bookingDate

string<date-time>

When the recipient booked the record

data.sendChain.senders.recordInstances.includedInRecipient

boolean

Whether the record was part of what was sent to the recipient

data.sendChain.senders.uniqueVoucherNumbers

string[]

Unique voucher numbers

data.sendChain.senders.numberOfNonBookedExpenses

integer

Number of non-booked expenses

data.sendChain.senders.numberOfBookedExpenses

integer

Number of booked expenses

data.sendChain.senders.aggregatedVoucherNumbers

string

Aggregated voucher numbers

data.sendChain.senders.aggregatedVoucherInformation

string

Aggregated voucher information

data.sendChain.senders.aggregatedVoucherErrorInformation

string

Aggregated voucher error information

data.tag

object

Tag information (included when 'tag' is in include parameter)

Hide child attributes

data.tag.simulatedCardReport

boolean | null

data.tag.integrationTest

boolean | null

Only returned to callers with the developer role.

data.tag.dimensions

object | null

The report's dimension values keyed by the dimension's description. A dimension with one value holds that value, a dimension with several values holds a list of them. Only computed from the report's custom fields in the organization level list, when the requested statuses include REVIEW, APPROVAL or READY_TO_SEND; otherwise the value stored on the report is returned (normally null).

Hide child attributes

data.tag.dimensions.{key}

any

Example:

{
  "Project": "P-100",
  "Cost center": ["CC-1", "CC-2"]
}

data.meta

object

Server-computed metadata for the report. Each property is opt-in through the include parameter.

Hide child attributes

data.meta.autoApproval

object

AI review guidance for the report, produced by the Controller agent and rolled up from the verdicts on the report's expenses. Only present when 'meta.autoApproval' is in the include parameter, the feature is enabled for the organization, and the agent has reached a verdict for every expense in the report.

Hide child attributes

data.meta.autoApproval.status

enum<string>

required

read-only

The verdict for the whole report. APPROVED means the report is low risk and needs no manual attention. REJECTED means at least one of its expenses was flagged and the report needs manual review - no rejection has taken place and the report's own status is unaffected. The two values match the per-expense verdict the expense API already exposes under meta.autoApproval, so a client can use one mapping for both. A report the agent has not finished with is omitted entirely rather than reported as pending.

Available options:

APPROVED,

REJECTED

data.meta.autoApproval.reasons

object[]

read-only

Why the agent reached that verdict, in the same wording the approver app shows the end user and already translated for the caller's locale. For REJECTED these are the deviations found on the report's expenses, de-duplicated across them and ordered by reason code. For APPROVED these are the checks that came back clean. Omitted when there is nothing to show, so a REJECTED report can arrive without it.

Hide child attributes

data.meta.autoApproval.reasons.reason

enum<string>

required

The check the agent ran. The set is closed and matches the agent's reason types; new codes are only added together with a new agent capability.

Available options:

SIMILAR_REJECTED_ORG,

SIMILAR_REJECTED_PERSON,

SIMILAR_REJECTED_GLOBAL,

POLICY_FAILURE,

NOT_VALID_RECEIPT,

DEVIATING_AMOUNT_ORG,

DEVIATING_AMOUNT_PERSON,

DEVIATING_AMOUNT_GLOBAL,

PREDICT_AMOUNT_DEVIATION,

WEEKEND_PURCHASE_DATE,

SPECIAL_ITEM_ALCOHOL,

SPECIAL_ITEM_TOBACCO

data.meta.autoApproval.reasons.description

string

required

The translated sentence shown for that reason.

data.customFields

object[]

Hide child attributes

data.customFields.fieldDefinitionId

string

UUID without dashes (32-character hex string)

Pattern: ^[0-9a-fA-F]{32}$

data.customFields.value

any

Can be: string, number, integer, date, boolean

Authentication

Findity Expense API

Findity Admin API

Findity Admin API V0

Findity Connect API

Authorizations

Path Parameters

Query Parameters

Response