---
title: "Verify entities in bulk"
method: PUT
path: "/api/v1/verifications"
tags: ["Verifications"]
---

# Verify entities in bulk

`PUT /api/v1/verifications`

## Request

- Base URL: `https://api.getcortexapp.com`
- URL: `https://api.getcortexapp.com/api/v1/verifications`
- Auth: HTTP bearer

Answers many entity-and-period pairs in one call. Each entry is answered on its own merits: an entity the caller may not verify is returned under `errors` while the rest are still recorded, because eligibility depends on who owns each entity. Read `errors` on every response -- a 200 does not mean every entry was recorded.

## Request body

- BulkVerifyRequest: Answers for many entity-and-period pairs
  - `verifications` VerifyEntityEntry[], required: The answers to record
    - `entity` string, required: The entity's tag or CID
    - `periodCid` string, required: The CID of the verification period
    - `reason` string: Why the entity is incorrect. Required when the period sets reasonRequired and the status is VERIFIED_INCORRECT.
    - `status` 'PENDING' | 'VERIFIED_CORRECT' | 'VERIFIED_INCORRECT', required: Whether the entity's data is correct. PENDING is not accepted.

## Response `200`

The entries that were recorded, and the entries that were not

- BulkVerifyResponse: What a bulk verify recorded, and what it declined to record
  - `errors` BulkVerifyError[], required: The entries that were not recorded, each naming the entity and period it came from
    - `code` 'ENTITY_NOT_FOUND' | 'PERIOD_NOT_FOUND' | 'ENTITY_NOT_IN_PERIOD_SCOPE' | 'DUPLICATE_ENTRY' | 'STATUS_NOT_AN_ANSWER' | 'REASON_REQUIRED' | 'PERIOD_NOT_OPEN' | 'MISSING_REQUIRED_ROLE' | 'NOT_AN_OWNER', required: Why the entry was not recorded. Branch on this rather than on the message.
    - `entity` string, required: The entity, as the request named it
    - `message` string, required: The reason in words, fixed to the code rather than written per entry
    - `periodCid` string, required: The verification period
  - `verifications` BulkVerifyResult[], required: The answers that were recorded
    - `entity` string, required: The entity, as the request named it
    - `periodCid` string, required: The verification period
    - `reason` string: Why the entity was marked incorrect, when a reason was given
    - `status` 'PENDING' | 'VERIFIED_CORRECT' | 'VERIFIED_INCORRECT', required: The answer recorded
    - `verifiedAt` string, date-time: When the entity was verified
    - `verifiedByApiKey` ApiKeyVerifier: An API key that verified an entity
      - `name` string: The key's name, or null when it has none
    - `verifiedByUser` CortexUserSummary: The user who verified the entity. Null while the status is PENDING, and null when a global API key verified it.
      - `email` string, required
      - `name` string, required

## Other responses

- `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

## Changes

- **2026-11-03** `a7b058663c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/verifications/put.md)

---

[API](https://skmtc.dev/cortex/apis/cortex-api.md) - [All operations](https://skmtc.dev/cortex/apis/cortex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cortex/apis/cortex-api/revisions/a7b058663c95?raw)