Fields - Receipt expenses

Create and manage receipt-based expenses using the dynamic Fields system in the Expense API. Create receipt-based expenses using the dynamic Fields system. This guide covers uploading receipts with OCR, initializing fields, handling categories and tax, managing representation expenses, and saving.

Overview

Receipt expenses use the ReceiptVerification expense type. They represent standard purchases where a user submits a receipt for reimbursement — covering everything from office supplies and meals to travel costs and representation/entertainment. This is the most common expense type and has the most straightforward field structure, making it the recommended starting point for your Fields integration. The server handles tax calculations, VAT logic, and country-specific rules — your client renders the fields and lets the user fill them in.

Key concepts

Concept	Description
OCR scanning	Upload a receipt image before creating the expense. The API extracts amount, tax, currency, date, and suggests categories — pre-filling the form.
Categories	Each organization defines expense categories (e.g., Travel, Meals, Office supplies). Changing the category can alter which fields are visible.
Tax / VAT	Tax fields are calculated server-side based on category, country, and amount. Your client displays them but doesn’t compute them.
Representation	Entertainment/representation expenses have additional fields: guest lists, purpose, and representation type. These appear dynamically when the category requires it.
Content	Receipt images and PDF attachments are uploaded separately via the Content API and referenced by ID in the fields.

API endpoints

Operation	Method	Endpoint
Upload receipt (with OCR)	`POST`	`/v1/expense/content?action=scan&organizationId={id}`
Upload receipt (without OCR)	`POST`	`/v1/expense/content?organizationId={id}`
Initialize fields	`GET`	`/v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/fields`
Update fields	`PUT`	`/v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/fields`
Create expense	`POST`	`/v1/expense/expenses?format=fields&organizationId={id}&expenseType=ReceiptVerification`
Update expense	`PUT`	`/v1/expense/expenses/{expenseId}?format=fields`
Get categories	`GET`	`/v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/categories`
Get currencies	`GET`	`/v1/expense/me/organizations/{id}/currencies`
Get payment types	`GET`	`/v1/expense/me/organizations/{id}/paymenttypes`
Retrieve receipt image	`GET`	`/v1/expense/content/{id}/image?size={width}x{height}`

Step 1: Upload the receipt

Upload the receipt image before initializing fields. Use action=scan to trigger OCR, which extracts data that can pre-fill the expense form.

bash

curl -X POST "https://stage-api.findity.com/api/v1/expense/content?action=scan&organizationId={orgId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: image/jpeg" \
  -H "Content-Name: receipt.jpg" \
  --data-binary @receipt.jpg

Example response

{
  "id": "ff808181826e28b201826e56fc980005",
  "name": "receipt.jpg",
  "contentType": "image/jpeg",
  "scanResult": {
    "id": "ff808181826e28b201826e5700e30006",
    "amount": 350.00,
    "taxAmount": 70.00,
    "currency": "SEK",
    "purchaseDate": "2024-03-15T00:00:00Z",
    "categoryIds": [
      "a1b2c3d4e5f6",
      "b2c3d4e5f6a1"
    ],
    "categoryId": "a1b2c3d4e5f6"
  }
}

Scan result fields

Field	Type	Description
`id`	string	Scan result ID — pass to fields initialization and category lookup
`amount`	number	Extracted total amount
`taxAmount`	number	Extracted tax/VAT amount
`currency`	string	Detected currency code
`purchaseDate`	string	Detected purchase date (ISO 8601)
`categoryIds`	string[]	Up to 3 suggested category IDs, ordered by confidence
`categoryId`	string	Top suggested category ID (convenience shorthand for `categoryIds[0]`)

Not all fields are guaranteed in a scan result — OCR accuracy depends on receipt quality. Always let the user review and correct pre-filled values.

Step 2: Initialize fields

Fetch the field structure for a new receipt expense:

bash

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

To apply scan results, first initialize the fields with GET, then apply the scan result via PUT:

bash

curl -X PUT "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensetypes/ReceiptVerification/fields?applyScanResult={scanResultId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [...fields from GET response...] }'

To load an existing expense for editing:

bash

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

Field structure overview

The response contains these key fields:

Field property	controlType	Description
`id`	`TEXT`	Expense ID (hidden, system field)
`categoryId`	`LIST`	Expense category — `requiresUpdate: true`
`verification.comment`	`MULTI_LINE_TEXT`	User comment
`verification.description`	`TEXT`	Expense description
`expenseReportId`	`LIST`	Assign to an expense report
`verification.receiptAttachment`	`CONTENT_HOLDER`	Receipt image or PDF attachment
`verification.purchaseDate`	`DATE`	Date of purchase — `requiresUpdate: true`
`verification.currencyCode`	`LIST`	Transaction currency — `requiresUpdate: true`
`verification.totalAmount`	`DOUBLE`	Total amount including tax (shown as “Amount incl. VAT”)
`verification.taxAmount`	`DOUBLE`	Tax / VAT amount
`verification.paymentTypeId`	`LIST`	Payment method (cash, corporate card, etc.)
`verification.verificationNumber`	`TEXT`	System-generated verification number (read-only)
`verification.storeName`	`TEXT`	Store or merchant name
`verification.exchangeRate`	`DOUBLE`	Exchange rate (appears when foreign currency selected)
Custom dimension fields	`LIST`	Organization-specific dimensions (e.g., cost center, project)

Step 3: Handle categories and tax

The category field (categoryId) has requiresUpdate: true. Changing the category triggers a server round-trip that can:

Show or hide tax fields based on the category’s tax rules
Reveal representation fields (guest list, purpose) for entertainment categories
Change which custom dimensions are visible
Update VAT calculation logic

Fetching categories

GET /v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/categories

Example response

{
  "meta": { "count": 5, "total": 5 },
  "data": [
    {
      "id": "a1b2c3d4e5f6",
      "name": "Travel",
      "iconUrl": "https://expense.findity.com/api/resources/...",
      "section": "Common"
    },
    {
      "id": "b2c3d4e5f6a1",
      "name": "Meals & Entertainment",
      "iconUrl": "https://expense.findity.com/api/resources/...",
      "section": "Representation"
    }
  ]
}

Categories may include a section property for grouping in the UI.

Category suggestions from scan

If you used OCR scanning in Step 1, pass the scanResultId when fetching categories to highlight 0–3 suggested categories in the picker:

GET /v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/categories?scanResultId={scanResultId}

Suggested categories are returned with a suggested: true flag. Display them prominently so the user can quickly confirm or change the pre-selected category.

Tax fields

Tax-related fields appear based on the selected category and country. Common tax fields include:

Field property	controlType	Description
`verification.taxAmount`	`DOUBLE`	Tax / VAT amount — may be auto-calculated
`verification.nonDeductibleVat`	`DOUBLE`	Non-deductible VAT portion
`verification.taxPercentage`	`LIST`	Tax rate selector (where applicable)

Tax fields are computed server-side. When the user changes totalAmount, currencyCode, or categoryId, send a PUT to get recalculated tax values. Never compute tax client-side — rules vary by country, category, and organization settings.

Step 4: Handle currency and exchange rates

When a user selects a foreign currency (different from the organization’s reimbursement currency), additional exchange rate fields appear:

Field property	controlType	Description
`verification.currencyCode`	`LIST`	Transaction currency — `requiresUpdate: true`
`verification.exchangeRate`	`DOUBLE`	Exchange rate to reimbursement currency

The currencyCode field has requiresUpdate: true — changing it triggers a server round-trip that fetches the current exchange rate. The reimbursement amount is calculated at the expense record level (not within the verification object) and returned as reimbursementAmount on the expense itself.

Fetching currencies

GET /v1/expense/me/organizations/{id}/currencies

Returns the list of currencies available in the organization. The data property on the currencyCode field contains the currently selected currency.

Step 5: Handle representation expenses

When a category requires representation/entertainment details, additional fields appear dynamically after the category is selected:

Field property	controlType	Description
`verification.representation.type`	`LIST`	Type of representation (internal, external, etc.) — `requiresUpdate: true`
`verification.representation.guests`	`GUEST_LIST`	List of guests with name and company
`verification.representation.numberOfGuests`	`INTEGER`	Total number of guests
`verification.representation.numberOfExternalGuests`	`INTEGER`	Number of external guests
`verification.representation.place`	`TEXT`	Place or venue name
`verification.representation.includesLiquor`	`SWITCH`	Whether liquor/wine/strong beer was included
`verification.representation.guestListAttached`	`SWITCH`	Whether to attach a guest list file — `requiresUpdate: true`
`verification.representation.guestListAttachment`	`CONTENT_HOLDER`	Attached guest list PDF or document

Guest list format

The GUEST_LIST control type holds an array of guest objects:

[
  { "name": "Jane Smith", "company": "Acme Corp" },
  { "name": "John Doe", "company": "Example Ltd" }
]

Representation types

Fetch representation types for the selected category:

GET /v1/expense/me/organizations/{id}/representationtypes

The verification.representation.type field has requiresUpdate: true — changing it may alter visibility of other representation fields based on the organization’s configuration.

Step 6: The update cycle

Receipt expenses have several fields with requiresUpdate: true. When the user changes any of these, send the full fields array back to the server:

PUT /v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/fields

Fields that trigger an update:

Field	What changes on update
`categoryId`	Tax rules, visible dimensions, representation fields, VAT logic
`verification.currencyCode`	Exchange rate, reimbursement amount
`verification.totalAmount`	Tax recalculation (in some configurations)
`verification.representation.type`	Representation field visibility
`verification.paymentTypeId`	Reimbursement-related fields

Example update request

bash

curl -X PUT "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensetypes/ReceiptVerification/fields" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      { "property": "id", "value": null },
      { "property": "categoryId", "value": "a1b2c3d4e5f6" },
      { "property": "verification.receiptAttachment", "value": "ff808181826e28b201826e56fc980005" },
      { "property": "verification.purchaseDate", "value": "2024-03-15T00:00:00Z" },
      { "property": "verification.currencyCode", "value": "SEK" },
      { "property": "verification.totalAmount", "value": 350.00 },
      { "property": "verification.taxAmount", "value": 70.00 },
      { "property": "verification.paymentTypeId", "value": "CASH" },
      { "property": "verification.comment", "value": "Office supplies for Q1 planning" }
    ]
  }'

Always send the complete fields array — including hidden fields and fields you didn’t modify. The server uses the full state to compute the response.

Step 7: Save the expense

Once the user has filled in all required fields, save the receipt expense.

Using fields format (recommended)

Create:

POST /v1/expense/expenses?format=fields&organizationId={id}&expenseType=ReceiptVerification

Update:

PUT /v1/expense/expenses/{expenseId}?format=fields

Send the full fields payload as the request body in both cases.

Using standard JSON format

Alternatively, extract values from the fields and use the standard expense format:

bash

curl -X POST "https://stage-api.findity.com/api/v1/expense/expenses" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ff808181963979e20196397a2098004b",
    "categoryId": "a1b2c3d4e5f6",
    "verification": {
      "type": "ReceiptVerification",
      "purchaseDate": "2024-03-15T00:00:00Z",
      "amount": 350.00,
      "taxAmount": 70.00,
      "currency": "SEK",
      "paymentTypeId": "a7384ac0d3dc45bf9d15f8de343cf612",
      "comment": "Office supplies for Q1 planning",
      "receiptAttachment": {
        "id": "ff808181826e28b201826e56fc980005"
      }
    }
  }'
``

### Example response

```json
{
  "id": "8a2b4c6d8e0f1a2b3c4d5e6f7a8b9c0d",
  "organizationId": "ff808181963979e20196397a2098004b",
  "personId": "ff808181963979e20196397a119f002d",
  "status": "NORMAL",
  "processStatus": "DRAFT",
  "categoryId": "a1b2c3d4e5f6",
  "reimbursementCurrency": "SEK",
  "reimbursementAmount": 350.00,
  "dateCreated": "2024-03-15T10:30:00Z",
  "lastUpdated": "2024-03-15T10:30:00Z",
  "verification": {
    "type": "ReceiptVerification",
    "purchaseDate": "2024-03-15T00:00:00Z",
    "amount": 350.00,
    "taxAmount": 70.00,
    "currency": "SEK",
    "paymentTypeId": "a7384ac0d3dc45bf9d15f8de343cf612",
    "comment": "Office supplies for Q1 planning",
    "receiptAttachment": {
      "id": "ff808181826e28b201826e56fc980005"
    }
  },
  "meta": {
    "abbreviation": {
      "reimbursementDescription": "350.00 SEK",
      "dateDescription": "15 Mar 2024"
    },
    "capabilities": {
      "canBeEdited": true,
      "canBeDeleted": true,
      "canBeSentIn": true,
      "canBeMerged": false
    }
  }
}

Receipt attachments

The verification.receiptAttachment field uses the CONTENT_HOLDER control type. It stores the content ID from the upload step.

Uploading additional attachments

Some expenses support multiple attachments. Upload each file separately and reference the IDs:

bash

curl -X POST "https://stage-api.findity.com/api/v1/expense/content?organizationId={orgId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/pdf" \
  -H "Content-Name: invoice.pdf" \
  --data-binary @invoice.pdf

Retrieving receipt images

Fetch receipt images at a specific size for display in your UI:

GET /v1/expense/content/{id}/image?size=400x400

The API resizes the image to fit within the specified dimensions while preserving aspect ratio.

Supported file types

Type	Content-Type	Notes
JPEG	`image/jpeg`	Most common for phone camera receipts
PNG	`image/png`	Screenshots and scanned documents
PDF	`application/pdf`	Invoices and formal documents

The maximum file size is controlled by the organization’s expenseReceiptMaxSize setting (in MB). Check this value from the organization’s settings object to validate file size client-side before uploading.

Card transaction expenses

When an organization has card integrations, card transactions can be automatically converted into receipt expenses. These appear as draft expenses with the card transaction data pre-filled. Card transaction expenses include:

Pre-filled amount, currency, and date from the transaction
A reference to the card transaction ID
meta.capabilities.canBeMerged: true if the expense can be merged with a manually created expense

The user reviews the pre-filled data, attaches a receipt, selects a category, and submits — the same fields flow as a regular receipt expense.

Common integration patterns

Scan-first expense creation

The recommended flow for receipt expenses is scan-first: upload the receipt with action=scan, then initialize fields with GET and apply the scan result via PUT. This pre-fills amount, tax, currency, date, and suggests categories — reducing manual entry to selecting the correct category and confirming values.

POST /v1/expense/content?action=scan&organizationId={id}
→ Extract scanResult.id and content id
GET /v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/fields
→ Initial field structure
PUT /v1/expense/me/organizations/{id}/expensetypes/ReceiptVerification/fields?applyScanResult={scanResultId}
→ Fields pre-filled with OCR data

Handling foreign currency expenses

When the user selects a currency different from the organization’s reimbursement currency, the exchange rate and reimbursement amount fields appear automatically after the requiresUpdate round-trip. Display the reimbursement amount prominently so the user knows the final amount they’ll receive. The exchange rate is pre-filled from Findity’s rate service but can be manually overridden if the organization allows it.

Email-based expense creation

Organizations can configure an expense email address (available in the organization’s settings.expenseEmail). Receipts forwarded to this email are automatically created as draft expenses with OCR scanning applied. These appear in the user’s draft list with the receipt already attached and data pre-filled.

Rendering the receipt alongside the form

Display the receipt image next to the expense form so users can reference it while filling in details. Fetch the image using the content ID from the verification.receiptAttachment field:

GET /v1/expense/content/{contentId}/image?size=600x800

On mobile, show the receipt as a tappable thumbnail that opens a full-screen viewer.

Handling rejected expenses

When a receipt expense is rejected, load it with the fields endpoint using expenseRecordId. The response includes an INFORMATION field with informationType: error containing the approver’s rejection comment. Display this prominently at the top of the form so the user knows what to fix before resubmitting.

Error handling

Common errors when working with receipt expenses:

Status code	Error code	Description
`400`	`INVALID_JSON_BODY`	Failed to parse the request body. Verify your JSON payload.
`400`	`INVALID_JSON_PROPERTY_VALUE`	Missing or invalid `type` on verification — ensure `type` is set to `ReceiptVerification`.
`400`	`NOT_A_RECEIPT_VERIFICATION_CATEGORY`	The category ID is not valid for receipt expenses. Fetch categories for `ReceiptVerification`.
`400`	`CONTENT_NOT_FOUND`	The referenced content ID does not exist. Verify the receipt was uploaded successfully.
`400`	`CONTENT_TOO_BIG`	The uploaded file exceeds the max size.
`400`	`TOTAL_AMOUNT_REQUIRED`	Total amount is missing. Ensure `verification.totalAmount` has a value.
`404`	`EXPENSE_RECORD_NOT_FOUND`	The expense ID does not exist or is not accessible by the current user.
`404`	`CATEGORY_NOT_FOUND`	The specified category does not exist in the organization.

Home

MCP Server

API Basics

Guides

Fields - Receipt expenses

Overview

Key concepts

API endpoints

Step 1: Upload the receipt

Example response

Scan result fields

Step 2: Initialize fields

Field structure overview

Step 3: Handle categories and tax

Fetching categories

Example response

Category suggestions from scan

Tax fields

Step 4: Handle currency and exchange rates

Fetching currencies

Step 5: Handle representation expenses

Guest list format

Representation types

Step 6: The update cycle

Example update request

Step 7: Save the expense

Using fields format (recommended)

Using standard JSON format

Receipt attachments

Uploading additional attachments

Retrieving receipt images

Supported file types

Card transaction expenses

Common integration patterns

Error handling

Next steps

​Overview

​Key concepts

​API endpoints

​Step 1: Upload the receipt

​Example response

​Scan result fields

​Step 2: Initialize fields

​Field structure overview

​Step 3: Handle categories and tax

​Fetching categories

​Example response

​Category suggestions from scan

​Tax fields

​Step 4: Handle currency and exchange rates

​Fetching currencies

​Step 5: Handle representation expenses

​Guest list format

​Representation types

​Step 6: The update cycle

​Example update request

​Step 7: Save the expense

​Using fields format (recommended)

​Using standard JSON format

​Receipt attachments

​Uploading additional attachments

​Retrieving receipt images

​Supported file types

​Card transaction expenses

​Common integration patterns

​Error handling

​Next steps

Overview

Key concepts

API endpoints

Step 1: Upload the receipt

Example response

Scan result fields

Step 2: Initialize fields

Field structure overview

Step 3: Handle categories and tax

Fetching categories

Example response

Category suggestions from scan

Tax fields

Step 4: Handle currency and exchange rates

Fetching currencies

Step 5: Handle representation expenses

Guest list format

Representation types

Step 6: The update cycle

Example update request

Step 7: Save the expense

Using fields format (recommended)

Using standard JSON format

Receipt attachments

Uploading additional attachments

Retrieving receipt images

Supported file types

Card transaction expenses

Common integration patterns

Error handling

Next steps