# Create a legal entity > The entities.create operation: POST /api/v1/entities in the REST API and the entities_create tool in the MCP server. Adds a legal entity: the company that sells (the seller of record), with its establishment, company registry ID, home tax ID, default currency, time zone and invoice settings. Brands are created under an entity next. The entity starts `onboarding` and `unverified`. Its home tax ID is verified later (VIES for `eu_vat`, HMRC for `gb_vat`, CH UID for `ch_vat`, otherwise a registry extract reviewed by Ownrecord). Invoice settings default to the number format `{series}-{year}-{seq:06}`, a yearly sequence reset and English invoices. The plan limits the number of entities (`entities.max`); one more than the limit is `entitlement_required`. The slug is unique within the organization. Needs `entities:write` (organization owners and admins). ## At a glance - **REST:** `POST /api/v1/entities` - **MCP tool:** `entities_create` - **Operation ID:** `entities.create` - **Scope:** Organization - **Permission:** `entities: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 `entities:write` scope - **Since:** M1 ## Request ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------------------------------- | -------------- | -------- | ----------- | | `slug` | string | Yes | | | `legalName` | string | Yes | | | `tradingName` | string | No | | | `establishment` | object | Yes | | | `establishment.country` | string | Yes | | | `establishment.subdivision` | string | No | | | `establishment.address` | object | Yes | | | `establishment.address.line1` | string | Yes | | | `establishment.address.line2` | string | No | | | `establishment.address.city` | string | Yes | | | `establishment.address.postalCode` | string | No | | | `establishment.address.region` | string | No | | | `establishment.address.country` | string | No | | | `establishment.companyRegistryId` | string | Yes | | | `establishment.euVatEstablished` | boolean | No | | | `homeTaxId` | object | Yes | | | `homeTaxId.type` | string | Yes | | | `homeTaxId.value` | string | Yes | | | `defaultCurrency` | string | Yes | | | `timezone` | string | Yes | | | `invoiceSettings` | object | No | | | `invoiceSettings.numberFormat` | string | No | | | `invoiceSettings.sequenceResetYearly` | boolean | No | | | `invoiceSettings.language` | string | No | | | `invoiceSettings.bilingual` | string or null | No | | | `invoiceSettings.footerText` | string or null | No | | | `invoiceSettings.bankTransfer` | object or null | No | | ## Response `201 Created` with a JSON object: | Field | Type | Description | | ------------------------------------- | ------------------------------------------------------------- | ----------- | | `id` | `ent_…` ID | | | `object` | `"legal_entity"` | | | `orgId` | `org_…` ID | | | `slug` | string | | | `legalName` | string | | | `tradingName` | string or null | | | `establishment` | object | | | `establishment.country` | string | | | `establishment.subdivision` | string or null | | | `establishment.address` | object | | | `establishment.address.line1` | string | | | `establishment.address.line2` | string or null | | | `establishment.address.city` | string | | | `establishment.address.postalCode` | string or null | | | `establishment.address.region` | string or null | | | `establishment.address.country` | string | | | `establishment.companyRegistryId` | string | | | `establishment.euVatEstablished` | boolean | | | `homeTaxId` | object | | | `homeTaxId.type` | string | | | `homeTaxId.value` | string | | | `verification` | object | | | `verification.status` | one of `unverified`, `pending_review`, `verified`, `rejected` | | | `verification.method` | one of `vies`, `hmrc`, `ch_uid`, `document` | | | `verification.checkedAt` | date-time or null | | | `defaultCurrency` | string | | | `timezone` | string | | | `invoiceSettings` | object | | | `invoiceSettings.numberFormat` | string | | | `invoiceSettings.sequenceResetYearly` | boolean | | | `invoiceSettings.language` | string | | | `invoiceSettings.bilingual` | string or null | | | `invoiceSettings.footerText` | string or null | | | `invoiceSettings.bankTransfer` | object or null | | | `status` | one of `onboarding`, `active`, `suspended`, `archived` | | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### A Croatian company ```http POST /api/v1/entities Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "slug": "acme-hr", "legalName": "Acme Digital d.o.o.", "establishment": { "country": "HR", "address": { "line1": "Ilica 1", "city": "Zagreb", "postalCode": "10000" }, "companyRegistryId": "080000000", "euVatEstablished": true }, "homeTaxId": { "type": "eu_vat", "value": "HR12345678901" }, "defaultCurrency": "EUR", "timezone": "Europe/Zagreb" } ``` Response (`201`): ```json { "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "object": "legal_entity", "orgId": "org_01m4tx5nj7ekd958x53w4bntcg", "slug": "acme-hr", "legalName": "Acme Digital d.o.o.", "tradingName": null, "establishment": { "country": "HR", "subdivision": null, "address": { "line1": "Ilica 1", "line2": null, "city": "Zagreb", "postalCode": "10000", "region": null, "country": "HR" }, "companyRegistryId": "080000000", "euVatEstablished": true }, "homeTaxId": { "type": "eu_vat", "value": "HR12345678901" }, "verification": { "status": "unverified", "method": "vies", "checkedAt": null }, "defaultCurrency": "EUR", "timezone": "Europe/Zagreb", "invoiceSettings": { "numberFormat": "{series}-{year}-{seq:06}", "sequenceResetYearly": true, "language": "en", "bilingual": null, "footerText": null, "bankTransfer": null }, "status": "onboarding", "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 | A field is missing or malformed (`details.issues`). | 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. | 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 entity of this organization already uses this slug. | Choose another slug. Organization and brand slugs are unique across Ownrecord; entity slugs are unique within an organization. | | [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required) | 403 | The plan's `entities.max` is reached. | Upgrade the organization's plan, or remove something to get back under the limit. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't create legal entities in this organization. | 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), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).