Organizations

Endpointhttps://api.kontier.eu/v1

List pending invitations

GET

https://api.kontier.eu/v1

/invitations

Returns every still-pending invitation for the active organization, newest first. Existence of the row IS the pending state; accepted invitations are deleted on first sign-in.

List pending invitations › 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 pending invitations › Responses

array | null · required

Invite a user to the organization

POST

https://api.kontier.eu/v1

/invitations

Sends a Keycloak-hosted invitation email to the supplied address and records the role names to apply on acceptance. Re-inviting the same address replaces the previous pending role intent. Empty role_names defaults to no_access.

Invite a user to the 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.

Invite a user to the organization › Request Body

email

string · required

role_names

array | null

Invite a user to the organization › Responses

Created

object · required

Revoke a pending invitation

DELETE

https://api.kontier.eu/v1

/invitations/{id}

Cancels a pending invitation: deletes the kontier row and best-effort removes the matching Keycloak org-invitation so the action token in the user's inbox stops working. Already-accepted invitations don't exist as rows - remove the user via the membership API instead.

Revoke a pending invitation › path Parameters

id

string · uuid · required

Invitation UUID

Revoke a pending invitation › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Revoke a pending invitation › Responses

No Content

No data returned

Get the current organization profile

GET

https://api.kontier.eu/v1

/organization

Returns the organization profile resolved from the caller's auth context (name, slug, default locale, etc.).

Get the current organization profile › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the current organization profile › Responses

object · required

GET/organization

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

shell

Example Responses

{
  "data": {
    "business_address": "business_address",
    "created_at": "2024-08-25T15:00:00Z",
    "default_currency": "default_currency",
    "default_date_format": "default_date_format",
    "default_first_day_of_week": "default_first_day_of_week",
    "default_language": "default_language",
    "default_locale": "default_locale",
    "default_number_format": "default_number_format",
    "default_timezone": "default_timezone",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "legal_name": "legal_name",
    "main_email": "main_email",
    "name": "name",
    "phone": "phone",
    "sales_audience": "sales_audience",
    "signup_email": "signup_email",
    "slug": "slug",
    "status": "status",
    "support_email": "support_email",
    "tax_registration_number": "tax_registration_number"
  }
}

json

application/json

Update the current organization profile

PUT

https://api.kontier.eu/v1

/organization

Updates editable fields on the caller's organization profile. The default_locale must be one of the supported invoicing languages (en, de, fr, es, it, pt, nl, ja).

Update the current organization profile › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update the current organization profile › Request Body

business_address

string

company_size_tier

string

default_country

string

default_currency

string

default_date_format

string

default_first_day_of_week

string

default_language

string

default_locale

string

default_number_format

string

default_timezone

string

legal_name

string

main_email

string

name

string

phone

string

sales_audience

string

signup_email

string

support_email

string

tax_inclusive

boolean

tax_registration_number

string

vat_id_collection

string

Update the current organization profile › Responses

object · required

PUT/organization

curl --request PUT \
  --url https://api.kontier.eu/v1/organization \
  --header 'Content-Type: application/json' \
  --data '
{
  "business_address": "business_address",
  "company_size_tier": "company_size_tier",
  "default_country": "default_country",
  "default_currency": "default_currency",
  "default_date_format": "default_date_format",
  "default_first_day_of_week": "default_first_day_of_week",
  "default_language": "default_language",
  "default_locale": "default_locale",
  "default_number_format": "default_number_format",
  "default_timezone": "default_timezone",
  "legal_name": "legal_name",
  "main_email": "main_email",
  "name": "name",
  "phone": "phone",
  "sales_audience": "sales_audience",
  "signup_email": "signup_email",
  "support_email": "support_email",
  "tax_inclusive": true,
  "tax_registration_number": "tax_registration_number",
  "vat_id_collection": "vat_id_collection"
}
'

shell

Example Request Body

{
  "business_address": "business_address",
  "company_size_tier": "company_size_tier",
  "default_country": "default_country",
  "default_currency": "default_currency",
  "default_date_format": "default_date_format",
  "default_first_day_of_week": "default_first_day_of_week",
  "default_language": "default_language",
  "default_locale": "default_locale",
  "default_number_format": "default_number_format",
  "default_timezone": "default_timezone",
  "legal_name": "legal_name",
  "main_email": "main_email",
  "name": "name",
  "phone": "phone",
  "sales_audience": "sales_audience",
  "signup_email": "signup_email",
  "support_email": "support_email",
  "tax_inclusive": true,
  "tax_registration_number": "tax_registration_number",
  "vat_id_collection": "vat_id_collection"
}

json

Example Responses

{
  "data": {
    "business_address": "business_address",
    "created_at": "2024-08-25T15:00:00Z",
    "default_currency": "default_currency",
    "default_date_format": "default_date_format",
    "default_first_day_of_week": "default_first_day_of_week",
    "default_language": "default_language",
    "default_locale": "default_locale",
    "default_number_format": "default_number_format",
    "default_timezone": "default_timezone",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "legal_name": "legal_name",
    "main_email": "main_email",
    "name": "name",
    "phone": "phone",
    "sales_audience": "sales_audience",
    "signup_email": "signup_email",
    "slug": "slug",
    "status": "status",
    "support_email": "support_email",
    "tax_registration_number": "tax_registration_number"
  }
}

json

application/json

List the organization's recipient lists

GET

https://api.kontier.eu/v1

/organization/contacts

Who on your own side receives each kind of mail: quotes & contracts, approvals, finance, operations and reports. Each list holds one address that receives the mail plus up to two copied on it, and an entry can be a shared mailbox, a named person, or a role — a role reaches everyone who holds it, so the list stays correct when someone joins. The lists are per workspace, so a sandbox alert never reaches your live desk. Small and bounded by design, so the whole list is returned and it is not paginated.

List the organization's recipient lists › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List the organization's recipient lists › Responses

array | null · required

object · required

GET/organization/contacts

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

shell

Example Responses

{
  "data": [
    {
      "category": "quotes_contracts",
      "created_at": "2024-08-25T15:00:00Z",
      "email": "email",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_primary": true,
      "kind": "email",
      "name": "name",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "position": 0,
      "role": "role",
      "updated_at": "2024-08-25T15:00:00Z",
      "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Add someone to one of the organization's recipient lists

POST

https://api.kontier.eu/v1

/organization/contacts

Adds a shared mailbox, a named person, or a role to one list. Omit is_primary to let the first entry in a list become the one that receives the mail; pass true to move it there from whichever entry holds it. Returns 409 when that recipient is already on the list and 422 when the list already holds three.

Add someone to one of the organization's recipient lists › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Add someone to one of the organization's recipient lists › Request Body

category

string · enum · required

What this contact receives. Required.

Enum values:

quotes_contracts

approvals

finance

operations

reports

Example: finance

kind

string · enum · required

Which arm this row carries. Required.

Enum values:

user

role

Example: email

email

string · maxLength: 320

Required when kind is email; must be absent otherwise.

Example: finance@acme.example

is_primary

boolean

Whether mail for this category is addressed here. Omit to let the first row in a category become its primary.

name

string · maxLength: 200

Optional label.

Example: Finance desk

role

string · maxLength: 100

Required when kind is role; must be absent otherwise.

Example: finance

user_id

string · uuid

Required when kind is user; must be absent otherwise.

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

Add someone to one of the organization's recipient lists › Responses

Created

object · required

POST/organization/contacts

curl --request POST \
  --url https://api.kontier.eu/v1/organization/contacts \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "category": "finance",
  "email": "finance@acme.example",
  "is_primary": true,
  "kind": "email",
  "name": "Finance desk",
  "role": "finance",
  "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "category": "finance",
  "email": "finance@acme.example",
  "is_primary": true,
  "kind": "email",
  "name": "Finance desk",
  "role": "finance",
  "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "category": "quotes_contracts",
    "created_at": "2024-08-25T15:00:00Z",
    "email": "email",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_primary": true,
    "kind": "email",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "position": 0,
    "role": "role",
    "updated_at": "2024-08-25T15:00:00Z",
    "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Remove an organization recipient

DELETE

https://api.kontier.eu/v1

/organization/contacts/{contactId}

Removes the entry. Idempotent - removing one that is already gone succeeds. If it was the entry receiving the mail, that list falls back to the operations list and then to the organization's main address.

Remove an organization recipient › path Parameters

contactId

string · uuid · required

Contact UUID

Remove an organization recipient › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Remove an organization recipient › Responses

No Content

No data returned

Update an organization recipient

PATCH

https://api.kontier.eu/v1

/organization/contacts/{contactId}

Changes which list an entry is on, who it names, its label, or whether it is the entry that receives the mail. Setting is_primary moves it there from whichever entry holds it, in one transaction. Clearing it leaves the list with nobody receiving directly, and its mail falls back to the operations list and then to the organization's main address.

Update an organization recipient › path Parameters

contactId

string · uuid · required

Contact UUID

Update an organization recipient › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update an organization recipient › Request Body

category

string · enum

Move this row to a different category. It keeps is_primary, so moving a primary into an occupied category takes that category over.

Enum values:

quotes_contracts

approvals

finance

operations

reports

Example: operations

email

string · maxLength: 320

The mailbox, when the resulting kind is email.

is_primary

boolean

true addresses this category here, demoting whichever row held it. false leaves the category with no primary at all, so it falls back to the operations list and then to the organisation's main address.

kind

string · enum

Change which arm this row carries. Supply the matching arm field with it.

Enum values:

user

role

Example: role

name

string · maxLength: 200

Set the label; an empty string clears it.

role

string · maxLength: 100

The organisation role, when the resulting kind is role.

user_id

string · uuid

The member, when the resulting kind is user.

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

Update an organization recipient › Responses

object · required

PATCH/organization/contacts/{contactId}

curl --request PATCH \
  --url https://api.kontier.eu/v1/organization/contacts/:contactId \
  --header 'Content-Type: application/json' \
  --data '
{
  "category": "operations",
  "email": "email",
  "is_primary": true,
  "kind": "role",
  "name": "name",
  "role": "role",
  "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "category": "operations",
  "email": "email",
  "is_primary": true,
  "kind": "role",
  "name": "name",
  "role": "role",
  "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "category": "quotes_contracts",
    "created_at": "2024-08-25T15:00:00Z",
    "email": "email",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_primary": true,
    "kind": "email",
    "name": "name",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "position": 0,
    "role": "role",
    "updated_at": "2024-08-25T15:00:00Z",
    "user_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Where each kind of organization mail is sent

GET

https://api.kontier.eu/v1

/organization/recipients

One row per list, showing the address that receives it, the addresses copied on it, and where that answer came from - the list itself, the operations fallback, the organization's main address, or nobody. It is the same lookup the sending path performs, so what it shows is what happens.

Where each kind of organization mail is sent › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Where each kind of organization mail is sent › Responses

array | null · required

object · required

Get the active org's security settings

GET

https://api.kontier.eu/v1

/organization/security

Returns the per-org auth policy: require_mfa, allowed_idps, allowed_email_domains, session_timeout_seconds. Empty arrays mean "no restriction."

Get the active org's security settings › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get the active org's security settings › Responses

object · required

Update the active org's security settings

PATCH

https://api.kontier.eu/v1

/organization/security

Partial update - fields omitted from the body are left unchanged. Empty arrays clear the restriction (no allowed_idps / allowed_email_domains). Setting require_mfa=true takes effect on the next request; existing sessions whose access token's amr claim lacks an MFA method receive 403 MFA_REQUIRED until they re-auth with MFA.

Update the active org's security settings › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update the active org's security settings › Request Body

allowed_email_domains

string[]

allowed_idps

string[]

jit_default_role

string

jit_enabled

boolean

require_mfa

boolean

session_timeout_seconds

integer · int64

Update the active org's security settings › Responses

object · required

PATCH/organization/security

curl --request PATCH \
  --url https://api.kontier.eu/v1/organization/security \
  --header 'Content-Type: application/json' \
  --data '
{
  "allowed_email_domains": [
    "string"
  ],
  "allowed_idps": [
    "string"
  ],
  "jit_default_role": "jit_default_role",
  "jit_enabled": true,
  "require_mfa": true,
  "session_timeout_seconds": 0
}
'

shell

Example Request Body

{
  "allowed_email_domains": [
    "string"
  ],
  "allowed_idps": [
    "string"
  ],
  "jit_default_role": "jit_default_role",
  "jit_enabled": true,
  "require_mfa": true,
  "session_timeout_seconds": 0
}

json

Example Responses

{
  "data": {
    "allowed_email_domains": [
      "string"
    ],
    "allowed_idps": [
      "string"
    ],
    "created_at": "2024-08-25T15:00:00Z",
    "jit_default_role": "jit_default_role",
    "jit_enabled": true,
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "require_mfa": true,
    "session_timeout_seconds": 0,
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Create a new organization

POST

https://api.kontier.eu/v1

/organizations

Provisions a new organization and mints its first API key. Mode determines the key prefix - "live" mints sk_live_, "sandbox" mints sk_test_. The plaintext key is returned once.

Create a new organization › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a new organization › Request Body

name

string · required

default_currency

string

default_locale

string

signup_email

string

slug

string

Create a new organization › Responses

Created

object · required

POST/organizations

curl --request POST \
  --url https://api.kontier.eu/v1/organizations \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "default_currency": "default_currency",
  "default_locale": "default_locale",
  "name": "name",
  "signup_email": "signup_email",
  "slug": "slug"
}
'

shell

Example Request Body

{
  "default_currency": "default_currency",
  "default_locale": "default_locale",
  "name": "name",
  "signup_email": "signup_email",
  "slug": "slug"
}

json

Example Responses

{
  "data": {
    "api_key": "api_key",
    "organization": {
      "business_address": "business_address",
      "created_at": "2024-08-25T15:00:00Z",
      "default_currency": "default_currency",
      "default_date_format": "default_date_format",
      "default_first_day_of_week": "default_first_day_of_week",
      "default_language": "default_language",
      "default_locale": "default_locale",
      "default_number_format": "default_number_format",
      "default_timezone": "default_timezone",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "legal_name": "legal_name",
      "main_email": "main_email",
      "name": "name",
      "phone": "phone",
      "sales_audience": "sales_audience",
      "signup_email": "signup_email",
      "slug": "slug",
      "status": "status",
      "support_email": "support_email",
      "tax_registration_number": "tax_registration_number"
    },
    "workspaces": [
      {
        "active_test_clock_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "created_at": "2024-08-25T15:00:00Z",
        "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "mode": "live",
        "name": "name",
        "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
        "slug": "slug",
        "status": "status",
        "updated_at": "2024-08-25T15:00:00Z"
      }
    ]
  }
}

json

application/json

Portal Workspaces