Create a legal entity · Ownrecord docs

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
`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`	400	A field is missing or malformed (`details.issues`).	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.	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 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`	403	The plan's `entities.max` is reached.	Upgrade the organization's plan, or remove something to get back under the limit.
`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: 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, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

A Croatian company#

Errors#