# Create an organization > The organizations.create operation: POST /api/v1/organizations in the REST API and the organizations_create tool in the MCP server. 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 | Description | | --------- | ------ | -------- | ----------- | | `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 ### Create an organization ```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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).