postAdmit enterprise

Required capabilityenterprises.create

Authentication: Send Authorization: Bearer <access_token>.

Create the enterprise perimeter when it does not exist yet.

Creates the enterprise perimeter and its default master account. Requires a platform-operator binding and an enterprise_wildcard grant anchored at platform-operators/<id> for enterprises.create; otherwise returns 403 forbidden_capability_scope. Admission does not provision the designated administrator, identity access, roles, or commercial agreements. Call POST /enterprises/{enterprise_id}/provision separately to complete that setup.

Parameters

Name Location Type Required Description and constraints
Idempotency-Key header string No Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128

Request

Required request body.

Request body schema

Field Type Required Description and constraints
designated_admin object Yes No additional fields
external_id string or null No
jurisdiction string Yes Country of registration, ISO 3166-1 alpha-2. pattern: ^[A-Z]{2}$; minLength: 2; maxLength: 2
legal_name string Yes minLength: 1
metadata object or null No

Additional fields are not accepted.

Request body schema.designated_admin

Field Type Required Description and constraints
display_name string or null No
email string Yes format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Additional fields are not accepted.

Request body schema.designated_admin.display_name

At least one alternative must match.

Request body schema.designated_admin.display_name: alternative 1

Type: string.

Request body schema.designated_admin.display_name: alternative 2

Type: null.

Request body schema.external_id

At least one alternative must match.

Request body schema.external_id: alternative 1

Type: string. minLength: 1

Request body schema.external_id: alternative 2

Type: null.

Request body schema.metadata

At least one alternative must match.

Request body schema.metadata: alternative 1

Type: object.

Request body schema.metadata: alternative 2

Type: null.

Request URL

POST
POST /enterprises

Request Body

application/json
{
  "designated_admin": {
    "display_name": "Acme Admin",
    "email": "admin@acme.example"
  },
  "external_id": "ent-ext-0001",
  "jurisdiction": "DE",
  "legal_name": "Acme Fintech GmbH",
  "metadata": {
    "industry": "fintech"
  }
}

Responses

Response

application/json
{
  "enterprise": {
    "admission_state": "admitted",
    "created_at": "2026-05-01T10:00:00Z",
    "default_master_account": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "etag": "2026-05-01T10:00:00.000Z",
    "external_id": "ent-ext-0001",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "jurisdiction": "DE",
    "jurisdiction_selected": false,
    "kyb_source": null,
    "kyb_stage": null,
    "kyb_state": null,
    "kyb_state_reason": null,
    "kyb_state_updated_at": null,
    "kyc_source": null,
    "kyc_stage": null,
    "legal_form": null,
    "legal_name": "Acme Fintech GmbH",
    "metadata": {
      "hq_country": "DE",
      "industry": "fintech"
    },
    "resource": "enterprise",
    "restriction_kind": null,
    "restriction_reason": null,
    "restriction_state": "none",
    "terminated_at": null,
    "termination_reason": null,
    "updated_at": "2026-05-01T10:00:00.000Z"
  },
  "master_account": {
    "created_at": "2026-05-01T10:00:00Z",
    "display_name": "Acme Fintech GmbH",
    "etag": "2026-05-01T10:00:00.000Z",
    "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "parent": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "resource": "master_account",
    "status": "active",
    "tenant_type": "enterprise",
    "updated_at": "2026-05-01T10:00:00.000Z"
  }
}

Resource created successfully.

Response 201 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
enterprise object Yes No additional fields
master_account object Yes No additional fields

Additional fields are not accepted.

application/json body.enterprise
Field Type Required Description and constraints
admission_state "admission_review" / "admitted" / "operational" / "restricted" / "offboarding" / "terminated" Yes
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
default_master_account string or null No
etag string Yes minLength: 1
external_id string or null No
id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
jurisdiction string Yes Country of registration, ISO 3166-1 alpha-2. pattern: ^[A-Z]{2}$; minLength: 2; maxLength: 2
jurisdiction_selected boolean Yes
kyb_source "bootstrap" / "sumsub" or null Yes
kyb_stage "form_k_ready" / "verified" or null Yes
kyb_state "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected" or null Yes
kyb_state_reason string or null Yes
kyb_state_updated_at string or null Yes
kyc_source "bootstrap" / "sumsub" or null Yes
kyc_stage "verified" or null Yes
legal_form string or null Yes
legal_name string Yes minLength: 1
metadata object or null No
resource "enterprise" Yes
restriction_kind "restricted" / "suspended" or null Yes
restriction_reason string or null Yes
restriction_state "none" / "restricted" Yes
terminated_at string or null Yes
termination_reason string or null Yes
updated_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional fields are not accepted.

application/json body.enterprise.default_master_account

At least one alternative must match.

application/json body.enterprise.default_master_account: alternative 1

Type: string. pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

application/json body.enterprise.default_master_account: alternative 2

Type: null.

application/json body.enterprise.external_id

At least one alternative must match.

application/json body.enterprise.external_id: alternative 1

Type: string.

application/json body.enterprise.external_id: alternative 2

Type: null.

application/json body.enterprise.kyb_source

At least one alternative must match.

application/json body.enterprise.kyb_source: alternative 1

Type: "bootstrap" / "sumsub".

application/json body.enterprise.kyb_source: alternative 2

Type: null.

application/json body.enterprise.kyb_stage

At least one alternative must match.

application/json body.enterprise.kyb_stage: alternative 1

Type: "form_k_ready" / "verified".

application/json body.enterprise.kyb_stage: alternative 2

Type: null.

application/json body.enterprise.kyb_state

At least one alternative must match.

application/json body.enterprise.kyb_state: alternative 1

Type: "not_started" / "in_progress" / "submitted" / "in_review" / "resubmission_required" / "form_k_ready" / "verified" / "rejected".

application/json body.enterprise.kyb_state: alternative 2

Type: null.

application/json body.enterprise.kyb_state_reason

At least one alternative must match.

application/json body.enterprise.kyb_state_reason: alternative 1

Type: string.

application/json body.enterprise.kyb_state_reason: alternative 2

Type: null.

application/json body.enterprise.kyb_state_updated_at

At least one alternative must match.

application/json body.enterprise.kyb_state_updated_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.enterprise.kyb_state_updated_at: alternative 2

Type: null.

application/json body.enterprise.kyc_source

At least one alternative must match.

application/json body.enterprise.kyc_source: alternative 1

Type: "bootstrap" / "sumsub".

application/json body.enterprise.kyc_source: alternative 2

Type: null.

application/json body.enterprise.kyc_stage

At least one alternative must match.

application/json body.enterprise.kyc_stage: alternative 1

Type: "verified".

application/json body.enterprise.kyc_stage: alternative 2

Type: null.

application/json body.enterprise.legal_form

At least one alternative must match.

application/json body.enterprise.legal_form: alternative 1

Type: string. minLength: 1

application/json body.enterprise.legal_form: alternative 2

Type: null.

application/json body.enterprise.metadata

At least one alternative must match.

application/json body.enterprise.metadata: alternative 1

Type: object.

application/json body.enterprise.metadata: alternative 2

Type: null.

application/json body.enterprise.restriction_kind

At least one alternative must match.

application/json body.enterprise.restriction_kind: alternative 1

Type: "restricted" / "suspended".

application/json body.enterprise.restriction_kind: alternative 2

Type: null.

application/json body.enterprise.restriction_reason

At least one alternative must match.

application/json body.enterprise.restriction_reason: alternative 1

Type: string.

application/json body.enterprise.restriction_reason: alternative 2

Type: null.

application/json body.enterprise.terminated_at

At least one alternative must match.

application/json body.enterprise.terminated_at: alternative 1

Type: string. format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

application/json body.enterprise.terminated_at: alternative 2

Type: null.

application/json body.enterprise.termination_reason

At least one alternative must match.

application/json body.enterprise.termination_reason: alternative 1

Type: string.

application/json body.enterprise.termination_reason: alternative 2

Type: null.

application/json body.master_account
Field Type Required Description and constraints
created_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
display_name string or null No
etag string Yes minLength: 1
id string Yes format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
parent string Yes pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
resource "master_account" Yes
status "active" / "suspended" / "closed" Yes
tenant_type "enterprise" / "platform_operator" Yes
updated_at string Yes format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional fields are not accepted.

application/json body.master_account.display_name

At least one alternative must match.

application/json body.master_account.display_name: alternative 1

Type: string.

application/json body.master_account.display_name: alternative 2

Type: null.

Response 400 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 401 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
code string Yes
data object No No additional fields
details object No Additional fields allowed
message string Yes

Additional fields are not accepted.

application/json body.data
Field Type Required Description and constraints
acr_values string No RFC 9470 step-up challenge (insufficient_user_authentication).
blockers object[] No For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.
code string No For legal refusals: the document code the refusal is about.
max_age string No RFC 9470 step-up challenge (insufficient_user_authentication).
max_source_amount object or null No For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum. No additional fields
min_source_amount object No For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included. No additional fields
published_version string No For document_version_superseded: the version currently published.
reason string No Typed refinement of code, from the failing service's contract.
resource string No Resource kind a resource_not_found refers to.
retry_after_ms integer or null No Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0
source string No For not_admissible: the gate that denied (verification, lifecycle, policy, compliance).

Additional fields are not accepted.

application/json body.data.blockers

For closure_preconditions_not_met on a terminal lifecycle verb: what must be resolved before the transition.

Type: object[].

application/json body.data.blockers item
Field Type Required Description and constraints
description string Yes
type "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" Yes
assets object[] No minItems: 1
count integer No minimum: 0; maximum: 9007199254740991

Additional fields are not accepted.

application/json body.data.blockers item.assets

Type: object[]. minItems: 1

application/json body.data.blockers item.assets item
Field Type Required Description and constraints
asset string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
kind "balance" / "held" / "owed" / "unsettled" Yes

Additional fields are not accepted.

application/json body.data.max_source_amount

For amount_below_minimum / amount_above_maximum: the product maximum in source asset units; null means no maximum.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

application/json body.data.min_source_amount

For amount_below_minimum / amount_above_maximum: the effective minimum in source asset units, fees included.

Field Type Required Description and constraints
currency string Yes
value string Yes

Additional fields are not accepted.

Response 403 schema

Content type: application/json.

See response 401 schema.

Response 409 schema

Content type: application/json.

See response 401 schema.

Response 500 schema

Content type: application/json.

See response 401 schema.

Response 502 schema

Content type: application/json.

See response 400 schema.

Response 503 schema

Content type: application/json.

See response 400 schema.