> ## Documentation Index
> Fetch the complete documentation index at: https://developer.findity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 bash theme={"system"}
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

```json theme={"system"}
{
  "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
```

```json theme={"system"}
{
  "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
```

| 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:

```javascript theme={"system"}
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

<Accordion title="Always fetch permissions on login" icon="fa-shield-halved">
  Call `GET /v1/expense/me/organizations?include=meta.permissions` immediately after authentication. Store the permissions object in your app state and use it to conditionally render UI elements. Never assume a user has a specific permission — organizations can configure these independently.
</Accordion>

<Accordion title="Cache sub-resource data per organization" icon="fa-database">
  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.
</Accordion>

<Accordion title="Handle multi-organization users" icon="fa-building">
  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.
</Accordion>

<Accordion title="Use include parameters to reduce payload size" icon="fa-filter">
  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.
</Accordion>

<Accordion title="Respect settings constraints in your UI" icon="fa-gear">
  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.
</Accordion>

## 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

```json theme={"system"}
{
  "error": {
    "code": "INVALID_ORGANIZATION_ID",
    "description": "The provided organization ID is not valid."
  }
}
```

<Info>
  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.
</Info>

## Next steps

<Cards>
  <Card title="Fields system" href="/docs/getting-started-with-expense-api#step-3-the-fields-system" icon="fa-list-check">
    Learn how to initialize and render dynamic expense forms using the Fields system
  </Card>

  <Card title="Expense types" href="/reference/get-organization-expense-types" icon="fa-receipt">
    See the full API reference for expense types
  </Card>

  <Card title="Categories" href="/reference/get-organization-categories" icon="fa-tags">
    See the full API reference for categories
  </Card>

  <Card title="Approvals" href="/docs/getting-started-with-expense-api#step-6-admin--approver-views" icon="fa-check-double">
    Learn how to build approval workflows using organization context
  </Card>
</Cards>