# Approve or reject a legal entity's verification

> The platform.verifications.decide operation: POST /api/v1/platform/verifications/{orgId}/{entityId}/decide in the REST API and the platform_verifications_decide tool in the MCP server.

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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](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 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](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_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), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).