Update a legal entity · Ownrecord docs

Changes a legal entity's slug, legal and trading name, address, company registry ID, home tax ID, default currency, time zone or invoice settings (number format, language, footer, bank transfer details). Send only the fields to change; null removes an optional value.

The establishment country can't change: a company in another country is another legal entity. A new home tax ID resets the verification to unverified. Needs entities:write (organization owners and admins).

At a glance

REST: PATCH /api/v1/entities/{id}
MCP tool: entities_update
Operation ID: entities.update
Scope: Organization, or one of its legal entities or brands
Permission: entities:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the entities:write scope
Since: M1

Request

Path parameters

Field	Type	Description
`id`	`ent_…` ID

Body

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

Field	Type	Required
`slug`	string	No
`legalName`	string	No
`tradingName`	string or null	No
`establishment`	object	No
`establishment.subdivision`	string or null	No
`establishment.address`	object	No
`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	No
`establishment.euVatEstablished`	boolean	No
`homeTaxId`	object	No
`homeTaxId.type`	string	Yes
`homeTaxId.value`	string	Yes
`defaultCurrency`	string	No
`timezone`	string	No
`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

200 OK 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

Add bank transfer details for invoices

HTTP

PATCH /api/v1/entities/ent_01m4tx5nj8emwbyf7y9vcf47x2
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "invoiceSettings": {
    "bankTransfer": {
      "iban": "HR1210010051863000160",
      "bic": "ZABAHR2X",
      "bankName": "Zagrebačka banka",
      "accountHolder": "Acme Digital d.o.o."
    }
  }
}

Response (200):

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": {
      "iban": "HR1210010051863000160",
      "bic": "ZABAHR2X",
      "bankName": "Zagrebačka banka",
      "accountHolder": "Acme Digital d.o.o."
    }
  },
  "status": "onboarding",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	No field to change was sent, or one is 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.	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.
`resource_not_found`	404	No entity with this ID is visible to the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The entity changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't change legal entities here.	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, 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#

Path parameters#

Body#

Response#

Examples#

Add bank transfer details for invoices#

Errors#