Verification

Verification runs one or more checks against a resolved entity and returns pass/fail results with source attribution and stored evidence.

Endpoint

POST /v1/verify

This is the convenience endpoint: it accepts either an entity_id (if you've already resolved) or raw identifiers (lookup-or-create + verify in one call).

For standalone verification jobs, use POST /v1/verifications.

Check types

Check	Provider	Description
sam_registration	SAM.gov	Is the entity registered and active?
tin_match	IRS TIN Matching	Does EIN + legal name match IRS records?

Modes

Cached (mode: "cached")

Returns data from VendorVal's entity store, synced nightly from SAM.gov. Responses in 20–80ms.

Use for: dashboards, batch processing, non-time-sensitive compliance checks.

Realtime (mode: "realtime")

Makes a live call to the source provider at request time. Responses in 500ms–5s.

Use for: onboarding flows, payment approvals, any check where stale data is unacceptable.

Provider fallback

If a realtime provider throws (timeout, auth error, unavailable), VendorVal automatically falls back to the next-priority provider. A provider that returns fail does not trigger fallback — that result is terminal.

Request

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

Or resolve-and-verify in one call:

{
  "identifiers": [{ "type": "uei", "value": "ABCD12345678" }],
  "legal_name": "Acme Federal Services LLC",
  "checks": ["sam_registration"],
  "mode": "realtime"
}

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"
    },
    {
      "check_type": "tin_match",
      "status": "pass",
      "confidence": 0.95,
      "origin": "irs_tin_matching",
      "determinism": "stochastic",
      "data_freshness_seconds": 0,
      "evidence_uri": "s3://vendorval-evidence/ver_01xyz/tin_match.json"
    }
  ],
  "created_at": "2026-04-19T12:00:00Z"
}

Result fields

Field	Description
overall_result	pass if all checks passed, fail if any failed, error if a provider errored
status	Per-check result: pass, fail, or error
confidence	0–1 confidence score for this result
origin	Which provider produced this result
determinism	deterministic (same input → same output) or stochastic
data_freshness_seconds	How old the underlying data is; 0 means realtime
evidence_uri	Immutable stored evidence artifact for audit

SAM.gov verification

Checks whether the entity has an active SAM.gov registration. A fail result means the entity is either not registered or debarred/excluded.

The data_freshness_seconds field tells you when the underlying SAM.gov data was last pulled. For cached mode this is typically 0–86400 seconds (nightly sync). For realtime mode it is always 0.

IRS TIN matching

Verifies the EIN and legal name combination against IRS records. Returns:

• pass — name and EIN match IRS records
• fail — mismatch; the reason is included in the evidence artifact
• error — IRS service unavailable or rate limited

IRS rate limits

IRS TIN matching has daily call limits per tenant. VendorVal enforces duplicate lockouts (same entity won't be re-checked within 24h) and respects IRS gateway blackout windows automatically.