# Entities tools

> MCP tools for Entities: entities_create, entities_get, entities_list, entities_registry_extract_upload, entities_update, entities_verify.

- `entities_create`: Create a legal entity
- `entities_get`: Get a legal entity
- `entities_list`: List legal entities
- `entities_registry_extract_upload`: Upload a registry extract for verification
- `entities_update`: Update a legal entity
- `entities_verify`: Verify a legal entity's tax ID

## `entities_create`

**Create a legal entity.** Operation [`entities.create`](https://ownrecord.io/docs/reference/entities-create.md) · Organization level · permission `entities:write` · risk tier `write` · since M1

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).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: false` · `openWorldHint: false`

### Arguments

| Argument          | Type    | Required | Description                                                                                                                                                                                              |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug`            | string  | yes      | (3–40 characters)                                                                                                                                                                                        |
| `legalName`       | string  | yes      | (1–200 characters)                                                                                                                                                                                       |
| `tradingName`     | string  | no       | (1–200 characters)                                                                                                                                                                                       |
| `establishment`   | object  | yes      | –                                                                                                                                                                                                        |
| `homeTaxId`       | object  | yes      | –                                                                                                                                                                                                        |
| `defaultCurrency` | string  | yes      | –                                                                                                                                                                                                        |
| `timezone`        | string  | yes      | –                                                                                                                                                                                                        |
| `invoiceSettings` | object  | no       | –                                                                                                                                                                                                        |
| `idempotency_key` | string  | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A field is missing or malformed (`details.issues`).
- [`slug_invalid`](https://ownrecord.io/docs/reference/errors.md#slug_invalid): The slug has the wrong format or is a reserved word.
- [`slug_taken`](https://ownrecord.io/docs/reference/errors.md#slug_taken): Another entity of this organization already uses this slug.
- [`entitlement_required`](https://ownrecord.io/docs/reference/errors.md#entitlement_required): The plan's `entities.max` is reached.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't create legal entities in this organization.

### Example

**A Croatian company**

Arguments:

```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",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```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"
}
```

## `entities_get`

**Get a legal entity.** Operation [`entities.get`](https://ownrecord.io/docs/reference/entities-get.md) · Organization level · permission `entities:read` · risk tier `read` · since M1

Returns one legal entity by its ID (`ent_…`): legal data, establishment, home tax ID and its verification,
default currency, time zone and invoice settings. Entities outside the organization, or outside the entity
of an entity-scoped request, are `resource_not_found`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument    | Type         | Required | Description                                                                        |
| ----------- | ------------ | -------- | ---------------------------------------------------------------------------------- |
| `id`        | ID (`ent_…`) | yes      | –                                                                                  |
| `entity_id` | ID (`ent_…`) | no       | Optional: act inside this legal entity (ent\_…) instead of the whole organization. |
| `brand_id`  | ID (`brd_…`) | no       | Optional: act inside this brand (brd\_…) instead of the whole organization.        |

- **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No entity with this ID is visible to the request.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see legal entities here.

### Example

**Read an entity**

Arguments:

```json
{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
}
```

Result `output`:

```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"
}
```

## `entities_list`

**List legal entities.** Operation [`entities.list`](https://ownrecord.io/docs/reference/entities-list.md) · Organization level · permission `entities:read` · risk tier `read` · since M1

Lists the organization's legal entities, newest first. An organization-level request sees every entity;
a request inside one entity (an entity-scoped member, or an entity API key) sees only that entity.
Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page).

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument         | Type         | Required | Description                                                                        |
| ---------------- | ------------ | -------- | ---------------------------------------------------------------------------------- |
| `limit`          | integer      | no       | (1–100)                                                                            |
| `starting_after` | ID (`ent_…`) | no       | –                                                                                  |
| `entity_id`      | ID (`ent_…`) | no       | Optional: act inside this legal entity (ent\_…) instead of the whole organization. |
| `brand_id`       | ID (`brd_…`) | no       | Optional: act inside this brand (brd\_…) instead of the whole organization.        |

- **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`.
- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): `limit` or `starting_after` is malformed.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't see legal entities here.

### Examples

**The first page**

Arguments:

```json
{
  "limit": 10
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

**One per page**

Arguments:

```json
{
  "limit": 1
}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "ent_01m4tx5nj8emwbyf7y9vcf47x3",
      "object": "legal_entity",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "slug": "acme-de",
      "legalName": "Acme GmbH",
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "ent_01m4tx5nj8emwbyf7y9vcf47x3"
}
```

## `entities_registry_extract_upload`

**Upload a registry extract for verification.** Operation [`entities.registry_extract.upload`](https://ownrecord.io/docs/reference/entities-registry-extract-upload.md) · Organization level · permission `entities:tax_ids` · risk tier `write` · since M12

Uploads the legal entity's extract from the company register (a PDF, PNG or JPEG of at most 10 MB) and asks
Ownrecord to verify the entity from it: the verification becomes `pending_review` (method `document`) and the
extract goes to Ownrecord's verification queue. You get the result by email, and the entity becomes `verified`
(or `rejected`, with the reason) once it's reviewed.

Use it when the tax ID can't be checked with a public register (`tax_id_check_not_available`) or the register
doesn't confirm it. Uploading again replaces the extract under review.

Needs `entities:tax_ids` (tax managers, owners and admins).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`ent_…`) | yes      | –                                                                                                                                                                                                        |
| `content`         | string       | yes      | The extract's bytes, base64-encoded: a PDF, PNG or JPEG file of at most 10 MB. (1–14081016 characters)                                                                                                   |
| `filename`        | string       | no       | (1–200 characters)                                                                                                                                                                                       |
| `entity_id`       | ID (`ent_…`) | no       | Optional: act inside this legal entity (ent\_…) instead of the whole organization.                                                                                                                       |
| `brand_id`        | ID (`brd_…`) | no       | Optional: act inside this brand (brd\_…) instead of the whole organization.                                                                                                                              |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`registry_extract_invalid`](https://ownrecord.io/docs/reference/errors.md#registry_extract_invalid): The content isn't base64 of a PDF, PNG or JPEG file of at most 10 MB.
- [`entity_already_verified`](https://ownrecord.io/docs/reference/errors.md#entity_already_verified): The entity is verified already.
- [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout): The file store didn't answer in time; nothing was recorded. Retry.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such legal entity in your scope.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't verify this entity.

### Example

**Send a registry extract for review**

Arguments:

```json
{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "court-register-extract.pdf",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "entity": {
    "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": "pending_review",
      "method": "document",
      "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"
  },
  "verification": {
    "status": "pending_review",
    "method": "document",
    "checkedAt": null,
    "consultationNumber": null,
    "documentFileId": "file_01m4tx5nj8emwbyf7y9vcf47xe",
    "notes": null
  }
}
```

## `entities_update`

**Update a legal entity.** Operation [`entities.update`](https://ownrecord.io/docs/reference/entities-update.md) · Organization level · permission `entities:write` · risk tier `write` · since M1

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).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type           | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`ent_…`)   | yes      | –                                                                                                                                                                                                        |
| `slug`            | string         | no       | (3–40 characters)                                                                                                                                                                                        |
| `legalName`       | string         | no       | (1–200 characters)                                                                                                                                                                                       |
| `tradingName`     | string or null | no       | –                                                                                                                                                                                                        |
| `establishment`   | object         | no       | –                                                                                                                                                                                                        |
| `homeTaxId`       | object         | no       | –                                                                                                                                                                                                        |
| `defaultCurrency` | string         | no       | –                                                                                                                                                                                                        |
| `timezone`        | string         | no       | –                                                                                                                                                                                                        |
| `invoiceSettings` | object         | no       | –                                                                                                                                                                                                        |
| `entity_id`       | ID (`ent_…`)   | no       | Optional: act inside this legal entity (ent\_…) instead of the whole organization.                                                                                                                       |
| `brand_id`        | ID (`brd_…`)   | no       | Optional: act inside this brand (brd\_…) instead of the whole organization.                                                                                                                              |
| `idempotency_key` | string         | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean        | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): No field to change was sent, or one is malformed.
- [`slug_invalid`](https://ownrecord.io/docs/reference/errors.md#slug_invalid): The slug has the wrong format or is a reserved word.
- [`slug_taken`](https://ownrecord.io/docs/reference/errors.md#slug_taken): Another entity of this organization already uses this slug.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No entity with this ID is visible to the request.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The entity changed at the same time; retry.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't change legal entities here.

### Example

**Add bank transfer details for invoices**

Arguments:

```json
{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "invoiceSettings": {
    "bankTransfer": {
      "iban": "HR1210010051863000160",
      "bic": "ZABAHR2X",
      "bankName": "Zagrebačka banka",
      "accountHolder": "Acme Digital d.o.o."
    }
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```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"
}
```

## `entities_verify`

**Verify a legal entity's tax ID.** Operation [`entities.verify`](https://ownrecord.io/docs/reference/entities-verify.md) · Organization level · permission `entities:tax_ids` · risk tier `write` · since M12

Checks the legal entity's home tax ID with its public register and records the answer:

- `eu_vat` with VIES (with the entity's own VAT ID as requester, so the answer carries a consultation number),
  `gb_vat` with HMRC and `ch_vat` with the Swiss UID register;
- `verified`: the entity is verified (a brand of it may go live once the rest of the go-live checklist holds);
- `invalid`: the register doesn't know the number; the entity stays unverified, with the reason in `notes`.
  Fix the tax ID (`entities.update`) or upload a registry extract (`entities.registry_extract.upload`);
- `unavailable`: the register couldn't answer; nothing changes. Try again later.

Other tax ID types have no register to ask (`tax_id_check_not_available`): upload a registry extract instead.
In development and CI the fixture registers answer (no real register is called).

Needs `entities:tax_ids` (tax managers, owners and admins).

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: true`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`ent_…`) | yes      | –                                                                                                                                                                                                        |
| `entity_id`       | ID (`ent_…`) | no       | Optional: act inside this legal entity (ent\_…) instead of the whole organization.                                                                                                                       |
| `brand_id`        | ID (`brd_…`) | no       | Optional: act inside this brand (brd\_…) instead of the whole organization.                                                                                                                              |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Scope:** the whole organization, or one legal entity or brand of it with `entity_id` or `brand_id`.
- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`tax_id_check_not_available`](https://ownrecord.io/docs/reference/errors.md#tax_id_check_not_available): The tax ID type has no register, or the number isn't well-formed.
- [`entity_already_verified`](https://ownrecord.io/docs/reference/errors.md#entity_already_verified): The entity is verified already.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The entity changed while its tax ID was being checked; try again.
- [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout): The register didn't answer in time (reported as `unavailable`).
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): No such legal entity in your scope.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): You can't verify this entity.

### Example

**VIES confirms the VAT ID**

Arguments:

```json
{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "entity": {
    "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": "verified",
      "method": "vies",
      "checkedAt": "2026-10-26T09:00:00.000Z"
    },
    "defaultCurrency": "EUR",
    "timezone": "Europe/Zagreb",
    "invoiceSettings": {
      "numberFormat": "{series}-{year}-{seq:06}",
      "sequenceResetYearly": true,
      "language": "en",
      "bilingual": null,
      "footerText": null,
      "bankTransfer": null
    },
    "status": "active",
    "createdAt": "2026-10-13T12:00:00.000Z",
    "updatedAt": "2026-10-13T12:00:00.000Z"
  },
  "verification": {
    "status": "verified",
    "method": "vies",
    "checkedAt": "2026-10-26T09:00:00.000Z",
    "consultationNumber": "WAPIAAAAZ1b2c3d4",
    "documentFileId": null,
    "notes": null
  },
  "check": {
    "outcome": "verified",
    "method": "vies",
    "consultationNumber": "WAPIAAAAZ1b2c3d4",
    "reason": null,
    "simulated": false
  }
}
```