Entity reviews

Get a review

GET /api/v1/entity_reviews/:id

Needs entity.review.view. Returns the review with a summary of its entity.

curl -H "Authorization: Bearer $VERITY_API_KEY" \
     https://your-host/api/v1/entity_reviews/7

{
  "entity_review": {
    "id": 7,
    "entity_id": 42,
    "purpose": "periodic",
    "status": "in_progress",
    "outcome": "pending_manual_review",
    "outcome_reason": "periodic_cycle",
    "assigned_user_id": 3,
    "started_at": "2026-06-28T08:00:00Z",
    "completed_at": null,
    "updated_at": "2026-06-28T08:40:00Z",
    "entity": {
      "id": 42,
      "registration_number": "7555555555",
      "legal_name": "API Review Entity",
      "country_id": 1,
      "status": "ready_for_review",
      "current_score": 81,
      "risk_level": "high",
      "risk_level_updated_at": "2026-06-28T08:00:00Z",
      "sanctions_status": "needs_review"
    },
    "notes_count": 1,
    "checks_count": 1
  }
}

Fields

Field	Type	Notes
purpose	string	initial or periodic
status	string	open, in_progress, escalated, completed, cancelled
outcome	string | null	Set when the review completes
outcome_reason	string | null	The triggering reason recorded with the decision
assigned_user_id	integer | null
started_at, completed_at, updated_at	string | null	ISO 8601
notes_count, checks_count	integer

The nested entity follows the same risk_level rule as everywhere else: the band appears only with risk_level_updated_at, and otherwise reads "risk_level": null, "risk_level_assessed": false.

current_score (coverage) is reported independently — an entity can be well covered and never assessed.

No write endpoints

Approving, rejecting, escalating and assigning are not available over the API. Each is a human decision that must carry an actor, a reason and an audit record, and several are gated on blockers that only make sense in front of someone who can resolve them.

To react to decisions programmatically, subscribe to outbound webhooks.