The Verifier
API

Understand the lifecycle first

An email verdict, a completed job, and a final result set are three different things.

There are three different meanings of status: an email classification (valid, invalid, unknown, catch-all, out-of-storage), a main job status (such as processing or completed), and additional_checks.status for tracked follow-up work. Never compare values from one layer with another.

Advanced verification is automatic follow-up work for eligible uncertain addresses, including provider-specific checks and slower SMTP paths. It can improve unknown or catch-all classifications after the main pass. Eligibility and available checks vary; not every uncertain address gets a definitive answer.

track_finality does not turn on every advanced check. It opts a new bulk job into durable tracking and sealing so your integration knows when automatic result changes have ended. Single verification is synchronous and does not return a bulk job ID for these companion endpoints.

Choose fast results when you can tolerate later classification changes: submit normally, wait for completed, then read/export. Choose stable results for a fixed downstream report: submit with track_finality: true, save the ID, wait for results_final === true, then begin pagination or export.

Backward compatibility: track_finality defaults to false. Existing response shapes, main status values, progress, completed_at, completion-email timing, CSV columns and billing semantics stay unchanged. Main progress is not held at 99%; completed and 100% still refer to the main pass. There is no finality webhook or new final-only export endpoint.

Main job states

If you encounter an unfamiliar state, preserve the raw response and job ID and alert your operator. Do not assume success or poll forever. paused is included because an existing or reused job can be paused; this guide does not promise a public pause/resume endpoint.

Advanced verification states

Why checks stopped

Suggested UI copy for completed plus nonfinal results: “Main verification complete. Advanced verification in progress; results may change.” Show separate warnings for untracked or aborted runs. A finished run with expired or failed checks also deserves an outcome warning.

Quickstart

Verify your first address in 60 seconds.

# Verify a single email
curl -X POST https://app.optimaverifier.com/api/v1/verifications/single \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada.lovelace@example.com"}'

Authentication

Authenticate requests with an Optima API key in the standard bearer-token header.

Authorization: Bearer <api_key>
Content-Type:  application/json

{
  "detail": "Could not validate credentials"
}

Base URL

A single versioned host serves every customer. Your API key identifies the account.

https://app.optimaverifier.com/api/v1/{resource}

// e.g.
https://app.optimaverifier.com/api/v1/verifications/single
https://app.optimaverifier.com/api/v1/verifications/bulk
https://app.optimaverifier.com/api/v1/verifications/job/{job_id}

Verify one email

Synchronous verification for signup forms and account changes. Response time depends on the receiving provider; set a request timeout and handle inconclusive results.

curl -X POST https://app.optimaverifier.com/api/v1/verifications/single \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada.lovelace@example.com"}'

{
  "email": "ada.lovelace@example.com",
  "status": "valid",
  "verified_at": "2026-05-25T10:30:00.123456+00:00",
  "credits_remaining": 4999
}

Bulk verify · submit a JSON array

Submit up to 1 million emails per request as a JSON array. We deduplicate, queue, and return a job id immediately.

Workflow

curl -X POST https://app.optimaverifier.com/api/v1/verifications/bulk \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["ada@example.com", "marcus@brand.co", "rachel@nope.invalid"],
    "job_name": "May newsletter sweep"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "job_name": "May newsletter sweep",
  "status": "queued",
  "total_rows": 2964,
  "original_count": 3001,
  "duplicate_count": 37,
  "processed_rows": 0,
  "valid_count": 0,
  "invalid_count": 0,
  "unknown_count": 0,
  "catch_all_count": 0,
  "created_at": "2026-05-25T10:30:00+00:00",
  "completed_at": null,
  "credits_reserved": 2964
}

Bulk verify · upload a file

For lists too large to JSON-encode. Send a multipart upload with a .txt file - one email per line.

curl -X POST https://app.optimaverifier.com/api/v1/verifications/bulk/upload \
  -H "Authorization: Bearer <api_key>" \
  -F "file=@my-list.txt" \
  -F "job_name=Q2 contacts"

Poll a job

Poll every 5–15 seconds. Save the job ID and bound both each request and your overall wait.

Existing/fast workflow (unchanged): completed means the main pass is ready to download. Advanced checks may still update unknown/catch-all addresses. Integrations needing a stable result set can opt into finality tracking; existing clients need no migration.

# One status read, not a polling loop. Save JOB_ID from your submission.
curl --fail-with-body --connect-timeout 10 --max-time 30 -sS \
  "https://app.optimaverifier.com/api/v1/verifications/job/$JOB_ID" \
  -H "Authorization: Bearer $OPTIMA_API_KEY"
# Inspect status using the lifecycle table. completed is main-pass completion only.
# For a bounded wait-and-export Bash example, see Advanced verification & finality.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "progress_percentage": 47.3,
  "total_rows": 2964,
  "processed_rows": 1402,
  "valid_count": 1284,
  "invalid_count": 95,
  "unknown_count": 17,
  "catch_all_count": 6
}

Advanced verification & finality

Know when results stop changing, not just when the main pass reaches 100%.

1. Opt in when creating a bulk job

Send track_finality: true in the JSON request, or track_finality=true in a multipart TXT upload. The default is false. A newly created job returns 201; duplicate reuse returns 200 and reused: true, with no additional charge. Both use the same legacy response shape. Save the returned ID.

Enrollment is rolled out gradually. An explicit 503 enrollment rejection happens before a new job or charge; honor Retry-After. Do not silently fall back to untracked results if your integration requires a stable report.

Opting in does not enroll reused historical jobs. If a reused job is not_tracked, stop waiting. Accept the legacy result or explicitly submit with force: true to create a new, normally charged run. Never force automatically after a timeout.

2. Read the companion finality endpoint

Use your existing bearer key. Reads do not start checks or consume credits and return Cache-Control: no-store. The batch query accepts comma-separated public IDs, deduplicates them in request order, and returns {"items": [...]}. Empty IDs, IDs longer than 36 characters, or more than 100 distinct IDs return 422. Any missing or foreign ID makes the entire batch return the same generic 404.

Response examples

Every example is a complete single-job response. For batch reads, place these objects inside items. See the state tables for the action associated with each state.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "results_final": false,
  "results_revision": 12,
  "results_updated_at": "2026-09-14T09:12:00Z",
  "finalized_at": null,
  "additional_checks": {
    "status": "running",
    "total": 5,
    "pending": 2,
    "finished": 3,
    "upgraded": 2,
    "failed": 1,
    "expired": 0,
    "deadline_at": "2026-09-14T10:00:00Z",
    "stop_reason": null
  }
}

3. Wait, inspect the outcome, then export

# Bash, curl and jq required. OPTIMA_API_KEY is a server-side environment variable.
set -euo pipefail
BASE=https://app.optimaverifier.com/api/v1/verifications
JOB=$(curl --fail-with-body --connect-timeout 10 --max-time 30 -sS "$BASE/bulk" \
  -H "Authorization: Bearer $OPTIMA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"emails":["ada@example.com"],"job_name":"Tracked run","track_finality":true}')
# Submit 503 means enrollment unavailable, with no new charge. Do not blindly retry POST.
JOB_ID=$(jq -er '.id' <<< "$JOB")
echo "Save job ID: $JOB_ID"
END=$((SECONDS + 7200))
FINAL=false
POLL_DIR=$(mktemp -d)
trap 'rm -f "$POLL_DIR/headers" "$POLL_DIR/body"; rmdir "$POLL_DIR"' EXIT
while (( SECONDS < END )); do
  REMAINING=$((END - SECONDS))
  REQUEST_TIMEOUT=$((REMAINING < 30 ? REMAINING : 30))
  if ! CODE=$(curl --connect-timeout 10 --max-time "$REQUEST_TIMEOUT" -sS \
      -D "$POLL_DIR/headers" -o "$POLL_DIR/body" -w '%{http_code}' \
      -H "Authorization: Bearer $OPTIMA_API_KEY" "$BASE/job/$JOB_ID/finality"); then
    REMAINING=$((END - SECONDS))
    (( REMAINING <= 0 )) && break
    sleep $((REMAINING < 10 ? REMAINING : 10)); continue
  fi
  if [[ "$CODE" == 429 || "$CODE" == 5?? ]]; then
    RETRY=$(awk 'tolower($1)=="retry-after:" {$1=""; sub(/^ /, ""); sub(/\r$/, ""); print}' "$POLL_DIR/headers")
    DELAY=10
    if [[ "$RETRY" =~ ^[0-9]+$ ]]; then DELAY=$RETRY
    elif [[ -n "$RETRY" ]]; then
      # GNU date handles Retry-After's HTTP-date form.
      WHEN=$(date -d "$RETRY" +%s 2>/dev/null || date +%s)
      DELAY=$((WHEN - $(date +%s)))
    fi
    (( DELAY < 1 )) && DELAY=1
    REMAINING=$((END - SECONDS))
    (( REMAINING <= 0 )) && break
    sleep $((DELAY < REMAINING ? DELAY : REMAINING)); continue
  fi
  [[ "$CODE" == 200 ]] || { echo "Finality HTTP $CODE; stop and fix credentials/request"; exit 1; }
  jq -e . "$POLL_DIR/body" >/dev/null
  if ! jq -e '(.status == "queued" or .status == "processing" or .status == "completed" or .status == "error" or .status == "canceled") and (.additional_checks.status == "waiting" or .additional_checks.status == "running" or .additional_checks.status == "finished" or .additional_checks.status == "aborted" or .additional_checks.status == "not_tracked")' "$POLL_DIR/body" >/dev/null; then
    echo 'Paused or unrecognized state; retain the ID and investigate'; exit 1
  fi
  if jq -e '.status == "error" or .status == "canceled" or .additional_checks.status == "aborted" or .additional_checks.status == "not_tracked" or .results_final == null' "$POLL_DIR/body" >/dev/null; then
    echo 'Run aborted/untracked; stop waiting. Forcing a new run costs credits.'; exit 1
  fi
  if jq -e '.results_final == true and .status == "completed" and .additional_checks.status == "finished"' "$POLL_DIR/body" >/dev/null; then
    FINAL=true; jq '.additional_checks' "$POLL_DIR/body"; break
  fi
  jq -e '.results_final == false and .additional_checks.status != "finished"' "$POLL_DIR/body" >/dev/null || { echo 'Inconsistent finality response'; exit 1; }
  REMAINING=$((END - SECONDS))
  (( REMAINING <= 0 )) && break
  sleep $((REMAINING < 10 ? REMAINING : 10))
done
[[ "$FINAL" == true ]] || { echo 'Timed out; retain the job ID'; exit 1; }
curl --fail-with-body --max-time 60 -sS -H "Authorization: Bearer $OPTIMA_API_KEY" \
  "$BASE/job/$JOB_ID/export?format=csv"

Read paginated results

Per-row results for a completed (or in-progress) bulk job.

For a stable report, wait for finality before requesting page 1. Otherwise rows, classifications and filtered totals may change between requests. total_count describes the selected filter; total_pages is at least 1 even for an empty result set. Stop on an empty page or when you have consumed the returned total.

curl "https://app.optimaverifier.com/api/v1/verifications/job/<job_id>/results?page=1&per_page=50" \
  -H "Authorization: Bearer <api_key>"

{
  "id": "a1b2c3d4-...",
  "job_name": "May newsletter sweep",
  "total_count": 2964,
  "page": 1,
  "per_page": 50,
  "total_pages": 60,
  "results": [
    { "email": "ada@example.com", "status": "valid", "verified_at": "2026-09-14T09:12:00+00:00" },
    { "email": "rachel@nope.invalid", "status": "invalid", "verified_at": "2026-09-14T09:12:00+00:00" }
  ]
}

Export CSV

Stream the full per-row result set as a CSV file. Echoes back any row_metadata columns you submitted.

The main job must be completed; otherwise export returns 400. For stable results, additionally wait for results_final === true. Use a temporary file for large downloads and publish it only after the download succeeds.

curl --fail --connect-timeout 10 --max-time 300 "https://app.optimaverifier.com/api/v1/verifications/job/<job_id>/export?format=csv" \
  -H "Authorization: Bearer <api_key>" \
  -o results.csv

Custom report

Download only the rows you need: pick the statuses, and optionally keep or drop free-mailbox and role addresses. Check the row count first, then download.

The main job must be completed to download. This is separate from Export CSV, which is unchanged.

# 1. How many rows would the report contain?
curl --fail --connect-timeout 10 --max-time 60 \
  "https://app.optimaverifier.com/api/v1/verifications/job/<job_id>/custom-report/count?statuses=out-of-storage,unknown&free=yes" \
  -H "Authorization: Bearer <api_key>"
# {"total_count": 105}

# 2. Download exactly those rows
curl --fail --connect-timeout 10 --max-time 300 \
  "https://app.optimaverifier.com/api/v1/verifications/job/<job_id>/custom-report?statuses=out-of-storage,unknown&free=yes" \
  -H "Authorization: Bearer <api_key>" \
  -o custom_report.csv

Verification history

All single verifications the user has run, newest first. Bulk results live on each job's /results endpoint instead.

curl "https://app.optimaverifier.com/api/v1/verifications/history?page=1&per_page=50" \
  -H "Authorization: Bearer <api_key>"

Find existing jobs

Recover a job ID or reconcile a submission whose response was interrupted.

Query parameters: page (default 1), per_page (default 50, clamped to 1–100), optional status (main job state), and optional search (job-name match).

The response is a JSON array of BulkJobResponse objects, not an items wrapper. An empty array means no matching jobs on that page. Use the same bearer authentication.

GET https://app.optimaverifier.com/api/v1/verifications/jobs?page=1&per_page=50&search=My%20import
Authorization: Bearer <api_key>

After an ambiguous POST timeout, check here or in the dashboard before resubmitting. Names and list matching are not an idempotency guarantee. Do not invent an Idempotency-Key contract or automatically use force=true.

Check balance

Returns the current credit balance and the 20 most recent ledger entries.

curl "https://app.optimaverifier.com/api/v1/credits" \
  -H "Authorization: Bearer <api_key>"

{
  "balance": 4999,
  "recent": [
    {
      "delta": -1,
      "reason": "consume",
      "balance_after": 4999,
      "note": null,
      "created_at": "2026-05-25T10:30:00+00:00"
    }
  ]
}

Status vocabulary

These are per-email classifications, not job states or HTTP error codes.

HTTP 200 means the API request succeeded, even when an email is invalid. Until a tracked job is final, an address’s classification can change through advanced verification.

Errors

API errors include a detail field; it may be a string, an object or a list. Intermediaries may return non-JSON errors, so check HTTP status before parsing.

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "emails"],
      "msg": "List should have at most 1000000 items",
      "input": []
    }
  ]
}

Quotas & limits

Per-user limits enforced server-side.

Before going live

Test your integration against outcomes, not just the happy path.

• Keep keys server-side. Persist job IDs durably and redact credentials from logs.
• Choose preliminary or stable results explicitly. Keep email, main-job and advanced-check states separate.
• Test queued → processing → completed with checks still running; never export early in a stable-results workflow.
• Test natural finality, no checks, failed checks and deadline expiry. Do not turn unknown or catch-all into valid in your app.
• Test duplicate reuse of an untracked job, paused jobs, error, canceled, incomplete and an unfamiliar future state.
• Test 401/402/403/404/422, 429 with Retry-After, 503 enrollment unavailable and a network timeout after POST.
• Use bounded GET retries and polling deadlines. Client timeouts do not cancel jobs; retain the ID to resume.
• For stable reports, wait before the first page/export. Use returned pagination totals; avoid combining pages fetched before and after result changes.
• Stream large downloads. Preserve the unchanged CSV header and supplied metadata columns.

When escalating a problem, include the public job ID, endpoint, HTTP status, UTC time, main status, finality status, revision and stop reason. Never send your bearer key.