Approve or reject a legal entity's verification

Records the result of a platform admin's review of a legal entity's registry extract (spec §39.1, §38.2): approve marks the entity verified (method document; an entity still onboarding becomes active, as with a register check), reject marks it rejected with a reason the organization sees. Either way the reviewer and time are recorded on the entity and the organization gets a legal_entity.updated event (live mode, the old verification in previousAttributes), which sends its owners and admins Ownrecord's entity verification result email, plus an ENTITY_VERIFICATION_RESULT alert (info, never emailed) in its inbox. A rejected organization can upload a new extract, which puts the entity back in the queue. Only entities waiting for review (pending_review) can be decided.

At a glance

REST: POST /api/v1/platform/verifications/{orgId}/{entityId}/decide
MCP tool: platform_verifications_decide
Operation ID: platform.verifications.decide
Scope: Platform
Permission: platform:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the platform:write scope
Since: M12

Request

Path parameters

Field	Type	Description
`orgId`	`org_…` ID	The entity's organization.
`entityId`	`ent_…` ID	The legal entity.

Body

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

Field	Type	Required	Description
`decision`	one of `approve`, `reject`	Yes	`approve` (verified) or `reject` (rejected).
`reason`	string	No	Why (required to reject; the organization sees it). Optional note when approving.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"platform_entity_verification"`
`org`	object
`org.id`	`org_…` ID
`org.slug`	string
`org.name`	string
`entity`	object
`entity.id`	`ent_…` ID
`entity.slug`	string
`entity.legalName`	string
`entity.tradingName`	string or null
`entity.country`	string
`entity.status`	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.verification.reviewer`	`usr_…` ID or null
`entity.verification.notes`	string or null
`entity.verification.documentFileId`	`file_…` ID or null	The registry extract under review (`entities.registry_extract.upload`).
`entity.address`	object
`entity.address.line1`	string
`entity.address.line2`	string or null
`entity.address.city`	string
`entity.address.postalCode`	string or null
`entity.address.region`	string or null
`entity.address.country`	string
`entity.companyRegistryId`	string
`entity.homeTaxId`	object
`entity.homeTaxId.type`	string
`entity.homeTaxId.value`	string
`waitingSince`	date-time
`documents`	array of object
`documents[].id`	`file_…` ID
`documents[].filename`	string or null
`documents[].kind`	string
`documents[].contentType`	string
`documents[].size`	integer
`documents[].livemode`	boolean
`documents[].underReview`	boolean	The extract the entity's verification names (the latest upload).
`documents[].createdAt`	date-time

Examples

Approve after checking the extract

HTTP

POST /api/v1/platform/verifications/org_01m5wvkry1e6w94sjxgme33fs6/ent_01m5wvkry1e6w94sjxgme33fsg/decide
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "decision": "approve",
  "reason": "Extract from Brønnøysundregistrene matches name, address and registry ID."
}

Response (200):

JSON

{
  "object": "platform_entity_verification",
  "org": {
    "id": "org_01m5wvkry1e6w94sjxgme33fs6",
    "slug": "nordwind",
    "name": "Nordwind"
  },
  "entity": {
    "id": "ent_01m5wvkry1e6w94sjxgme33fsg",
    "slug": "nordwind-no",
    "legalName": "Nordwind Software AS",
    "tradingName": null,
    "country": "NO",
    "status": "active",
    "verification": {
      "status": "verified",
      "method": "document",
      "checkedAt": "2026-11-03T09:00:00.000Z",
      "reviewer": "usr_01m5wvkry1e6w94sjxgme33fsa",
      "notes": "Extract from Brønnøysundregistrene matches name, address and registry ID.",
      "documentFileId": "file_01m5wvkry1e6w94sjxgme33fsn"
    },
    "address": {
      "line1": "Karl Johans gate 1",
      "line2": null,
      "city": "Oslo",
      "postalCode": "0154",
      "region": null,
      "country": "NO"
    },
    "companyRegistryId": "923 456 789",
    "homeTaxId": {
      "type": "no_vat",
      "value": "NO923456789MVA"
    }
  },
  "waitingSince": "2026-11-03T09:00:00.000Z",
  "documents": [
    {
      "id": "file_01m5wvkry1e6w94sjxgme33fsn",
      "filename": "brreg-extract.pdf",
      "kind": "registry_extract",
      "contentType": "application/pdf",
      "size": 184220,
      "livemode": true,
      "underReview": true,
      "createdAt": "2026-11-02T13:09:41.000Z"
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`entity_verification_not_pending`	409	The entity isn't waiting for document review.	Reload the verification queue: the entity was already approved or rejected, or it was verified another way (VIES, HMRC, CH UID).
`resource_not_found`	404	The organization has no legal entity with this ID.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`validation_failed`	400	A rejection without a reason, or a reason longer than 1,000 characters.	Fix the fields listed in `details.issues` and send the request again.
`version_conflict`	409	The entity changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You aren't a platform admin.	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_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Approve after checking the extract#

Errors#