Organization Tree

Endpointhttps://api.kontier.eu/v1

List the organizations below this one

GET

https://api.kontier.eu/v1

/organization/children

The direct children of the caller's organization, keyset-paged over (created_at, id). Each row carries the kind and origin of the edge that put it there.

List the organizations below this one › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

after_created_at

string · date-time

Keyset cursor: the created_at of the last row of the previous page.

after_id

string

Keyset cursor: the id of the last row of the previous page.

List the organizations below this one › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List the organizations below this one › Responses

object · required

GET/organization/children

curl --request GET \
  --url https://api.kontier.eu/v1/organization/children

shell

Example Responses

{
  "data": {
    "children": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "depth": 0,
        "edge_kind": "customer",
        "edge_origin": "edge_origin",
        "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "identity_mode": "identity_mode",
        "name": "name",
        "restriction": "none",
        "signup_email": "signup_email",
        "slug": "slug",
        "status": "status"
      }
    ],
    "next_after_created_at": "2024-08-25T15:00:00Z",
    "next_after_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Add an affiliate organization

POST

https://api.kontier.eu/v1

/organization/children/affiliates

Creates an organization below the caller's with an AFFILIATE edge — part of the same business rather than a customer of it — and invites its first admin. The parent's tree.children_allowed and tree.max_children settings gate it. The admin address is required and the request is refused with 422 without one, naming admin_email: an organization nobody can enter is not a tenant. An API key may create one too — the invitation is then credited to the platform's provisioning identity, while the audit trail records your key as what created it.

Add an affiliate organization › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Add an affiliate organization › Request Body

admin_email

string · email · required

Who is invited into the new organization. Required: an organization nobody can enter is not a tenant.

name

string · minLength: 1 · maxLength: 200 · required

The affiliate's display name.

default_currency

string

Defaults to the parent's.

default_locale

string

Defaults to the parent's.

object

The new organization's legal identity: legal name, registered address, identifiers, tax registrations and bank account. Validated whole before anything is written; every refusal names its field under identity.*, and nothing is created when one is refused. Optional: what is missing is reported by the organization's compliance readiness, never refused.

slug

string · maxLength: 100

Optional; derived from the name when omitted.

Add an affiliate organization › Responses

Created

object · required

POST/organization/children/affiliates

curl --request POST \
  --url https://api.kontier.eu/v1/organization/children/affiliates \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "admin_email": "test@example.com",
  "default_currency": "default_currency",
  "default_locale": "default_locale",
  "identity": {
    "bank": {
      "account_name": "account_name",
      "bic": "bic",
      "iban": "iban"
    },
    "identifiers": [
      {
        "country": "DE",
        "kind": "DE_USTIDNR",
        "value": "DE123456789"
      }
    ],
    "legal_address": {
      "city": "city",
      "country": "country",
      "line1": "line1",
      "line2": "line2",
      "postal_code": "postal_code",
      "state": "state"
    },
    "legal_name": "Beispiel Software GmbH",
    "main_email": "hello@example.com",
    "phone": "+49 30 1234567",
    "registrations": [
      {
        "country": "AT",
        "identifier": "ATU12345678",
        "scheme": "VAT",
        "valid_from": "2026-07-01"
      }
    ]
  },
  "name": "name",
  "slug": "slug"
}
'

shell

Example Request Body

{
  "admin_email": "test@example.com",
  "default_currency": "default_currency",
  "default_locale": "default_locale",
  "identity": {
    "bank": {
      "account_name": "account_name",
      "bic": "bic",
      "iban": "iban"
    },
    "identifiers": [
      {
        "country": "DE",
        "kind": "DE_USTIDNR",
        "value": "DE123456789"
      }
    ],
    "legal_address": {
      "city": "city",
      "country": "country",
      "line1": "line1",
      "line2": "line2",
      "postal_code": "postal_code",
      "state": "state"
    },
    "legal_name": "Beispiel Software GmbH",
    "main_email": "hello@example.com",
    "phone": "+49 30 1234567",
    "registrations": [
      {
        "country": "AT",
        "identifier": "ATU12345678",
        "scheme": "VAT",
        "valid_from": "2026-07-01"
      }
    ]
  },
  "name": "name",
  "slug": "slug"
}

json

Example Responses

{
  "data": {
    "admin_invited": true,
    "child": {
      "created_at": "2024-08-25T15:00:00Z",
      "depth": 0,
      "edge_kind": "customer",
      "edge_origin": "edge_origin",
      "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "identity_mode": "identity_mode",
      "name": "name",
      "restriction": "none",
      "signup_email": "signup_email",
      "slug": "slug",
      "status": "status"
    },
    "seed_failed": [
      "string"
    ]
  }
}

json

application/json

Provision a child organization from a subscription

POST

https://api.kontier.eu/v1

/organization/children/from-subscription

The same business-idempotent saga the subscription.activated consumer drives. Replaying converges on ONE organization. The plan must carry metadata.auto_provision_tenant; nothing provisions without it.

Provision a child organization from a subscription › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Provision a child organization from a subscription › Request Body

source_subscription_id

string · uuid · required

An ACTIVE subscription in this organization's live workspace, on a plan carrying metadata.auto_provision_tenant.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

source_delivery_id

string · uuid

This delivery's id. Derived from the subscription when omitted.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

source_event_id

string · uuid

The outbound envelope's idempotency key. Derived from the subscription when omitted.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

Provision a child organization from a subscription › Responses

Created

object · required

POST/organization/children/from-subscription

curl --request POST \
  --url https://api.kontier.eu/v1/organization/children/from-subscription \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "source_delivery_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "source_event_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "source_subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "source_delivery_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "source_event_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "source_subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "admin_invited": true,
    "child": {
      "created_at": "2024-08-25T15:00:00Z",
      "depth": 0,
      "edge_kind": "customer",
      "edge_origin": "edge_origin",
      "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "identity_mode": "identity_mode",
      "name": "name",
      "restriction": "none",
      "signup_email": "signup_email",
      "slug": "slug",
      "status": "status"
    },
    "replayed": true,
    "seed_failed": [
      "string"
    ]
  }
}

json

application/json

Get every organization below this one

GET

https://api.kontier.eu/v1

/organization/children/subtree

Every organization below the caller's, at any depth, shallowest first — the caller's own organization is not among them. Each row carries its depth in the whole tree, so a client can render the shape. This is what /organization/children answers for direct children only.

Get every organization below this one › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get every organization below this one › Responses

array | null · required

Get one organization below this one

GET

https://api.kontier.eu/v1

/organization/children/{id}

Where the organization sits: its parent, its ancestors root first, the kind of its edge and its depth. An id that is not below the caller's organization answers 404.

Get one organization below this one › path Parameters

id

string · required

Get one organization below this one › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get one organization below this one › Responses

object · required

GET/organization/children/{id}

curl --request GET \
  --url https://api.kontier.eu/v1/organization/children/:id

shell

Example Responses

{
  "data": {
    "ancestors": [
      {
        "created_at": "2024-08-25T15:00:00Z",
        "depth": 0,
        "edge_kind": "customer",
        "edge_origin": "edge_origin",
        "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "identity_mode": "identity_mode",
        "name": "name",
        "restriction": "none",
        "signup_email": "signup_email",
        "slug": "slug",
        "status": "status"
      }
    ],
    "depth": 0,
    "organization": {
      "created_at": "2024-08-25T15:00:00Z",
      "depth": 0,
      "edge_kind": "customer",
      "edge_origin": "edge_origin",
      "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "identity_mode": "identity_mode",
      "name": "name",
      "restriction": "none",
      "signup_email": "signup_email",
      "slug": "slug",
      "status": "status"
    }
  }
}

json

application/json

Change why a child hangs where it does

PUT

https://api.kontier.eu/v1

/organization/children/{id}/edge-kind

Flips the edge between customer and affiliate. The same kind is refused. Becoming a customer needs a customer row in the parent for this organization; the parent and the ancestor path are never touched.

Change why a child hangs where it does › path Parameters

id

string · required

Change why a child hangs where it does › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Change why a child hangs where it does › Request Body

edge_kind

string · enum · required

The kind to flip TO. The same kind is refused.

Enum values:

customer

affiliate

Change why a child hangs where it does › Responses

object · required

PUT/organization/children/{id}/edge-kind

curl --request PUT \
  --url https://api.kontier.eu/v1/organization/children/:id/edge-kind \
  --header 'Content-Type: application/json' \
  --data '
{
  "edge_kind": "customer"
}
'

shell

Example Request Body

{
  "edge_kind": "customer"
}

json

Example Responses

{
  "data": {
    "created_at": "2024-08-25T15:00:00Z",
    "depth": 0,
    "edge_kind": "customer",
    "edge_origin": "edge_origin",
    "edge_source_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "identity_mode": "identity_mode",
    "name": "name",
    "restriction": "none",
    "signup_email": "signup_email",
    "slug": "slug",
    "status": "status"
  }
}

json

application/json

Invite an admin into a child organization

POST

https://api.kontier.eu/v1

/organization/children/{id}/invitations

Writes the admin role-intent row and dispatches the invitation the child's identity mode calls for. The response reports the PROBED fact of whether anyone can now reach the organization.

Invite an admin into a child organization › path Parameters

id

string · required

Invite an admin into a child organization › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Invite an admin into a child organization › Request Body

email

string · email · required

Invite an admin into a child organization › Responses

Accepted

object · required

Withdraw an invitation into a child organization

POST

https://api.kontier.eu/v1

/organization/children/{id}/invitations/revoke

Idempotent: revoking an invitation that is not there succeeds.

Withdraw an invitation into a child organization › path Parameters

id

string · required

Withdraw an invitation into a child organization › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Withdraw an invitation into a child organization › Request Body

email

string · email · required

Withdraw an invitation into a child organization › Responses

object · required

List a child organization's members and invitations

GET

https://api.kontier.eu/v1

/organization/children/{id}/members

List a child organization's members and invitations › path Parameters

id

string · required

List a child organization's members and invitations › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List a child organization's members and invitations › Responses

object · required

Suspend or restore one membership in a child organization

POST

https://api.kontier.eu/v1

/organization/children/{id}/members/{userId}/enabled

Writes the MEMBERSHIP's status, not the person's realm account: a member of several organizations keeps every other one.

Suspend or restore one membership in a child organization › path Parameters

id

string · required

userId

string · required

Suspend or restore one membership in a child organization › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Suspend or restore one membership in a child organization › Request Body

enabled

boolean · required

Suspend or restore one membership in a child organization › Responses

object · required

Re-send a child member's address verification

POST

https://api.kontier.eu/v1

/organization/children/{id}/members/{userId}/resend-verification

Re-send a child member's address verification › path Parameters

id

string · required

userId

string · required

Re-send a child member's address verification › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Re-send a child member's address verification › Responses

Accepted

object · required

Get an organization and everything below it

GET

https://api.kontier.eu/v1

/organization/children/{id}/subtree

The organization itself first, then every organization below it, shallowest first.

Get an organization and everything below it › path Parameters

id

string · required

Get an organization and everything below it › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get an organization and everything below it › Responses

array | null · required

Names Reports