Verification API

Request body

Any other field, at the top level or inside options, is rejected with 400 BAD_REQUEST naming the supported fields, so a misspelled option can never be silently ignored and charged for.

Safe retries: the Idempotency-Key header

This endpoint charges before it answers, so a request that times out or fails with a 5xx on the way back may already have been charged. To retry it safely, send an optional Idempotency-Key header: any opaque token of 1–255 printable ASCII characters with no spaces (a UUID is fine), unique per logical request. Repeating the same request with the same key returns the job the first attempt created and charges nothing more.

curl -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2a4e-3b7d-4e0a-9c11-2d8f5a7b9e01" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

• After dispatch, a repeat answers 200 with "idempotent_replay": true, the receipt's current job_id, "credits_used": 0 and the "status": "pending" shape — read the result or refund for that attempt from GET /v1/jobs/{job_id}. The request claims its uncharged job first; the debit, credit-ledger entry and funded job state then commit together. If a caller stops between that commit and queueing, a repeat safely finishes the interrupted enqueue and returns the normal acceptance or result shape without a second charge. Once a failed attempt is fully refunded, the same key starts a newly charged attempt under a fresh job_id; the old failed job remains terminal (until the refund completes, a repeat returns that failed job uncharged).
• A key identifies one request on this endpoint. Reusing it with a different address or options is refused with 409 IDEMPOTENCY_KEY_CONFLICT before anything is charged. A malformed key is refused with 400 INVALID_IDEMPOTENCY_KEY.
• Keys are scoped to your account and to this endpoint, and a repeat is answered with the receipt's current job throughout its retention window (at least 30 days); only the fully refunded rotation described above changes that current job. Two requests racing with the same key produce one charge and one job.
• Without the header the endpoint behaves exactly as before. The Node and Python SDKs send a key automatically on every verify and batch call from 0.2.0 and retry only requests that carry one; earlier releases and the other SDKs do not.

Example request

curl -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "include_activity": true,
    "options": {
      "deep_verify": true,
      "include_ai": true
    }
  }'

This request runs on every plan. To also receive the enrichment block, add "enrich": true inside options — that option requires the Business plan or higher, and sending it without one returns 403 instead of a verification result.

Response

Shown with every optional block populated. enrichment appears only when you send options.enrich on a Business-or-higher plan, activity only with include_activity, and ai only when AI analysis returns something to report.

{
  "success": true,
  "data": {
    "job_id": "5e809a8a-1d1a-4c92-86f8-2b7395e5d803",
    "email": "john@example.com",
    "status": "risky",
    "sub_status": "catch_all",
    "quality_score": 72,
    "verification": {
      "syntax_valid": true,
      "domain_exists": true,
      "mx_found": true,
      "mx_records": ["mx1.example.com", "mx2.example.com"],
      "smtp_check": true,
      "catch_all": true,
      "greylisted": false,
      "smtp_code": 250,
      "smtp_message": "250 2.1.5 Recipient OK"
    },
    "flags": {
      "disposable": false,
      "role_account": false,
      "free_provider": false,
      "spam_trap": false,
      "abuse_email": false,
      "honeypot": false,
      "complainer": false,
      "bot_generated": false
    },
    "domain_info": {
      "domain": "example.com",
      "provider_type": "corporate",
      "auth_score": 84,
      "auth_grade": "B",
      "has_spf": true,
      "spf_policy": "SoftFail",
      "has_dmarc": true,
      "dmarc_policy": "Quarantine",
      "has_dkim": true
    },
    "enrichment": {
      "first_name": "John",
      "full_name": "John",
      "gender": "male",
      "country": "United States",
      "country_code": "US"
    },
    "ai": {
      "typo_suggestion": null,
      "typo_confidence": null,
      "catch_all_confidence": 15
    },
    "activity": {
      "level": "active",
      "score": 78,
      "last_activity_at": "2026-01-15T10:30:00Z",
      "engagement": { "open_count": 12, "click_count": 5, "reply_count": 1 },
      "deliverability": { "bounce_count": null, "complaint_count": null },
      "confidence": 80,
      "data_points": 18
    },
    "credits_used": 1,
    "credits_remaining": 4998,
    "from_cache": false,
    "processing_time_ms": 1345,
    "verified_at": "2026-02-03T14:22:15.123Z",
    "request_id": "2a4104cd-ef74-4412-89e2-a4859a72bd11"
  }
}

Response fields

Every field a completed result can carry. A field marked as omitted is absent from the JSON rather than null, so read it with a default. Fields are added without a version change; unknown ones are informational.

{
  "success": true,
  "data": {
    "job_id": "8f14e45f-ceea-467a-9a1f-2b0c8f9c4a11",
    "email": "user@example.com",
    "status": "pending",
    "message": "Verification is still in progress. 1 credit is held while processing; if the worker fails before producing a result, job reconciliation refunds it. Use GET /v1/jobs/{job_id} to check status.",
    "credits_held": 1
  }
}

Credits