Organizations

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

List user organizations

Retrieve all organizations the authenticated user belongs to.

GET /v1/expense/me/organizations

Query parameters

Example request

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": "[email protected]",
        "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

Query parameters

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.

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://..." }
  ]
}

Categories

Retrieve expense categories for a specific expense type. Categories can include suggestions when a scanResultId is provided.

GET /v1/expense/me/organizations/{id}/expensetypes/{expenseType}/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.

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

Error handling

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

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.

Next steps