POST /v1/verify

Convenience endpoint: lookup-or-create an entity, then run verification checks in a single call.

For standalone verification against an already-resolved entity, use POST /v1/verifications.

Request

POST https://api.vendorval.com/v1/verify
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body — with entity ID

{
  entity_id: string
  checks: Array<"sam_registration" | "tin_match">
  mode: "cached" | "realtime"
}

Body — with identifiers (lookup-or-create)

{
  identifiers: Array<{ type: "uei" | "tin" | "duns" | "cage"; value: string }>
  legal_name?: string
  checks: Array<"sam_registration" | "tin_match">
  mode: "cached" | "realtime"
}

Example

{
  "entity_id": "ent_01abc...",
  "checks": ["sam_registration", "tin_match"],
  "mode": "cached"
}

Response

200

{
  id: string
  entity_id: string
  overall_result: "pass" | "fail" | "error"
  results: Array<{
    check_type: string
    status: "pass" | "fail" | "error"
    confidence: number
    origin: string
    determinism: "deterministic" | "stochastic"
    data_freshness_seconds: number
    evidence_uri: string
  }>
  created_at: string
}

Example response

{
  "id": "ver_01xyz...",
  "entity_id": "ent_01abc...",
  "overall_result": "pass",
  "results": [
    {
      "check_type": "sam_registration",
      "status": "pass",
      "confidence": 0.99,
      "origin": "sam_gov",
      "determinism": "deterministic",
      "data_freshness_seconds": 43200,
      "evidence_uri": "s3://vendorval-evidence/ver_01xyz/sam_registration.json"
    }
  ],
  "created_at": "2026-04-19T12:00:00Z"
}

overall_result logic

Condition	overall_result
All checks pass	pass
Any check fail	fail
Any check error, none fail	error

Provider fallback

If a realtime provider throws (timeout, HTTP error, auth failure), the next provider in priority order is tried automatically. If a provider returns fail, fallback does not trigger — that result is final.