# Update a legal entity

> The entities.update operation: PATCH /api/v1/entities/{id} in the REST API and the entities_update tool in the MCP server.

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 | Description |
| ------------------------------------- | -------------- | -------- | ----------- |
| `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`](https://ownrecord.io/docs/reference/errors.md#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`](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. |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#version_conflict)     | 409         | The entity changed at the same time; retry.                 | Fetch the object again and retry the change.                                                                                   |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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](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), [`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).