Reference

Verify API.

Counterparty intelligence over HTTPS. MCP and webhook delivery in private preview. JSON in, structured risk state out.

Private beta. Base URL: https://api.verify.inc/api · /v1 prefix on the roadmap

Authentication.

Authenticated requests send a Bearer JWT (issued by /api/auth/login or /api/auth/signup) together with the workspace X-API-Key.

Self-serve workspace key issuance (planned format vk_live_* / vk_test_*) ships with the v1 API. Today, request a key via viridiana@verify.inc.

Request

GET /api/counterparties/{id}
Authorization: Bearer <JWT>
X-API-Key:     <workspace-key>
Accept:        application/json

Upload an agreement.

Send a contract as multipart/form-data. The response returns extracted parties and signers within seconds. Verification runs in the background and emits events as findings return.

Request

POST /api/contracts/upload
Authorization: Bearer <JWT>
X-API-Key:     <workspace-key>
Content-Type:  multipart/form-data

contract=@agreement.pdf

Response · 202 Accepted

{
  "id":     "ctr_8xq...",
  "status": "extracted",
  "parties": [
    { "name": "Acme Corp",      "type": "business", "role": "buyer"  },
    { "name": "Northpoint LLC", "type": "business", "role": "seller" }
  ],
  "signers": [
    { "name": "M. Webb", "title": "CEO", "party": "Acme Corp" }
  ]
}

Counterparty record.

Every counterparty has a persistent record across agreements. The record tracks all prior screenings, monitoring events, decisions, and reviewer overrides as an append-only history.

GET /api/counterparties/{id}

{
  "_id":              "<ObjectId>",
  "canonicalName":    "Acme Corp",
  "type":             "business",
  "currentRiskBadge": "orange",
  "currentRiskScore": 0.62,
  "domain":           "acme.example",
  "aliases":          [ { "name": "Acme Corp.", "seenAt": "..." } ],
  "screeningCount":   4,
  "firstScreenedAt":  "2025-08-14T11:02:18Z",
  "lastScreenedAt":   "2026-02-09T14:47:09Z",
  "monitoringEnabled": true,
  "monitoringFrequency": "weekly"
}

Monitoring events.

Monitoring profiles produce typed events as counterparty state changes. Events are append-only, ordered per counterparty, and paged.

Event types include screening_completed, sanctions_flag_added, sanctions_flag_cleared, litigation_found, registry_status_changed, risk_badge_changed, monitoring_enabled, monitoring_disabled, verification_rerun, and contract_linked.

GET /api/counterparties/{id}/timeline

{
  "events": [
    {
      "_id":               "<ObjectId>",
      "eventType":         "litigation_found",
      "severity":          "warning",
      "ingestionContext":  { "source": "monitoring", "ingestionTimestamp": "..." },
      "metadata":          { "caseName": "...", "court": "S.D.N.Y." },
      "contractId":        "<ObjectId>",
      "partyId":           "<ObjectId>",
      "createdAt":         "2026-04-12T14:03:22Z"
    }
  ],
  "total": 17, "page": 1, "limit": 50
}

Webhook delivery.

Private preview · delivery semantics finalized at v1

Outbound webhook delivery is in private preview. Today the canonical event surface is the per-counterparty timeline endpoint GET /counterparties/{id}/timeline, which returns the same typed events that future deliveries will carry.

Signing scheme, retry policy, and replay endpoint will be documented as the system exits preview. Reach viridiana@verify.inc to be notified.

Risk state.

Each screened party carries a riskBadge (green · orange · red), a riskScore, and a structured findings object summarizing what was checked.

Risk state transitions are persisted as risk_badge_changed events on the counterparty timeline.

A first-class Decision entity with reviewer overrides and append-only verdict chains is on the roadmap.

Party · screened

{
  "_id":         "<ObjectId>",
  "name":        "Acme Corp",
  "type":        "business",
  "riskBadge":   "orange",
  "riskScore":   0.62,
  "riskReasons": [ "⚠ Court records returned potential matches" ],
  "findings":    {
    "sanctionsHit":         false,
    "courtCases":           2,
    "businessStatus":       "active",
    "registeredJurisdiction": "Delaware"
  }
}

MCP overview.

Private preview · subject to change

An MCP (Model Context Protocol) server is in private preview. The server is a thin wrapper around the REST API and exposes the same capabilities that power the dashboard.

The planned tools are verify_contract, get_counterparty, and list_events. Output shapes match the REST API.

Reach viridiana@verify.inc to request preview access.

Error responses.

Errors return a typed payload with a stable code, a human-readable message, and a request_id for support.

Codes include unauthorized, forbidden, not_found, rate_limited, conflict, invalid_request, internal_error.

Response · 429 Too Many Requests

{
  "code":       "rate_limited",
  "message":    "Workspace exceeded screening quota.",
  "request_id": "req_8x_42a...",
  "retry_after": 30
}

Idempotency keys.

State-changing requests accept an Idempotency-Key header. Verify stores the response associated with each key for 24 hours, and replays the same response on repeat.

Use a unique key per logical operation. Retried requests with the same key produce the same result without side effects.

Request

POST /api/contracts/upload
Authorization:   Bearer <JWT>
X-API-Key:       <workspace-key>
Idempotency-Key: 8b3c1f...-contract-2026-04-12
Content-Type:    multipart/form-data

Signature verification.

Private preview · scheme finalized at v1

Webhook signing ships with the v1 webhook release. The current intent is HMAC-SHA256 over a timestamp plus the raw request body, with a per-tenant secret. A Node.js verifier example and the canonical scheme will be published here once the system exits preview.

Versioned at /v1. Breaking changes are announced 90 days in advance with parallel versions during the deprecation window.

Browse the full operation set in the interactive API reference or download the OpenAPI 3.1 spec.

Need a key, a sandbox, or a security review? viridiana@verify.inc