Create an organization

Creates an organization (the account and the boundary for all its data) and makes you its owner (org_owner). The slug appears in console URLs (/console/{slug}) and is unique across Ownrecord: 3 to 40 lowercase letters, digits and single hyphens.

Who can call it: any signed-in user, from the console. API keys belong to an organization, so they can't create one.

New organizations start on Ownrecord's free sandbox plan (test mode only): Ownrecord creates the organization's billing account and subscription right after. Upgrade in Organization → Billing (platform_billing.change_plan) to take live payments. Add a legal entity next, then a brand.

At a glance

REST: POST /api/v1/organizations
MCP tool: organizations_create
Operation ID: organizations.create
Scope: Platform
Permission: account:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the account:write scope
Since: M1

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required
`name`	string	Yes
`slug`	string	Yes
`country`	string	Yes

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`org_…` ID
`object`	`"organization"`
`slug`	string
`name`	string
`country`	string
`status`	one of `active`, `restricted`, `suspended`, `closing`, `closed`
`isPlatform`	boolean
`supportAccess`	one of `off`, `on_request`, `always_read`
`requireMfa`	boolean
`entitlements`	object
`plan`	object
`plan.status`	one of `trialing`, `active`, `past_due`, `unpaid`, `canceled`, `none`
`plan.override`	object or null
`createdBy`	`usr_…` ID
`createdAt`	date-time
`updatedAt`	date-time

Examples

HTTP

POST /api/v1/organizations
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "name": "Acme",
  "slug": "acme",
  "country": "HR"
}

Response (201):

JSON

{
  "id": "org_01m4tx5nj7ekd958x53w4bntcg",
  "object": "organization",
  "slug": "acme",
  "name": "Acme",
  "country": "HR",
  "status": "active",
  "isPlatform": false,
  "supportAccess": "on_request",
  "requireMfa": false,
  "entitlements": {
    "livemode": true,
    "entities.max": 2,
    "brands.max": 3,
    "members.max": 10,
    "jurisdictions.registered.max": 10,
    "subscriptions.enabled": true,
    "usage_billing.enabled": true,
    "einvoicing.enabled": true,
    "processors.secondary": false,
    "custom_domains.max": 2,
    "api.rate_limit_rps": 100,
    "audit.retention_days": 90,
    "support.level": "email",
    "filing.reports": "full",
    "sso.enabled": false,
    "assistant.enabled": true,
    "assistant.messages_per_month": 1000
  },
  "plan": {
    "status": "none",
    "override": {
      "reason": "Temporary Growth entitlements until platform billing (M12)",
      "expiresAt": null
    }
  },
  "createdBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The name, slug or country is missing or malformed.	Fix the fields listed in `details.issues` and send the request again.
`slug_invalid`	400	The slug has the wrong format or is a reserved word such as `api`.	Choose a slug such as `acme` or `acme-app`. Reserved words such as `api`, `console` and `docs` can't be used.
`slug_taken`	409	Another organization already uses this slug.	Choose another slug. Organization and brand slugs are unique across Ownrecord; entity slugs are unique within an organization.
`permission_denied`	403	The caller isn't a signed-in user (for example, an API key).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#