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

1. Complete Admin API — Getting started 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

API endpoints

All endpoints are available under the Admin API base URL:

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

The following operations are available:

Required headers

Include these headers with every request:

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

Settings object

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

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

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

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:

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:

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, dimensions, 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.

📘

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

Next steps