Fields - Per diem expenses

Create per diem and subsistence allowance expenses using the dynamic Fields system. This guide covers travel routes with multiple stops, destination-based rules, meal and accommodation deductions, and the complex update cycle that ties it all together.

Overview

Per diem expenses use the SubsistenceAllowance expense type. They represent daily allowances for business travel — covering meals, accommodation, and incidental costs based on the destination country, trip duration, and applicable deductions.

This is the most complex expense type in Findity. The server manages country-specific per diem rates, time-based allowance calculations, deduction rules for provided meals and accommodation, and multi-stop travel itineraries. Your client renders the fields and handles the add/remove stop interactions — the server does all the computation.

Key concepts

API endpoints

All per diem field operations use the standard Fields endpoints with expenseType=SubsistenceAllowance:

Step 1: Initialize fields

Fetch the field structure for a new per diem expense:

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

To load an existing per diem expense for editing:

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

Field structure overview

The response contains these top-level fields:

The bulk of the complexity lives inside verification.travelRoute.

Step 2: Understand the travel route structure

The verification.travelRoute field group is the core of a per diem expense. It contains a dynamic set of nested field groups representing the travel itinerary.

Route structure

A per diem travel route consists of:

Travel Route (FIELD_GROUP)
├── Departure (FIELD_GROUP)
│   ├── Departure date/time (LOCAL_DATE_TIME)
│   └── Destination (LIST)
├── Stop 1 (FIELD_GROUP) — optional, repeatable
│   ├── Departure date/time (LOCAL_DATE_TIME)
│   ├── Destination (LIST)
│   └── Deductions (FIELD_GROUP)
│       ├── Breakfast (SWITCH)
│       ├── Lunch (SWITCH)
│       ├── Dinner (SWITCH)
│       └── Accommodation (LIST or SWITCH)
├── Stop 2 (FIELD_GROUP) — optional, repeatable
│   └── ...
└── Return (FIELD_GROUP)
    └── Return date/time (LOCAL_DATE_TIME)

Departure fields

The departure group defines where and when the trip starts:

Return fields

The return group defines when the trip ends:

Deduction fields

Each travel stop (and potentially the overall trip) includes deduction toggles:

📘

Deduction fields have requiresUpdate: true because toggling them triggers a server-side recalculation of the per diem allowance. The accommodation field can be either a SWITCH (provided/not provided) or a LIST (type of accommodation) depending on the country's rules.

The LOCAL_DATE_TIME control type

Per diem uses LOCAL_DATE_TIME instead of DATE_TIME. Values are formatted as yyyy-MM-dd HH:mm without timezone information:

{ "property": "verification.departureDateTime", "controlType": "LOCAL_DATE_TIME", "value": "2024-06-10 08:30" }

This represents the traveler's local time at the point of departure — not UTC. The server uses these local times to calculate trip duration and determine which per diem rates apply.

Step 3: Manage travel stops

Travel stops allow users to create multi-destination itineraries. Each stop represents a change of destination during the trip, potentially with different per diem rates and deduction rules.

Adding a stop

The travel route field group includes commands for adding stops:

{
  "commands": [
    {
      "text": "Add stop",
      "confirmationRequired": false,
      "command": "action=addStop&afterIndex=0"
    }
  ]
}

Execute the command by appending it to the PUT URL:

curl -X PUT "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensetypes/SubsistenceAllowance/fields?action=addStop&afterIndex=0" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "fields": [...full fields array...] }'

The server responds with an updated fields structure that includes a new stop field group inserted at the specified position.

Removing a stop

Each intermediate stop has a deleteCommand that removes it:

{
  "property": "verification.travelStops[0]",
  "controlType": "FIELD_GROUP",
  "deletable": true,
  "deleteCommand": {
    "text": "Remove stop",
    "confirmationRequired": true,
    "confirmation": "Are you sure you want to remove this stop?",
    "command": "action=removeStop&index=0"
  }
}

Execute by appending the command to the PUT URL:

PUT /v1/expense/me/organizations/{id}/expensetypes/SubsistenceAllowance/fields?action=removeStop&index=0

⚠️

When confirmationRequired is true, display the confirmation text in a dialog before executing the command. Removing a stop deletes all associated deduction data.

Stop field structure

Each travel stop contains its own set of fields:

Step 4: Handle destinations

The destination field determines which country-specific per diem rates and rules apply. Each leg of the trip can have a different destination.

Fetching destinations

GET /v1/expense/me/organizations/{id}/expensetypes/SubsistenceAllowance/destinations

Destinations are typically countries, but some countries have region-specific rates (e.g., different rates for major cities vs. the rest of the country).

Example response

{
  "meta": { "count": 3, "total": 195 },
  "data": [
    { "id": "SE", "name": "Sweden" },
    { "id": "NO", "name": "Norway" },
    { "id": "DE", "name": "Germany" }
  ]
}

Changing a destination has requiresUpdate: true because it can:

• Change the per diem daily rate
• Alter which deduction fields are visible
• Modify the accommodation field type (SWITCH vs. LIST)
• Update the allowance calculation

Step 5: The update cycle

Per diem expenses have the most active update cycle of all expense types. Nearly every meaningful user interaction triggers a server round-trip:

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

Fields that trigger updates

Example update request

curl -X PUT "https://stage-api.findity.com/api/v1/expense/me/organizations/{orgId}/expensetypes/SubsistenceAllowance/fields" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      { "property": "id", "value": null },
      { "property": "categoryId", "value": "c3d4e5f6a1b2" },
      { "property": "verification.travelRoute", "fields": [
        { "property": "verification.departureDateTime", "value": "2024-06-10 08:30" },
        { "property": "verification.destination", "value": "DE" },
        { "property": "verification.returnDateTime", "value": "2024-06-12 18:00" },
        { "property": "verification.deduction.breakfast", "value": true },
        { "property": "verification.deduction.lunch", "value": false },
        { "property": "verification.deduction.dinner", "value": false },
        { "property": "verification.deduction.accommodation", "value": "OWN" }
      ]}
    ]
  }'

⚠️

Always send the complete fields array — including hidden fields, all travel stops, and fields you didn't modify. The server uses the full state to compute the per diem allowance.

Calculated output fields

After each update, the server returns calculated fields that you display as read-only:

These fields typically have disabled: true — display them to the user but don't allow editing.

Step 6: Handle the summary

The travel route FIELD_GROUP includes a summary array that provides a compact preview of the trip:

{
  "summary": [
    { "type": "property_value", "property": "Destination", "value": "Germany" },
    { "type": "property_value", "property": "Departure", "value": "10 Jun 2024 08:30" },
    { "type": "property_value", "property": "Return", "value": "12 Jun 2024 18:00" },
    { "type": "property_value", "property": "Allowance", "value": "1,250.00 SEK" }
  ]
}

Use the summary to display a collapsed view of the travel route — particularly useful in list views or when the route field group is minimized.

Step 7: Save the expense

Once all stops, destinations, and deductions are configured, save the per diem expense.

Using fields format (recommended)

Create:

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

Update:

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

Send the full fields payload as the request body.

Using standard JSON 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": "c3d4e5f6a1b2",
    "verification": {
      "type": "SubsistenceAllowance",
      "comment": "Business trip to Berlin",
      "departureDateTime": "2024-06-10 08:30",
      "returnDateTime": "2024-06-12 18:00",
      "destination": "DE",
      "travelStops": [],
      "deductions": {
        "breakfast": [true, false],
        "lunch": [false, false],
        "dinner": [false, true],
        "accommodation": "OWN"
      }
    }
  }'

Example response

{
  "id": "9f3a5b7c1d2e4f6a8b0c2d4e6f8a0b2c",
  "organizationId": "ff808181963979e20196397a2098004b",
  "personId": "ff808181963979e20196397a119f002d",
  "status": "NORMAL",
  "processStatus": "DRAFT",
  "categoryId": "c3d4e5f6a1b2",
  "reimbursementCurrency": "SEK",
  "reimbursementAmount": 1250.00,
  "dateCreated": "2024-06-10T09:15:00Z",
  "lastUpdated": "2024-06-10T09:15:00Z",
  "verification": {
    "type": "SubsistenceAllowance",
    "comment": "Business trip to Berlin",
    "departureDateTime": "2024-06-10 08:30",
    "returnDateTime": "2024-06-12 18:00",
    "destination": "DE",
    "travelStops": []
  },
  "meta": {
    "abbreviation": {
      "reimbursementDescription": "1,250.00 SEK",
      "dateDescription": "10–12 Jun 2024"
    },
    "capabilities": {
      "canBeEdited": true,
      "canBeDeleted": true,
      "canBeSentIn": true
    }
  }
}

Multi-stop trips

For trips with multiple destinations, each leg has its own per diem rate and deduction configuration.

Example: Three-country trip

A trip from Stockholm → Berlin → Paris → Stockholm:

Travel Route
├── Departure: 2024-06-10 08:30
│   └── Destination: Germany
├── Stop 1: 2024-06-12 09:00
│   └── Destination: France
│   └── Deductions: Lunch provided
└── Return: 2024-06-14 20:00

Each leg uses the destination's per diem rate for the duration of that leg. The server calculates partial-day allowances for the first and last days based on departure and arrival times.

Building the fields payload for multi-stop

{
  "fields": [
    { "property": "id", "value": null },
    { "property": "categoryId", "value": "c3d4e5f6a1b2" },
    { "property": "verification.travelRoute", "fields": [
      { "property": "verification.departureDateTime", "value": "2024-06-10 08:30" },
      { "property": "verification.destination", "value": "DE" },
      { "property": "verification.travelStops", "fields": [
        { "property": "verification.travelStops[0]", "fields": [
          { "property": "verification.travelStops[0].departureDateTime", "value": "2024-06-12 09:00" },
          { "property": "verification.travelStops[0].destination", "value": "FR" },
          { "property": "verification.travelStops[0].deduction.breakfast", "value": false },
          { "property": "verification.travelStops[0].deduction.lunch", "value": true },
          { "property": "verification.travelStops[0].deduction.dinner", "value": false },
          { "property": "verification.travelStops[0].deduction.accommodation", "value": "OWN" }
        ]}
      ]},
      { "property": "verification.returnDateTime", "value": "2024-06-14 20:00" },
      { "property": "verification.deduction.breakfast", "value": false },
      { "property": "verification.deduction.lunch", "value": false },
      { "property": "verification.deduction.dinner", "value": false },
      { "property": "verification.deduction.accommodation", "value": "OWN" }
    ]}
  ]
}

Country-specific behavior

Per diem rules vary significantly by country. The Fields system abstracts this complexity, but understanding the differences helps when building your UI:

📘

You don't need to implement these rules. The server handles all country-specific logic through the Fields update cycle. This table is provided for context when testing and debugging per diem calculations.

INFORMATION fields

Per diem expenses frequently include INFORMATION fields that display calculated summaries, warnings, or regulatory notes:

{
  "property": "verification.perDiemInfo",
  "controlType": "INFORMATION",
  "informationType": "information",
  "value": "Per diem rate for Germany: 420 SEK/day. Trip qualifies for 2.5 days.",
  "visible": true,
  "dismissible": false
}

Render these based on the informationType:

Common integration patterns

Error handling

Common errors when working with per diem expenses:

Next steps