Update expense report for organization

Updates an expense report. When the action query parameter is provided, performs the specified action instead of a field update. Otherwise, updates the allowed fields (name, comment, customFields, expenseRecords, and status with voucherNumber, errorText, bookingDate, sentToBookingDate and paidDate); any other fields in the request body are silently ignored. status is first compared with the report’s current status, case insensitive. A status equal to the current one counts as no status change and is ignored, whatever the status is, so a report read with GET can be sent back unchanged also when it is for example ON_HOLD. A body with only an unchanged status (or only read-only fields, or only empty customFields or expenseRecords) has nothing to update and is answered with 400 NO_KNOWN_JSON_PROPERTIES. When status differs from the current one, the report is moved to that status the same way action=setStatus does it, with the same side effects. Only NEW, NORMAL, READY_TO_SEND, SENT and PAID are accepted, anything else is answered with 400 INVALID_PARAMETER and nothing in the body is applied. Earlier, a different status that is not accepted was silently ignored; it is now rejected. A status that differs from the current one is always applied, also when it comes from an earlier GET and the report has been moved since; the update has no version check. Leave status out of the body unless the report should be moved. voucherNumber, errorText, bookingDate, sentToBookingDate and paidDate are only applied together with a status change. Sending them without status is answered with 400 INVALID_PARAMETER, and so is sending them with a status equal to the current one; use action=setStatus to change them on a report that is already in the target status. The GET response doesn’t contain these fields (it returns sent, paid and externalVoucherNumber instead), so they don’t block sending a report read with GET back unchanged. Returning the report to its owner (messageText, returnToUser) is only available through action=setStatus; sending either of them in a field update is answered with 400 INVALID_PARAMETER. On the partner endpoint (/partners/{partnerId}/reports/{reportId}) status and these fields are still ignored. moveToNextStep moves a report that is in TRANSFER or TRANSFER_TO_RECIPIENT to the next step of its send chain: to the next recipient, or to SENT when the chain is complete. forwardToApprovalOrBooking forwards a report that is ON_HOLD back into the approval or booking flow. Both are support tools and are restricted to the developer role. The report must belong to the organization in the path; a report of another organization is answered with 404 EXPENSE_REPORT_NOT_FOUND even when the caller administers that organization. sendReminder reminds the owner of the report about it, and takes { "message": "..." } as its body. Only reports that carry an invoice reference can be reminded, and only organization administrators and standard API keys may use it.

PUT

organizations

{organizationId}

reports

{reportId}

curl --request PUT \
  --url https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/reports/{reportId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Business Trip Stockholm",
  "comment": "Updated comment for the expense report",
  "expenseRecords": [
    {
      "id": "a73efe636a4d47359f3c28c3024b6d23"
    }
  ],
  "customFields": [
    {
      "fieldDefinitionId": "2b965c866b634698811dabf45a491089",
      "value": true
    }
  ]
}
'

{
  "id": "550e8400e29b41d4a716446655440000",
  "name": "Business Trip Stockholm",
  "personId": "123e4567e89b12d3a456426614174000",
  "organizationId": "550e8400e29b41d4a716446655440001",
  "dateCreated": "2024-01-15T09:30:00Z",
  "lastUpdated": "2024-01-16T14:45:00Z",
  "reportNumber": "ER-2024-001",
  "comment": "Business trip to Stockholm for client meeting",
  "emailRecipients": "manager@company.com;finance@company.com",
  "status": "APPROVAL",
  "processStatus": "PROCESSED",
  "type": "MANUAL",
  "reimbursement": 2580.5,
  "reimbursementCurrency": "SEK",
  "sent": "2024-01-16T10:00:00Z",
  "previewUrl": "https://expense.findity.com/api/expensereports/550e8400e29b41d4a716446655440000",
  "meta": {
    "autoApproval": {
      "status": "REJECTED",
      "reasons": [
        {
          "reason": "POLICY_FAILURE",
          "description": "Violates the company's expense policy."
        },
        {
          "reason": "WEEKEND_PURCHASE_DATE",
          "description": "The purchase was made during a weekend."
        }
      ]
    }
  },
  "expenseRecords": [
    {
      "id": "7f3c1a9e2b4d4e6f8a0b1c2d3e4f5a61",
      "status": "APPROVAL",
      "personId": "123e4567e89b12d3a456426614174000",
      "organizationId": "550e8400e29b41d4a716446655440001",
      "categoryId": "8a5f867e9b204742a8cc2ca2b6c57358",
      "expenseReportId": "550e8400e29b41d4a716446655440000",
      "dateCreated": "2024-01-15T09:30:00Z",
      "lastUpdated": "2024-01-16T14:45:00Z",
      "reimbursement": 1250,
      "reimbursementCurrency": "SEK",
      "meta": {
        "categoryIconUrl": "https://expense.findity.com/api/resources/8a5f867e9b204742a8cc2ca2b6c57358"
      }
    },
    {
      "id": "7f3c1a9e2b4d4e6f8a0b1c2d3e4f5a62",
      "status": "APPROVAL",
      "personId": "123e4567e89b12d3a456426614174000",
      "organizationId": "550e8400e29b41d4a716446655440001",
      "categoryId": "9b6f977f8c305753b9dd3db3c7d68469",
      "expenseReportId": "550e8400e29b41d4a716446655440000",
      "dateCreated": "2024-01-15T18:45:00Z",
      "lastUpdated": "2024-01-16T14:45:00Z",
      "reimbursement": 1330.5,
      "reimbursementCurrency": "SEK",
      "meta": {
        "categoryIconUrl": "https://expense.findity.com/api/resources/9b6f977f8c305753b9dd3db3c7d68469"
      }
    }
  ],
  "ownerName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "organizationName": "Acme Corporation",
  "organizationNumber": "556123-4567",
  "organizationLanguage": "en",
  "organizationUseNewDimensions": true,
  "organizationRequiresAttestation": false,
  "organizationUsesPaymentBasis": true,
  "expenseRecordCount": 2,
  "totalAmount": 2580.5,
  "userCanModifyReports": true,
  "userCanSendReports": true,
  "reportGroup": 1,
  "onHoldStatus": {
    "cards": [],
    "cardMissingConfig": [],
    "transactionWithAuthStatus": [],
    "cardDeleted": [],
    "allTransactionsEligibleForClearing": false
  },
  "bank": "SEB1234567890",
  "dueDate": "2024-01-25T00:00:00Z",
  "cardNumber": "**** **** **** 1234",
  "invoiceRef": "INV-2024-001",
  "invoiceNumber": "INV-2024-001",
  "invoiceDate": "2024-01-15T00:00:00Z",
  "reminderSentToUser": false,
  "employeeId": "EMP001",
  "validationErrors": [
    {
      "errorMessage": "Required field: Description",
      "errorCode": "REQUIRED_FIELD",
      "checkType": "BLOCKER",
      "property": "description",
      "expenseRecordId": "550e8400e29b41d4a716446655440001"
    }
  ],
  "reminderSentToApprover": false,
  "approverReminded": false,
  "hasExpenseViolations": false,
  "message": {
    "text": "Please attach the receipt for the hotel expense",
    "isAdminView": true
  },
  "hasRejectedExpenseRecords": false,
  "hasIncorrectApprovalChains": false,
  "approvalAllowed": true,
  "requiresNextStepApproverSelection": false,
  "currentApproverInfo": {
    "singleApprover": true,
    "hasIncorrectApprovalChains": false,
    "approvalChainId": "456e7890e89b12d3a456426614174999",
    "fullName": "Jane Smith",
    "email": "jane.smith@company.com"
  },
  "sendChain": {
    "isComplete": false,
    "senders": [
      {
        "status": "TRANSFER_TO_RECIPIENT",
        "recipient": {
          "id": "789e0123e89b12d3a456426614174888"
        },
        "sortOrder": 1,
        "collectReport": false,
        "recordInstances": [],
        "uniqueVoucherNumbers": [],
        "numberOfNonBookedExpenses": 0,
        "numberOfBookedExpenses": 0
      }
    ]
  },
  "tag": {
    "simulatedCardReport": false,
    "dimensions": {
      "project": "PROJ-001",
      "department": "Sales"
    }
  },
  "customFields": [
    {
      "fieldDefinitionId": "2b965c866b634698811dabf45a491089",
      "value": true
    }
  ]
}

Authorizations

Authorization

string

header

required

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

Path Parameters

organizationId

string

required

Unique identifier of the organization. String in UUID without dashes (32-character hex string) if access is done via values from Findity system otherwise, id of external system can be used

reportId

string

required

The unique identifier of the expense report. String, UUID format (32-character hexadecimal). Required. UUID without dashes (32-character hex string)

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

Query Parameters

action

enum<string>

Action to perform on the expense report instead of a field update. String, enum. Optional. Accepted values: reviewOk, clearTransactions, approve, reject, simulateBilling, sendReminder, setStatus, moveToNextStep, forwardToApprovalOrBooking, deleteExternalVoucherInfo. approve and reject submit an approval decision for the report's approval chain and require a request body holding approvalChainId. approve carries the per record decisions, so partial approvals are supported; reject rejects every expense record of the report unless explicit records are supplied. simulateBilling assigns a generated billing file reference to the report and to its card transactions, sets the due date to tomorrow and renames the report. It requires the adminApiExpenseReports:updateExpenseReport-simulateBilling permission and is intended as a developer and support tool. sendReminder reminds the owner of the report about it and takes an optional message in the request body. It requires the adminApiExpenseReports:updateExpenseReport-sendReminder permission, and only reports that carry an invoice reference can be reminded. setStatus moves the report to the status given in the request body. It is deprecated for plain status changes: send status in a field update (without action) instead, which does the same. It is still the way to return a report to its owner with messageText or returnToUser, and to set voucherNumber, errorText, bookingDate, sentToBookingDate or paidDate on a report that is already in the target status, for example to correct the voucher number of a SENT report or the paid date of a PAID report; a field update rejects these fields when status is unchanged. Changing the status of several reports at once, and moving reports to another recipient, is a separate operation: PUT /organizations/{organizationId}/reports?action=setStatus. deleteExternalVoucherInfo is deprecated and will be removed in a later release; use DELETE /organizations/{organizationId}/reports/{reportId}/externalvoucher instead, with recipientId as a query parameter instead of in the body. Until then it does the same as that endpoint and needs the same rights to modify reports, but answers 200 with the report. It clears the external voucher reference from the report and from every expense record in it. With recipientId in the request body, and if the report has a send chain, the voucher numbers of that recipient's step are cleared as well and a change log entry is written. A recipient of another organization is answered with 400 and nothing is cleared. moveToNextStep and forwardToApprovalOrBooking advance the report in its send chain. Both are restricted to the developer role and answer 403 for anyone else. Use PUT /organizations/{organizationId}/reports?action=moveToNextStep to advance several reports at once.

Available options:

reviewOk,

clearTransactions,

approve,

reject,

simulateBilling,

sendReminder,

setStatus,

moveToNextStep,

forwardToApprovalOrBooking,

deleteExternalVoucherInfo

Body

application/json

Option 1
Option 2
Option 3

Fields that can be updated on an expense report. status and the fields used together with it (voucherNumber, errorText, bookingDate, sentToBookingDate, paidDate) are applied in a field update and with action=setStatus, and ignored with any other action. Any other fields in the request body are silently ignored.

name

string

The display name of the expense report. String, maximum 255 characters.

comment

string

Comment on the expense report. String, unlimited characters. When action=approve or action=reject is used, this is instead stored as the comment on the approval decision.

customFields

object[]

Array of custom field values to set on the expense report. Each item must include a fieldDefinitionId and a value. Array of custom field objects.

Hide child attributes

customFields.fieldDefinitionId

string

UUID without dashes (32-character hex string)

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

customFields.value

any

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

expenseRecords

object[]

Array of bare expense record objects to include in this report. Exclude a record to to delete it from a report.

Hide child attributes

expenseRecords.id

string

status

string

Target lifecycle status of the report, case insensitive. String. Required when action=setStatus; in a field update it is optional and moves the report to this status the same way action=setStatus does. It is first compared with the current status: when it is equal it is ignored, whatever the status is, and the fields used together with it are rejected with 400 INVALID_PARAMETER. Ignored with any other action. Accepted values for a change are NEW, NORMAL, READY_TO_SEND, SENT and PAID; any other value, known lifecycle status or not, is rejected with 400 INVALID_PARAMETER, since the remaining statuses are reached through their own processing. The transition itself is not validated - the report is moved to the given status whatever its current one is, so the caller decides what makes sense.

voucherNumber

string

External voucher number to store on the report and its expense records. String, unlimited characters. Optional, only used together with a status change.

errorText

string

Error information to store on the report; the previous error status is cleared first. String, unlimited characters. Optional, only used together with a status change.

bookingDate

string<date-time>

Accounting booking date of the report, the date the report is booked on. Stored on the report itself and used when reports are exported and sorted by booking date. String, date-time format yyyy-MM-dd'T'HH:mm:ss with Z, ±hh:mm or ±hhmm and optional fractions of a second; a value that can't be parsed, such as a date without a time, is not rejected but treated as omitted. Optional, only used together with a status change for the SENT and PAID statuses. When omitted it defaults to the current time: always on a move to SENT, and on a move to PAID only when the report has no booking date yet.

sentToBookingDate

string<date-time>

Date the report was handed over to booking. Stored separately from bookingDate and passed on to the integration in the send chain payload. String, date-time format, parsed like bookingDate. Optional, only used together with a status change for the SENT and PAID statuses, and an omitted or unparseable value defaults the same way as for bookingDate.

paidDate

string<date-time>

Paid date to store on the report. String, date-time format, parsed like bookingDate. Optional, only used together with a status change for the PAID status; an omitted or unparseable value defaults to the current time.

messageText

string

Message sent to the report owner when the report is returned to the user. String, unlimited characters. Optional, only used with action=setStatus; sending it in a field update is answered with 400 INVALID_PARAMETER. Supplying it is enough to treat the change as a return to the owner when the target status is NEW or NORMAL, returnToUser does not have to be set as well.

returnToUser

boolean

Marks the status change as a return to the report owner. Boolean. Optional, only used with action=setStatus; sending it in a field update is answered with 400 INVALID_PARAMETER. Set it to notify the owner for any target status, or when moving to NEW or NORMAL without a messageText. It is redundant when messageText is given together with the NEW or NORMAL status, which already counts as a return.

approvalChainId

string

Id of the approval chain the decision applies to. String, UUID format (32-character hex). Required when action=approve or action=reject, ignored otherwise. Must belong to the report in the path.

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

rejectedExpenseRecords

object[]

Expense records to reject. Array of objects, optional. Only used with action=approve or action=reject. Every record of the report that is not listed here is approved, so an omitted or empty list approves the whole report; with action=reject an omitted list rejects every record of the report.

Hide child attributes

rejectedExpenseRecords.id

string

required

Id of the expense record to reject. String, UUID format (32-character hex). Required. Must belong to the report in the path.

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

rejectedExpenseRecords.rejectComment

string

Comment explaining why the record was rejected. String, unlimited characters. Optional.

nextStepApproverIds

string[]

Ids of the approvers to use for the next approval step. Array of strings, optional. Only relevant for action=approve when the approval section requires next step approvers to be chosen; the ids must be approver candidates of the next approval step.

Id of an approver. String, UUID format (32-character hex).

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

Response

comment

string

dateCreated

string

read-only

emailRecipients

string

expenseRecords

object[]

Hide child attributes

expenseRecords.id

string

expenseRecords.status

enum<string>

read-only

Available options:

NEW,

NORMAL,

APPROVAL,

APPROVED,

REJECTED

expenseRecords.personId

string

UUID without dashes (32-character hex string)

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

expenseRecords.dateCreated

string

read-only

expenseRecords.lastUpdated

string

read-only

expenseRecords.organizationId

string

UUID without dashes (32-character hex string)

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

expenseRecords.categoryId

string

UUID without dashes (32-character hex string)

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

expenseRecords.rejectComment

string

read-only

expenseRecords.expenseReportId

string

UUID without dashes (32-character hex string)

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

expenseRecords.reimbursement

number

read-only

expenseRecords.reimbursementCurrency

string

read-only

expenseRecords.meta

object

Hide child attributes

expenseRecords.meta.categoryIconUrl

string

Example:

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

string

lastUpdated

string

name

string

organizationId

string

UUID without dashes (32-character hex string)

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

personId

string

UUID without dashes (32-character hex string)

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

previewUrl

string

read-only

reportNumber

string

sent

string

read-only

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.

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.

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

processStatus

enum<string>

read-only

Available options:

DRAFT,

PROCESSING,

PROCESSED,

REJECTED

reimbursement

number

read-only

reimbursementCurrency

string

read-only

type

enum<string>

read-only

Available options:

AUTOMATIC,

MANUAL,

COMPANY_CARD

ownerName

string

firstName

string

First name of the expense report owner

lastName

string

Last name of the expense report owner

adminErrorInformation

string

Error information from admin operations

organizationName

string

organizationNumber

string

organizationLanguage

string

organizationUseNewDimensions

boolean

organizationRequiresAttestation

boolean

organizationUsesPaymentBasis

boolean

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

expenseRecordCount

integer

Number of expense records in this report

totalAmount

number

Total amount of all expense records in the report

userCanModifyReports

boolean

userCanSendReports

boolean

reportGroup

integer

onHoldStatus

object

read-only

On-hold status information

Hide child attributes

onHoldStatus.cards

object[]

List of active cards associated with the expense report

Hide child attributes

onHoldStatus.cards.bank

string

Bank identifier

onHoldStatus.cards.cardNumber

string

Card number (masked)

onHoldStatus.cardMissingConfig

object[]

List of cards missing configuration

Hide child attributes

onHoldStatus.cardMissingConfig.erId

string

Expense record ID

onHoldStatus.cardMissingConfig.bank

string

Bank identifier

onHoldStatus.cardMissingConfig.cardNumber

string

Card number (masked)

onHoldStatus.cardMissingConfig.cardExternalId

string

External card ID

onHoldStatus.transactionWithAuthStatus

string[]

List of expense record IDs with authorization status transactions

onHoldStatus.cardDeleted

object[]

List of deleted cards

Hide child attributes

onHoldStatus.cardDeleted.erId

string

Expense record ID

onHoldStatus.cardDeleted.bank

string

Bank identifier

onHoldStatus.cardDeleted.cardNumber

string

Card number (masked)

onHoldStatus.cardDeleted.cardExternalId

string

External card ID

onHoldStatus.allTransactionsEligibleForClearing

boolean

Whether all transactions are eligible for manual clearing

bank

string

Bank information for payment

dueDate

string<date-time>

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

cardNumber

string

Card number (masked)

invoiceRef

string

Invoice reference

invoiceNumber

string

Invoice number

invoiceDate

string<date-time>

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

externalVoucherNumber

string

External voucher number from integration

externalVoucherInformation

string

External voucher information

externalVoucherErrorInformation

string

Error information from external voucher system

externalVoucherId

string

External voucher ID

reminderSentToUser

boolean

Whether a reminder has been sent to the user

hasExpenseViolations

boolean

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

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

message.text

string

required

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

message.isAdminView

boolean

required

Whether the message was written from the admin view

approverReminded

boolean

Whether an approver has been reminded

reminderSentToApprover

boolean

deprecated

Deprecated, use approverReminded. Whether an approver has been reminded

employeeId

string

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

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

validationErrors.errorMessage

string

required

Translated, human-readable text of the error

validationErrors.errorCode

string

required

Code of the error, for example REQUIRED_FIELD

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

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.

validationErrors.expenseRecordId

string

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

hasRejectedExpenseRecords

boolean

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

hasIncorrectApprovalChains

boolean

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

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)

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)

currentApproverInfo

object

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

Hide child attributes

currentApproverInfo.singleApprover

boolean

Whether the report has a single approver

currentApproverInfo.hasIncorrectApprovalChains

boolean

Whether the report has incorrect approval chains

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.

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).

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).

sendChain

object

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

Hide child attributes

sendChain.isComplete

boolean

Whether every active step in the chain has been sent

sendChain.senders

object[]

List of senders in the chain

Hide child attributes

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.

sendChain.senders.recipient

object

The recipient this step sends to

Hide child attributes

sendChain.senders.recipient.id

string

Id of the recipient, the value the recipientId filter takes

sendChain.senders.recipient.integrationPluginName

string

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

sendChain.senders.sortOrder

integer

Position of this step in the chain, ascending

sendChain.senders.collectReport

boolean

Whether this step collects the report instead of sending it on

sendChain.senders.recordInstances

object[]

The per expense record send instances belonging to this step

Hide child attributes

sendChain.senders.recordInstances.id

string

External id of the record send instance

sendChain.senders.recordInstances.expenseRecordId

string

The expense record this instance belongs to

sendChain.senders.recordInstances.externalVoucherNumber

string

Voucher number the recipient booked the record under

sendChain.senders.recordInstances.externalVoucherId

string

The recipient's own id for the voucher

sendChain.senders.recordInstances.externalVoucherUrl

string

Link to the voucher in the recipient system

sendChain.senders.recordInstances.externalVoucherInformation

string

Message returned by the recipient for this record

sendChain.senders.recordInstances.externalVoucherErrorInformation

string

Error returned by the recipient for this record

sendChain.senders.recordInstances.bookingDate

string<date-time>

When the recipient booked the record

sendChain.senders.recordInstances.includedInRecipient

boolean

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

sendChain.senders.uniqueVoucherNumbers

string[]

Unique voucher numbers

sendChain.senders.numberOfNonBookedExpenses

integer

Number of non-booked expenses

sendChain.senders.numberOfBookedExpenses

integer

Number of booked expenses

sendChain.senders.aggregatedVoucherNumbers

string

Aggregated voucher numbers

sendChain.senders.aggregatedVoucherInformation

string

Aggregated voucher information

sendChain.senders.aggregatedVoucherErrorInformation

string

Aggregated voucher error information

tag

object

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

Hide child attributes

tag.simulatedCardReport

boolean | null

tag.integrationTest

boolean | null

Only returned to callers with the developer role.

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

tag.dimensions.{key}

any

Example:

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

meta

object

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

Hide child attributes

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

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

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

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

meta.autoApproval.reasons.description

string

required

The translated sentence shown for that reason.

customFields

object[]

Hide child attributes

customFields.fieldDefinitionId

string

UUID without dashes (32-character hex string)

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

customFields.value

any

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

⌘I

curl --request PUT \
  --url https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/reports/{reportId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Business Trip Stockholm",
  "comment": "Updated comment for the expense report",
  "expenseRecords": [
    {
      "id": "a73efe636a4d47359f3c28c3024b6d23"
    }
  ],
  "customFields": [
    {
      "fieldDefinitionId": "2b965c866b634698811dabf45a491089",
      "value": true
    }
  ]
}
'

{
  "id": "550e8400e29b41d4a716446655440000",
  "name": "Business Trip Stockholm",
  "personId": "123e4567e89b12d3a456426614174000",
  "organizationId": "550e8400e29b41d4a716446655440001",
  "dateCreated": "2024-01-15T09:30:00Z",
  "lastUpdated": "2024-01-16T14:45:00Z",
  "reportNumber": "ER-2024-001",
  "comment": "Business trip to Stockholm for client meeting",
  "emailRecipients": "manager@company.com;finance@company.com",
  "status": "APPROVAL",
  "processStatus": "PROCESSED",
  "type": "MANUAL",
  "reimbursement": 2580.5,
  "reimbursementCurrency": "SEK",
  "sent": "2024-01-16T10:00:00Z",
  "previewUrl": "https://expense.findity.com/api/expensereports/550e8400e29b41d4a716446655440000",
  "meta": {
    "autoApproval": {
      "status": "REJECTED",
      "reasons": [
        {
          "reason": "POLICY_FAILURE",
          "description": "Violates the company's expense policy."
        },
        {
          "reason": "WEEKEND_PURCHASE_DATE",
          "description": "The purchase was made during a weekend."
        }
      ]
    }
  },
  "expenseRecords": [
    {
      "id": "7f3c1a9e2b4d4e6f8a0b1c2d3e4f5a61",
      "status": "APPROVAL",
      "personId": "123e4567e89b12d3a456426614174000",
      "organizationId": "550e8400e29b41d4a716446655440001",
      "categoryId": "8a5f867e9b204742a8cc2ca2b6c57358",
      "expenseReportId": "550e8400e29b41d4a716446655440000",
      "dateCreated": "2024-01-15T09:30:00Z",
      "lastUpdated": "2024-01-16T14:45:00Z",
      "reimbursement": 1250,
      "reimbursementCurrency": "SEK",
      "meta": {
        "categoryIconUrl": "https://expense.findity.com/api/resources/8a5f867e9b204742a8cc2ca2b6c57358"
      }
    },
    {
      "id": "7f3c1a9e2b4d4e6f8a0b1c2d3e4f5a62",
      "status": "APPROVAL",
      "personId": "123e4567e89b12d3a456426614174000",
      "organizationId": "550e8400e29b41d4a716446655440001",
      "categoryId": "9b6f977f8c305753b9dd3db3c7d68469",
      "expenseReportId": "550e8400e29b41d4a716446655440000",
      "dateCreated": "2024-01-15T18:45:00Z",
      "lastUpdated": "2024-01-16T14:45:00Z",
      "reimbursement": 1330.5,
      "reimbursementCurrency": "SEK",
      "meta": {
        "categoryIconUrl": "https://expense.findity.com/api/resources/9b6f977f8c305753b9dd3db3c7d68469"
      }
    }
  ],
  "ownerName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "organizationName": "Acme Corporation",
  "organizationNumber": "556123-4567",
  "organizationLanguage": "en",
  "organizationUseNewDimensions": true,
  "organizationRequiresAttestation": false,
  "organizationUsesPaymentBasis": true,
  "expenseRecordCount": 2,
  "totalAmount": 2580.5,
  "userCanModifyReports": true,
  "userCanSendReports": true,
  "reportGroup": 1,
  "onHoldStatus": {
    "cards": [],
    "cardMissingConfig": [],
    "transactionWithAuthStatus": [],
    "cardDeleted": [],
    "allTransactionsEligibleForClearing": false
  },
  "bank": "SEB1234567890",
  "dueDate": "2024-01-25T00:00:00Z",
  "cardNumber": "**** **** **** 1234",
  "invoiceRef": "INV-2024-001",
  "invoiceNumber": "INV-2024-001",
  "invoiceDate": "2024-01-15T00:00:00Z",
  "reminderSentToUser": false,
  "employeeId": "EMP001",
  "validationErrors": [
    {
      "errorMessage": "Required field: Description",
      "errorCode": "REQUIRED_FIELD",
      "checkType": "BLOCKER",
      "property": "description",
      "expenseRecordId": "550e8400e29b41d4a716446655440001"
    }
  ],
  "reminderSentToApprover": false,
  "approverReminded": false,
  "hasExpenseViolations": false,
  "message": {
    "text": "Please attach the receipt for the hotel expense",
    "isAdminView": true
  },
  "hasRejectedExpenseRecords": false,
  "hasIncorrectApprovalChains": false,
  "approvalAllowed": true,
  "requiresNextStepApproverSelection": false,
  "currentApproverInfo": {
    "singleApprover": true,
    "hasIncorrectApprovalChains": false,
    "approvalChainId": "456e7890e89b12d3a456426614174999",
    "fullName": "Jane Smith",
    "email": "jane.smith@company.com"
  },
  "sendChain": {
    "isComplete": false,
    "senders": [
      {
        "status": "TRANSFER_TO_RECIPIENT",
        "recipient": {
          "id": "789e0123e89b12d3a456426614174888"
        },
        "sortOrder": 1,
        "collectReport": false,
        "recordInstances": [],
        "uniqueVoucherNumbers": [],
        "numberOfNonBookedExpenses": 0,
        "numberOfBookedExpenses": 0
      }
    ]
  },
  "tag": {
    "simulatedCardReport": false,
    "dimensions": {
      "project": "PROJ-001",
      "department": "Sales"
    }
  },
  "customFields": [
    {
      "fieldDefinitionId": "2b965c866b634698811dabf45a491089",
      "value": true
    }
  ]
}

Authentication

Findity Expense API

Findity Admin API

Findity Admin API V0

Findity Connect API

Update expense report for organization

Authorizations

Path Parameters

Query Parameters

Body

Response