# Upload a registry extract for verification

> The entities.registry_extract.upload operation: POST /api/v1/entities/{id}/registry_extract in the REST API and the entities_registry_extract_upload tool in the MCP server.

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

## At a glance

- **REST:** `POST /api/v1/entities/{id}/registry_extract`
- **MCP tool:** `entities_registry_extract_upload`
- **Operation ID:** `entities.registry_extract.upload`
- **Scope:** Organization, or one of its legal entities or brands
- **Permission:** `entities:tax_ids`
- **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:tax_ids` scope
- **Since:** M12

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `ent_…` ID |             |

### Body

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

| Field      | Type   | Required | Description                                                                    |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `content`  | string | Yes      | The extract's bytes, base64-encoded: a PDF, PNG or JPEG file of at most 10 MB. |
| `filename` | string | No       |                                                                                |

## Response

`201 Created` with a JSON object:

| Field                                        | Type                                                          | Description |
| -------------------------------------------- | ------------------------------------------------------------- | ----------- |
| `entity`                                     | object                                                        |             |
| `entity.id`                                  | `ent_…` ID                                                    |             |
| `entity.object`                              | `"legal_entity"`                                              |             |
| `entity.orgId`                               | `org_…` ID                                                    |             |
| `entity.slug`                                | string                                                        |             |
| `entity.legalName`                           | string                                                        |             |
| `entity.tradingName`                         | string or null                                                |             |
| `entity.establishment`                       | object                                                        |             |
| `entity.establishment.country`               | string                                                        |             |
| `entity.establishment.subdivision`           | string or null                                                |             |
| `entity.establishment.address`               | object                                                        |             |
| `entity.establishment.address.line1`         | string                                                        |             |
| `entity.establishment.address.line2`         | string or null                                                |             |
| `entity.establishment.address.city`          | string                                                        |             |
| `entity.establishment.address.postalCode`    | string or null                                                |             |
| `entity.establishment.address.region`        | string or null                                                |             |
| `entity.establishment.address.country`       | string                                                        |             |
| `entity.establishment.companyRegistryId`     | string                                                        |             |
| `entity.establishment.euVatEstablished`      | boolean                                                       |             |
| `entity.homeTaxId`                           | object                                                        |             |
| `entity.homeTaxId.type`                      | string                                                        |             |
| `entity.homeTaxId.value`                     | string                                                        |             |
| `entity.verification`                        | object                                                        |             |
| `entity.verification.status`                 | one of `unverified`, `pending_review`, `verified`, `rejected` |             |
| `entity.verification.method`                 | one of `vies`, `hmrc`, `ch_uid`, `document`                   |             |
| `entity.verification.checkedAt`              | date-time or null                                             |             |
| `entity.defaultCurrency`                     | string                                                        |             |
| `entity.timezone`                            | string                                                        |             |
| `entity.invoiceSettings`                     | object                                                        |             |
| `entity.invoiceSettings.numberFormat`        | string                                                        |             |
| `entity.invoiceSettings.sequenceResetYearly` | boolean                                                       |             |
| `entity.invoiceSettings.language`            | string                                                        |             |
| `entity.invoiceSettings.bilingual`           | string or null                                                |             |
| `entity.invoiceSettings.footerText`          | string or null                                                |             |
| `entity.invoiceSettings.bankTransfer`        | object or null                                                |             |
| `entity.status`                              | one of `onboarding`, `active`, `suspended`, `archived`        |             |
| `entity.createdAt`                           | date-time                                                     |             |
| `entity.updatedAt`                           | date-time                                                     |             |
| `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                                             |             |
| `verification.consultationNumber`            | string or null                                                |             |
| `verification.documentFileId`                | `file_…` ID or null                                           |             |
| `verification.notes`                         | string or null                                                |             |

## Examples

### Send a registry extract for review

```http
POST /api/v1/entities/ent_01m4tx5nj8emwbyf7y9vcf47x2/registry_extract
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "court-register-extract.pdf"
}
```

Response (`201`):

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

## Errors

| Code                                                                                                 | HTTP status | When                                                                  | What to do                                                                                           |
| ---------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`registry_extract_invalid`](https://ownrecord.io/docs/reference/errors.md#registry_extract_invalid) | 400         | The content isn't base64 of a PDF, PNG or JPEG file of at most 10 MB. | Upload the extract from the company register as a PDF (or a clear photo) under 10 MB.                |
| [`entity_already_verified`](https://ownrecord.io/docs/reference/errors.md#entity_already_verified)   | 409         | The entity is verified already.                                       | Nothing to do. Change its tax ID to verify it again.                                                 |
| [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout)                 | 502         | The file store didn't answer in time; nothing was recorded. Retry.    | Retry the request with the same Idempotency-Key after a short wait.                                  |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)             | 404         | No such legal entity in your scope.                                   | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)               | 403         | You can't verify this entity.                                         | 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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`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_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).