Fields - Receipt expenses

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

API endpoints

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.

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

💡

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.

Category suggestions from scan

Pass the scanResultId when fetching categories to receive 0–3 suggested categories:

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

Suggested categories are returned with a suggested: true flag. Display them prominently in your category picker.

Step 2: Initialize fields

Fetch the field structure for a new receipt expense:

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 during initialization, pass the applyScanResult parameter:

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

To load an existing expense for editing:

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:

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.

Tax fields

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

📘

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:

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:

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:

Example update request

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:

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:

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

⚠️

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

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

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

Error handling

Common errors when working with receipt expenses:

Next steps