Sub-Organizations

Create and manage isolated tenant organizations for each of your end clients, all from a single API key.

Overview

Partner accounts can programmatically create sub-organizations: fully isolated tenants, one per end client. Each sub-organization has its own documents, workflow runs, webhooks, and usage statistics, while billing is consolidated on your main organization's plan and credits.

Sub-organizations are headless: they have no users and no dashboard access. You operate them entirely through the API using your existing API key.

Acting on Behalf of a Sub-Organization

Every existing API endpoint (workflow runs, webhooks, usage, metrics) can target a sub-organization by adding the X-Organization-Id header to the request. Without the header, requests target your main organization.

curl -X POST "https://app.holofin.ai/api/v1.1/workflow-runs/" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "X-Organization-Id: org_01h2xcejqtf2nbrexx3vqjhp41" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "wf_...", "document_b64": "..."}'

The header accepts the sub-organization id in either form: the org_... identifier returned at creation, or the raw UUID. Targeting an organization that is not one of your sub-organizations (or one that has been deactivated) returns 404.

Workflow definitions are shared with your sub-organizations automatically: a run created on behalf of a sub-organization can reference any workflow defined on your main organization, in addition to the tenant's own (see Cloned Workflows). The run, its documents, and its usage are recorded on the sub-organization.

Create a Sub-Organization

Creates a new sub-organization. The new tenant is active immediately and inherits your organization's processing configuration (fraud detection, data retention period, and related settings).

Request Body

Example

curl -X POST "https://app.holofin.ai/api/v1.1/organizations" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Insurance", "external_ref": "crm-4821"}'

Response 201 Created (or 200 OK on an idempotent replay):

{
  "id": "org_01h2xcejqtf2nbrexx3vqjhp41",
  "name": "Acme Insurance",
  "external_ref": "crm-4821",
  "status": "active",
  "created_at": "2026-07-25T09:14:02.481930+00:00"
}

Cloned Workflows

By default, creating a sub-organization copies every published workflow from your main organization into the new tenant. The copies are independent: each sub-organization owns its own workflow ids, and editing one never affects your main organization or your other tenants, so each client can be tuned separately.

The copy is complete. Any classifier, segmenter, or extractor that belongs to your organization is copied alongside the workflow and re-linked to the tenant's version, so a sub-organization never depends on a definition it does not own. Shared Holofin agents are referenced as-is.

Cloned workflows keep the name and published version of the original but start with email ingestion disabled. Draft workflows are not copied.

Pass "clone_workflows": false to skip this and create an empty tenant. Runs created on its behalf still reference the workflows defined on your main organization, as described in Acting on Behalf of a Sub-Organization.

curl -X POST "https://app.holofin.ai/api/v1.1/organizations" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Insurance", "external_ref": "crm-4821", "clone_workflows": false}'

List Sub-Organizations

Returns all of your sub-organizations (active and inactive), oldest first.

{
  "organizations": [
    {
      "id": "org_01h2xcejqtf2nbrexx3vqjhp41",
      "name": "Acme Insurance",
      "external_ref": "crm-4821",
      "status": "active",
      "created_at": "2026-07-25T09:14:02.481930+00:00"
    }
  ]
}

Get a Sub-Organization

Fetches a single sub-organization by its org_... identifier or raw UUID.

Update a Sub-Organization

Updates the name and/or status of a sub-organization. Setting status to "inactive" immediately cuts API access to that tenant: subsequent requests using its X-Organization-Id return 404. Re-activate by setting status back to "active".

curl -X PATCH "https://app.holofin.ai/api/v1.1/organizations/org_01h2xcejqtf2nbrexx3vqjhp41" \
  -H "X-API-Key: $HOLOFIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Sub-organizations cannot be deleted through the API. Deactivate them instead; document retention and deletion follow the sub-organization's data retention settings.

Billing and Usage

• Consolidated billing
  Sub-organizations have no plan of their own. All processing draws on your main organization's subscription and credit balance, and appears on your invoice.
• Per-tenant usage tracking
  Usage is recorded per sub-organization. Call /api/v1.1/usage or /api/v1.1/metrics/volumes with the X-Organization-Id header to get per-tenant figures; without the header you get your main organization's own usage.
• Webhooks
  Webhook endpoints are registered per organization. Register endpoints for a sub-organization via /api/v1.1/webhooks with the X-Organization-Id header. Workflow-level events are delivered to the endpoints of the organization that owns the workflow definition.

Error Codes