Organizations

Retrieve user organizations, permissions, and configuration from the Expense API Retrieve the organizations a user belongs to and access organization-level configuration such as expense types, categories, currencies, and permissions — all scoped to the authenticated user.

Overview

In the Expense API, organizations are accessed through the user context (/me/organizations). Unlike the Admin API where you manage organizations directly, the Expense API returns only the organizations the authenticated user is a member of, along with their permissions, design settings, and support configuration. This is typically the first call after authenticating a user — the organization ID is required for nearly every subsequent Expense API call.

Key concepts

Concept	Description
Permissions	Each organization includes a `meta.permissions` object that controls what the user can do (create expenses, approve, send reports, etc.)
Design	Organizations carry branding configuration (colors, logos) that you can use to white-label your UI
Settings	Organization-level settings like booking country, receipt size limits, and support configuration
Expense types	Each organization defines which expense types are available (receipts, mileage, per diem, food benefits)

List user organizations

Retrieve all organizations the authenticated user belongs to.

GET /v1/expense/me/organizations

Query parameters

Parameter	Type	Description
`include`	string	Optional properties to include: `settings`, `design`, `meta.permissions`
`searchText`	string	Free text search to filter organizations by name
`max`	integer	Max records to return (default: 10, max: 1000)
`offset`	integer	Pagination offset (default: 0)

Example request

bash

curl -X GET "https://stage-api.findity.com/api/v1/expense/me/organizations?include=settings,design,meta.permissions" \
  -H "Authorization: Bearer {access_token}"

Example response

{
  "meta": {
    "count": 2,
    "total": 2
  },
  "data": [
    {
      "id": "11adfe2a080040e3892ffb89c21ec44e",
      "name": "Example Ltd.",
      "meta": {
        "permissions": {
          "canAddCard": true,
          "canViewExpenses": true,
          "canApprove": false,
          "canCreateExpense": true,
          "canCreateReport": false,
          "canSendExpenses": true,
          "canSendReports": false,
          "canDeleteAccount": false
        }
      },
      "design": {
        "accentColor": "#9cd8c4",
        "logoUrl": "https://expense.findity.com/api/resources/ff808181442fd363..."
      },
      "settings": {
        "bookingCountry": "SE",
        "reportMaxNumberOfExpenses": 10,
        "expenseReceiptMaxSize": 5,
        "expenseEmail": "test@findity.com",
        "supportSettings": {
          "type": "url-dialog",
          "title": "Support",
          "value": "https://support.findity.com"
        }
      }
    }
  ]
}

Get a single organization

Retrieve details for a specific organization.

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

Path parameters

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	The organization ID

Query parameters

Parameter	Type	Description
`include`	string	Optional properties: `settings`, `design`, `meta.permissions`

Permissions reference

The meta.permissions object controls which actions the user can perform within an organization. Always check these before rendering action buttons in your UI.

Permission	Description
`canViewExpenses`	User can view expenses (i.e., is an employee of the organization)
`canCreateExpense`	User can create new expenses
`canCreateReport`	User can create expense reports
`canSendExpenses`	User can send individual expenses
`canSendReports`	User can send expense reports for approval
`canApprove`	User can approve expenses in this organization
`canAddCard`	User can connect payment cards
`canDeleteAccount`	User is allowed to delete their account

Organization sub-resources

Once you have an organization ID, you can access its configuration. These endpoints return the data needed to populate dropdowns, validate input, and render expense forms.

Expense types

Retrieve the expense types available in the organization. Use this to determine which types of expenses a user can create.

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

{
  "meta": { "count": 4, "total": 4 },
  "data": [
    { "type": "ReceiptVerification", "name": "Expense", "iconUrl": "https://..." },
    { "type": "CarSpecification", "name": "Mileage", "iconUrl": "https://..." },
    { "type": "SubsistenceAllowance", "name": "Subsistence allowance", "iconUrl": "https://..." },
    { "type": "FoodBenefitsSpecification", "name": "Food benefit", "iconUrl": "https://..." }
  ]
}

Parameter	Type	Description
`expenseType`	string	One of: `ReceiptVerification`, `CarSpecification`, `SubsistenceAllowance`, `FoodBenefitsSpecification`
`scanResultId`	string (uuid)	Optional. A scan result ID to get 0-3 suggested categories

Currencies

Retrieve available currencies for the organization.

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

Payment types

Retrieve available payment types (e.g., cash, corporate card, private card).

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

Countries

Retrieve the list of countries available in the organization.

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

Custom field lists

Retrieve values for a custom field list (used for custom dimensions like cost center, project, etc.).

GET /v1/expense/me/organizations/{id}/lists/{listkey}

Chart of accounts

Search the organization’s chart of accounts.

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

Policy documents

Retrieve a policy document for the organization.

GET /v1/expense/me/organizations/{id}/policies/documents/{documentId}

Common integration patterns

Pattern 1: Organization selector

If a user belongs to multiple organizations, present an organization selector at startup and store the selected ID for subsequent API calls.

GET /v1/expense/me/organizations?include=meta.permissions,design

Use the design object (logo, accent colors) to visually distinguish organizations and the permissions object to show/hide features in your UI.

Pattern 2: Cache organization configuration

Categories, currencies, payment types, and other list data change infrequently. Cache these per organization and refresh periodically rather than fetching on every form render.

Resource	Suggested cache duration
Expense types	24 hours
Categories	24 hours
Currencies	24 hours
Payment types	24 hours
Permissions	Per session

Pattern 3: Permission-driven UI

Build your UI conditionally based on the user’s permissions:

const org = await getOrganization(orgId);
const permissions = org.meta.permissions;

// Only show "New expense" button if user can create expenses
if (permissions.canCreateExpense) {
  showCreateExpenseButton();
}

// Only show approval tab if user is an approver
if (permissions.canApprove) {
  showApprovalTab();
}

// Only show "Send" action on reports if allowed
if (permissions.canSendReports) {
  showSendReportAction();
}

Integration best practices

Cache sub-resource data per organization

Expense types, categories, currencies, and payment types rarely change. Fetch them once per session (or cache for up to 24 hours) and store them keyed by organization ID. This avoids redundant API calls when users navigate between expense forms.

Handle multi-organization users

Users can belong to multiple organizations, each with different permissions, expense types, and configurations. Always prompt for organization selection when meta.total > 1, and reload all sub-resource data when the user switches organizations.

Use include parameters to reduce payload size

Only request the data you need. For an organization selector screen, include=design,meta.permissions is sufficient. Skip settings unless you need to display support information or enforce receipt size limits.

Respect settings constraints in your UI

The settings object contains values your UI should enforce — such as expenseReceiptMaxSize (max upload size in MB) and reportMaxNumberOfExpenses (max expenses per report). Validate these client-side before making API calls to avoid unnecessary errors.

Error handling

The API uses standard HTTP status codes. Handle these common scenarios when working with organization endpoints:

Status code	Error code	Description
`400`	`INVALID_ORGANIZATION_ID`	The organization ID format is invalid. Verify you’re using the correct `id` from the list organizations response.
`401`	`UNAUTHORIZED`	The access token is missing, expired, or invalid. Refresh the token and retry.
`403`	`FORBIDDEN`	The user does not have access to this organization. Re-fetch the user’s organizations to verify membership.
`404`	`ORGANIZATION_NOT_FOUND`	The organization does not exist or the user is no longer a member. Prompt the user to select a different organization.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Implement exponential backoff and consider caching sub-resource responses.

Example error response

{
  "error": {
    "code": "INVALID_ORGANIZATION_ID",
    "description": "The provided organization ID is not valid."
  }
}

When a user receives a 403 or 404 on an organization they previously had access to, their membership may have been revoked. Refresh the organizations list and redirect to the organization selector.

Home

MCP Server

API Basics

Guides

Overview

Key concepts

List user organizations

Query parameters

Example request

Example response

Get a single organization

Path parameters

Query parameters

Permissions reference

Organization sub-resources

Expense types

Categories

Currencies

Payment types

Countries

Custom field lists

Chart of accounts

Policy documents

Common integration patterns

Pattern 1: Organization selector

Pattern 2: Cache organization configuration

Pattern 3: Permission-driven UI

Integration best practices

Error handling

Example error response

Next steps

​Overview

​Key concepts

​List user organizations

​Query parameters

​Example request

​Example response

​Get a single organization

​Path parameters

​Query parameters

​Permissions reference

​Organization sub-resources

​Expense types

​Categories

​Currencies

​Payment types

​Countries

​Custom field lists

​Chart of accounts

​Policy documents

​Common integration patterns

​Pattern 1: Organization selector

​Pattern 2: Cache organization configuration

​Pattern 3: Permission-driven UI

​Integration best practices

​Error handling

​Example error response

​Next steps

Overview

Key concepts

List user organizations

Query parameters

Example request

Example response

Get a single organization

Path parameters

Query parameters

Permissions reference

Organization sub-resources

Expense types

Categories

Currencies

Payment types

Countries

Custom field lists

Chart of accounts

Policy documents

Common integration patterns

Pattern 1: Organization selector

Pattern 2: Cache organization configuration

Pattern 3: Permission-driven UI

Integration best practices

Error handling

Example error response

Next steps