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 and Dimensions 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

Complete Admin API — Getting started to obtain an access token with Admin API access.
Note your partnerCode — required when creating a new organization.
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/

cURL

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

{
  "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

cURL

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

{
  "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.

cURL

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

{
  "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}/

cURL

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

{
  "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}/

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

cURL

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

{
  "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

cURL

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

{
  "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/

cURL

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

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

Call GET /organizations/externalid/lookup/?vat={vat} to check if the organization already exists.
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.
After creation, set up users, dimensions, and other configuration.

Syncing from ERP

To keep organization data in sync with your ERP:

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

Retrieving report statistics

To generate billing or usage reports:

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

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.

Home

MCP Server

API Basics

Guides

Overview

Prerequisites

Key concepts

API endpoints

Required headers

Step 1 — List organizations

Step 2 — Create or update an organization

Request body properties

Settings object

Example: Create a new organization

Example: Update an existing organization

Step 3 — Get an organization

Step 4 — Delete an organization

Lookup organization by VAT

Report counters

Common integration patterns

Onboarding new organizations

Syncing from ERP

Retrieving report statistics

Error handling

Next steps

​Overview

​Prerequisites

​Key concepts

​API endpoints

​Required headers

​Step 1 — List organizations

​Step 2 — Create or update an organization

​Request body properties

​Settings object

​Example: Create a new organization

​Example: Update an existing organization

​Step 3 — Get an organization

​Step 4 — Delete an organization

​Lookup organization by VAT

​Report counters

​Common integration patterns

​Onboarding new organizations

​Syncing from ERP

​Retrieving report statistics

​Error handling

​Next steps

Overview

Prerequisites

Key concepts

API endpoints

Required headers

Step 1 — List organizations

Step 2 — Create or update an organization

Request body properties

Settings object

Example: Create a new organization

Example: Update an existing organization

Step 3 — Get an organization

Step 4 — Delete an organization

Lookup organization by VAT

Report counters

Common integration patterns

Onboarding new organizations

Syncing from ERP

Retrieving report statistics

Error handling

Next steps