Upload a registry extract for verification

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`	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`	409	The entity is verified already.	Nothing to do. Change its tax ID to verify it again.
`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`	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`	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: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, 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#

Path parameters#

Body#

Response#

Examples#

Send a registry extract for review#

Errors#