Organizations

Key Concepts

An organization represents a company or entity within Findity. Each organization contains employees, expense categories, dimensions, and settings that control how expense management works for that entity.

Key properties of an organization include:

Property	Description
`externalSourceId`	A globally unique identifier from your external system, used to address the organization across API calls
`name`	Display name of the organization
`vat`	The organizational/company registration number
`className`	Always set to `com.findity.consumer.Company` when creating an organization
`address`	Postal address with `street1`, `city`, `postalCode`, `countryCode` (ISO 2-letter), and optionally `countryId`
`settings`	Configuration object including `templateOrganizationId`, `errorMailRecipient`, and feature toggles
`licenses`	License configuration for the organization
`partnerCode`	Partner code linking the organization to a partner

API Endpoints

All endpoints are available under the Admin API base URL:

https://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.

GET /organizations/

This returns an array of organization objects. Use this to discover organizations available to your API key.

Step 2 — Create or Update an Organization

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

POST /organizations/externalid/{externalId}/

Request Body Properties

Property	Type	Required	Description
`name`	string	Yes	Display name of the organization
`externalSourceId`	string	Yes	External identifier matching the `{externalId}` in the URL
`className`	string	Yes (create only)	Set to `com.findity.consumer.Company` when creating
`vat`	string	No	Company registration number
`partnerCode`	string	No	Partner code to associate organization with a partner
`address`	object	No	Address with `street1`, `city`, `postalCode`, `countryCode`, `countryId`
`settings`	object	No	Organization settings (see below)
`licenses`	object	No	License configuration

Settings Object

Property	Type	Description
`templateOrganizationId`	string	ID of the template organization to base a new organization on
`externallyActivated`	boolean	Whether the organization is externally activated
`errorMailRecipient`	string	Email address for error notifications
`ignoreMileageExpenseCategory`	boolean	Ignore mileage expense categories
`ignoreSubsistenceAllowanceCategory`	boolean	Ignore subsistence allowance categories
`forceNonDeductableVatOnCategories`	boolean	Force non-deductable VAT on categories
`recipient`	object	Recipient settings (e.g., `fortnoxAuthCode`)

Example: Create a New Organization

{
  "name": "Example Organization 2",
  "externalSourceId": "1234",
  "className": "com.findity.consumer.Company",
  "vat": "123456-1234",
  "partnerCode": "xxxx",
  "address": {
    "street1": "Example street",
    "city": "City",
    "postalCode": "-",
    "countryCode": "SE"
  },
  "settings": {
    "templateOrganizationId": "xxx",
    "errorMailRecipient": "[email protected]"
  }
}

Example: Update an Existing Organization

When updating, include only the fields you want to change. The className field is not required for updates.

{
  "name": "Updated Organization Name",
  "externalSourceId": "1234",
  "address": {
    "street1": "New street 1",
    "city": "New City",
    "postalCode": "12345",
    "countryCode": "SE"
  }
}

Step 3 — Get an Organization

Retrieve a single organization by its external ID.

GET /organizations/externalid/{externalId}/

Step 4 — Delete an Organization

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

DELETE /organizations/externalid/{externalId}/

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

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.

GET /organizations/externalid/lookup/?vat=123456-1234

Report Counters

Retrieve expense report statistics for an organization within a date range. Use the fromDate and toDate query parameters to filter.

GET /organizations/externalid/{externalId}/reportcounters/?fromDate=2024-01-01&toDate=2024-12-31

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 used during organization creation. It copies categories, dimensions, and other configuration from the template. Changing it after creation has no effect.

Next steps

Dimensions

Configure dimension fields and manage value lists.