---
title: "Get a single verification result."
method: GET
path: "/v1/verify/{id}"
---

# Get a single verification result.

`GET /v1/verify/{id}`

## Request

- Base URL: `https://api.bounceless.io`
- URL: `https://api.bounceless.io/v1/verify/{id}`
- Auth: API key in header `X-Api-Key`

Poll the verifyRequestId returned by a 202 POST /v1/verify (for example every 2s under a client deadline) until status is completed or failed. running keeps the hold held and bills nothing; the first terminal result settles the charge once, and later reads return the stored result unchanged. Unknown ids, ids of another account, and accounts without async results enabled return 404 not_found.

## Path parameters

- `id` string, uuid, required

## Response `200`

Current result.

- VerifyRequestResult
  - `status` 'running' | 'completed' | 'failed', required
  - `resultCategory` 'deliverable' | 'catch_all' | 'unknown' | 'undeliverable' | 'risky' | 'recheck' | 'pending' | 'other'
  - `verifyRequestId` string, uuid
  - `createdAt` string, date-time
  - `decision` object, nullable
  - `presend` ClientDecisionEnvelopeV1, required
    - `contract_version` 1, required
    - `status` 'running' | 'completed' | 'deferred' | 'recheck_scheduled' | 'failed' | 'rejected', required
    - `outcome` 'pending' | 'actionable_verdict' | 'non_verdict', required
    - `decision` 'send' | 'suppress' | 'send_with_caution' | 'enrich_first' | 'recheck_later' | 'manual_review', nullable, required
    - `verdict` 'DELIVERABLE' | 'UNDELIVERABLE_NO_MAILBOX' | 'UNDELIVERABLE_NO_MAIL_SERVER' | 'UNDELIVERABLE_BOUNCED' | 'CATCH_ALL' | 'MAILBOX_FULL' | 'DISPOSABLE' | 'ROLE' | 'SPAMTRAP' | 'RISKY_SPAMTRAP' | 'BLACKLISTED' | 'GREYLISTED' | 'TRANSIENT' | 'UNKNOWN' | 'UNKNOWN_WEBMAIL', nullable, required
    - `provider_family` string, nullable, required
    - `confidence` number, nullable, required
    - `reasons` string[], required
    - `evidence_class` string, nullable, required
    - `retry` object, nullable, required
      - `eligible_at` string
      - `expires_at` string
      - `affinity_required` boolean
    - `billing` object, required
      - `disposition` 'held' | 'debited' | 'released', required
      - `credits` integer, nullable, required: Actually settled normal verification credits; null when exact historical row attribution is unavailable. New standard jobs include catch-all resolution with no supplemental debit; historical jobs retain their accepted quote. Catch-all charges are reported separately.
    - `history` object, nullable, required
  - `evidence` ControlEvidence[]: Optional per-check evidence (BL-11576). Present only for checks the engine actually reported; the key is omitted when none were. A missing check means unavailable, never pass. Never derived from the verdict.
    - `kind` 'format' | 'mx' | 'mailbox' | 'catch_all' | 'risk', required
    - `state` 'pass' | 'fail' | 'unknown' | 'not_run', required: Taken from the engine classification of that check (SMTP matched rule, catch-all reason), never the raw SMTP code class. unknown = ran, inconclusive (incl. greylist, or a block of our sending IP); not_run = engine attested it did not run; fail = ran with an unfavourable observation.
    - `reason` string, required: Stable machine token, e.g. rcpt_accepted, rcpt_rejected, mailbox_full, rcpt_inconclusive, probe_not_attempted, catch_all_detected, catch_all_ruled_out, catch_all_unconfirmed, list_match.
    - `observedAt` string, date-time, nullable, required: Engine observation instant (cycle attestation, else engine verified_at). null when the engine did not provide one.
    - `provenance` object, nullable, required
      - `mechanism` string, nullable, required
      - `mechanismRevision` string, required
      - `freshness` 'fresh_probe' | 'fresh_cache', required
    - `measurement` object: Allowlisted measurements (smtpCode, enhancedCode, probes, accepts, quorum, list).
  - `checks` Checks: Per-control checks (BL-11693, engine wire BL-11692). Always four keys. States are the engine's, passed through; a check the engine did not emit is {state:"unknown", reason_code:"evidence_unavailable"}. Never derived from the verdict.
    - `syntax` Check, required
      - `state` 'passed' | 'failed' | 'unknown' | 'not_run' | 'error', required
      - `reason_code` string, required: Machine token; evidence_unavailable when the engine emitted nothing usable.
      - `observed_at` string, date-time
      - `detail` string: Machine token only; free text is never forwarded.
    - `mail_records` Check, required
      - `state` 'passed' | 'failed' | 'unknown' | 'not_run' | 'error', required
      - `reason_code` string, required: Machine token; evidence_unavailable when the engine emitted nothing usable.
      - `observed_at` string, date-time
      - `detail` string: Machine token only; free text is never forwarded.
    - `mailbox` Check, required
      - `state` 'passed' | 'failed' | 'unknown' | 'not_run' | 'error', required
      - `reason_code` string, required: Machine token; evidence_unavailable when the engine emitted nothing usable.
      - `observed_at` string, date-time
      - `detail` string: Machine token only; free text is never forwarded.
    - `risk` Check, required
      - `state` 'passed' | 'failed' | 'unknown' | 'not_run' | 'error', required
      - `reason_code` string, required: Machine token; evidence_unavailable when the engine emitted nothing usable.
      - `observed_at` string, date-time
      - `detail` string: Machine token only; free text is never forwarded.
  - `engine` VerifyEngine
    - `verifiedAt` string, nullable
    - `attempts` integer, nullable
    - `providerFamily` string, nullable
  - `isRole` boolean, nullable: Engine role label (BL-11811). Not a check, never gating; null when the engine did not emit it.
  - `requestId` string, required

## Other responses

- `401`: Error response.
- `404`: Error response.
- `429`: Rate limit exceeded.

---

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