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

Create, retrieve, update, and delete organizations.

This guide walks through the full lifecycle of an organization — from checking whether one already exists, creating it from your external system, and keeping it in sync via upsert, through to deletion. All operations use the `externalSourceId` field as the stable identifier, so you never need to store a Findity-internal `id` in your system. Read this guide alongside [Users](/docs/users-new) and [Dimensions](/docs/dimensions-new) to complete a full onboarding flow.

## Overview

An **organization** sits at the core of Findity's data model. Each organization contains employees, expense categories, dimensions, and settings. Organizations are grouped under a **partner**, which is managed by a **client application** (your integration's identity in Findity).

The `POST /organizations/externalid/{externalId}/` endpoint behaves as an **upsert**: if no organization with that `externalSourceId` exists it is created; if one already exists it is updated. This means you can run the same payload on a nightly schedule without risk of duplicates.

Use `externalSourceId` — the identifier from your ERP or HR system — as the primary key throughout. Findity assigns its own internal `id`, but you should never need to store or use it.

## Prerequisites

1. Complete [Admin API — Getting started](/docs/getting-started-with-admin-api) to obtain an access token with Admin API access.
2. Note your `partnerCode` — required when creating a new organization.
3. Note the `templateOrganizationId` of your default template organization (ask your Findity contact if unsure).

## Key concepts

| Concept | Description |
| - | - |
| **Organization** | A company or entity within Findity. Each one contains employees, expense categories, dimensions, and settings. |
| **`externalSourceId`** | A globally unique identifier from your external system. Used to address the organization in every API call without needing Findity's internal `id`. |
| **`name`** | Display name of the organization. |
| **`vat`** | The company registration number (org.nr). |
| **`className`** | The type of organization. Always set to `com.findity.consumer.Company` when creating. Not needed on updates. |
| **`address`** | Postal address with `street1`, `city`, `postalCode`, and `countryCode` (ISO 3166-1 alpha-2). |
| **`settings`** | Configuration object including `templateOrganizationId`, `errorMailRecipient`, and feature toggles. |
| **`partnerCode`** | Partner code linking the organization to a partner. Required on creation. |

## API endpoints

All endpoints are available under the Admin API base URL:

```
https://stage-expense.findity.com/api/admin
```

The following operations are available:

| Operation | Method | Endpoint |
| - | - | - |
| List organizations | `GET` | `/organizations/` |
| Get organization by external ID | `GET` | `/organizations/externalid/{externalId}/` |
| Create or update organization | `POST` | `/organizations/externalid/{externalId}/` |
| Delete organization | `DELETE` | `/organizations/externalid/{externalId}/` |
| Lookup organization by VAT | `GET` | `/organizations/externalid/lookup/?vat={vat}` |
| Get report counters | `GET` | `/organizations/externalid/{externalId}/reportcounters/` |

### Required headers

Include these headers with every request:

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `X-Findity-ApiVersion` | `3` |
| `Authorization` | `Bearer {access_token}` |

## Step 1 — List organizations

Retrieve all organizations the current API user is administrating. Use this to discover available organizations or to iterate over all of them when aggregating statistics.

HTTP

```
GET /organizations/
```

```sh cURL theme={"system"}
curl -X GET "https://stage-expense.findity.com/api/admin/organizations/" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}"
```

```json JSON theme={"system"}
{
  "organizations": [
    {
      "id": "4f2a3b1c",
      "externalSourceId": "EXT-ORG-001",
      "name": "Acme Sverige AB",
      "vat": "556123-4567",
      "status": "NORMAL",
      "address": {
        "street1": "Kungsgatan 12",
        "city": "Stockholm",
        "postalCode": "111 35",
        "countryCode": "SE"
      }
    }
  ],
  "serverTime": "2026-05-22T08:00:00Z"
}
```

## Step 2 — Create or update an organization

Create a new organization or update an existing one by sending a `POST` request with the `externalSourceId` as the path parameter.

HTTP

```
POST /organizations/externalid/{externalId}/
```

### Request body properties

| Property | Type | Required | Description |
| - | - | - | - |
| `name` | string | Required (create); optional (update) | Display name of the organization. |
| `externalSourceId` | string | Required | External identifier. Must match the `{externalId}` in the URL. |
| `className` | string | Required (create only) | Set to `com.findity.consumer.Company` when creating. Not needed on updates. |
| `vat` | string | Optional | Company registration number. |
| `partnerCode` | string | Required (create) | Partner code to associate the organization with a partner. |
| `address` | object | Optional | Address with `street1`, `city`, `postalCode`, and `countryCode` (ISO 3166-1 alpha-2). |
| `settings` | object | Optional | Organization settings (see below). |

### Settings object

| Property | Type | Description |
| - | - | - |
| `templateOrganizationId` | string | ID of the template organization. Applied only during creation — supplying it on an update has no effect. |
| `externallyActivated` | boolean | Whether the organization is externally activated. |
| `errorMailRecipient` | string | Email address for error notifications. |
| `recipient` | object | Recipient settings, e.g. `{ "fortnoxAuthCode": "..." }` to connect a Fortnox accounting recipient. |

### Example: Create a new organization

```sh cURL theme={"system"}
curl -X POST "https://stage-expense.findity.com/api/admin/organizations/externalid/EXT-ORG-001/" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "name": "Acme Sverige AB",
    "externalSourceId": "EXT-ORG-001",
    "className": "com.findity.consumer.Company",
    "vat": "556123-4567",
    "partnerCode": "partner-se",
    "address": {
      "street1": "Kungsgatan 12",
      "city": "Stockholm",
      "postalCode": "111 35",
      "countryCode": "SE"
    },
    "settings": {
      "templateOrganizationId": "tmpl-se-001",
      "errorMailRecipient": "admin@acme.se"
    }
  }'
```

```json JSON theme={"system"}
{
  "id": "4f2a3b1c",
  "externalSourceId": "EXT-ORG-001",
  "name": "Acme Sverige AB",
  "vat": "556123-4567",
  "status": "NORMAL",
  "address": {
    "street1": "Kungsgatan 12",
    "city": "Stockholm",
    "postalCode": "111 35",
    "countryCode": "SE"
  },
  "settings": {
    "errorMailRecipient": "admin@acme.se"
  }
}
```

### Example: Update an existing organization

When updating, include only the fields you want to change. The `className` and `partnerCode` fields are not required for updates.

```sh cURL theme={"system"}
curl -X POST "https://stage-expense.findity.com/api/admin/organizations/externalid/EXT-ORG-001/" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "externalSourceId": "EXT-ORG-001",
    "name": "Acme Sverige AB (Updated)",
    "address": {
      "street1": "Drottninggatan 5",
      "city": "Gothenburg",
      "postalCode": "411 03",
      "countryCode": "SE"
    }
  }'
```

```json JSON theme={"system"}
{
  "id": "4f2a3b1c",
  "externalSourceId": "EXT-ORG-001",
  "name": "Acme Sverige AB (Updated)",
  "vat": "556123-4567",
  "status": "NORMAL",
  "address": {
    "street1": "Drottninggatan 5",
    "city": "Gothenburg",
    "postalCode": "411 03",
    "countryCode": "SE"
  }
}
```

## Step 3 — Get an organization

Retrieve a single organization by its external ID.

HTTP

```
GET /organizations/externalid/{externalId}/
```

```sh cURL theme={"system"}
curl -X GET "https://stage-expense.findity.com/api/admin/organizations/externalid/EXT-ORG-001/" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}"
```

```json JSON theme={"system"}
{
  "id": "4f2a3b1c",
  "externalSourceId": "EXT-ORG-001",
  "name": "Acme Sverige AB",
  "vat": "556123-4567",
  "status": "NORMAL",
  "address": {
    "street1": "Kungsgatan 12",
    "city": "Stockholm",
    "postalCode": "111 35",
    "countryCode": "SE"
  },
  "settings": {
    "errorMailRecipient": "admin@acme.se"
  }
}
```

## Step 4 — Delete an organization

Delete an organization by its external ID. This operation is irreversible.

HTTP

```
DELETE /organizations/externalid/{externalId}/
```

> [!NOTE]
>
> Deleting an organization removes all associated data including employees, expense reports, and settings. This
> action cannot be undone.

```sh cURL theme={"system"}
curl -X DELETE "https://stage-expense.findity.com/api/admin/organizations/externalid/EXT-ORG-001/" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}"
```

```json JSON theme={"system"}
{
  "result": "success",
  "description": "Organization deleted"
}
```

## Lookup organization by VAT

Search for an organization using its VAT/registration number. This is useful for checking whether an organization already exists before creating a new one.

HTTP

```
GET /organizations/externalid/lookup/?vat=556123-4567
```

```sh cURL theme={"system"}
curl -X GET "https://stage-expense.findity.com/api/admin/organizations/externalid/lookup/?vat=556123-4567" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}"
```

The response `result` field has three possible values:

| Value | Meaning |
| - | - |
| `FOUND` | Organization exists and belongs to this client application. `externalSourceId` is included in the response. |
| `FOUND_IN_OTHER_CA` | Organization exists but was created by a different client application. |
| `NOT_FOUND` | No organization with this VAT exists. Safe to create. |

```json JSON theme={"system"}
{
  "result": "FOUND",
  "id": "4f2a3b1c",
  "externalSourceId": "EXT-ORG-001",
  "status": "NORMAL"
}
```

## Report counters

Retrieve expense report statistics for an organization within a date range. Both `fromDate` and `toDate` are optional — omitting them returns counters for all time. Use ISO 8601 date format (`YYYY-MM-DD`).

HTTP

```
GET /organizations/externalid/{externalId}/reportcounters/
```

```sh cURL theme={"system"}
curl -X GET "https://stage-expense.findity.com/api/admin/organizations/externalid/EXT-ORG-001/reportcounters/?fromDate=2026-01-01&toDate=2026-12-31" \
  -H "Content-Type: application/json" \
  -H "X-Findity-ApiVersion: 3" \
  -H "Authorization: Bearer {access_token}"
```

```json JSON theme={"system"}
{
  "organization": {
    "id": "4f2a3b1c",
    "externalSourceId": "EXT-ORG-001",
    "name": "Acme Sverige AB"
  },
  "counts": {
    "UNSUBMITTED": 3,
    "SUBMITTED": 1,
    "APPROVED": 5,
    "BOOKED": 12
  }
}
```

## Common integration patterns

### Onboarding new organizations

When onboarding a new organization from your external system:

1. Call `GET /organizations/externalid/lookup/?vat={vat}` to check if the organization already exists.
2. If it does not exist, call `POST /organizations/externalid/{externalId}/` with `className` set to `com.findity.consumer.Company` and a `templateOrganizationId` in `settings` to inherit configuration from a template.
3. After creation, set up [users](/docs/users-new), [dimensions](/docs/dimensions-new), and other configuration.

### Syncing from ERP

To keep organization data in sync with your ERP:

1. Call `POST /organizations/externalid/{externalId}/` on a schedule (e.g., nightly) for each organization.
2. Include only the fields that may have changed — the endpoint performs an upsert, creating or updating as needed.
3. Use the same `externalSourceId` as your ERP's identifier to maintain a consistent mapping.

### Retrieving report statistics

To generate billing or usage reports:

1. Call `GET /organizations/` to list all organizations.
2. For each organization, call `GET /organizations/externalid/{externalId}/reportcounters/` with the desired date range.
3. Aggregate the counters across organizations as needed.

> [!NOTE]
>
> **The `templateOrganizationId` setting is only applied during organization creation. It copies categories, dimensions, and other configuration from the template. Supplying it on an update request has no effect.**

## Error handling

| Status code | Description |
| - | - |
| `400` | Invalid request body or constraint violation. Check field types and required fields. A duplicate `vat` value on an existing organization also returns `400`. |
| `401` | Token missing or expired. Re-authenticate and retry. |
| `403` | Insufficient permissions for this organization or operation. |
| `404` | No organization found for the given `externalId`. |
| `429` | Rate limit exceeded. Apply exponential backoff. |

## Next steps

> **[Dimensions](/docs/admin-api-dimensions)**
>
> Configure dimension fields and manage value lists.

> **[Users](/docs/admin-api-users)**
>
> Add, update, and remove employees from an organization.

> **[Charts of accounts](/docs/admin-api-charts-of-accounts)**
>
> Map expense categories to accounting numbers.

> **[Dimensions](\{LINK_TO_DIMENSIONS_REFERENCE})**
>
> Configure dimension fields and manage value lists.