API Documentation

Overview

The Zuhal API is a RESTful interface designed for developers who need to verify email addresses programmatically. Whether you need to validate a single email during user registration or clean a list of 1 million contacts, our API scales to meet your needs.

We support JSON responses for all endpoints and use standard HTTP response codes to indicate errors.

Authentication

Every API request must be authenticated using your unique API Key. You can find or regenerate your key in the Dashboard > Developer Settings.

Pass the key in the HTTP Header of your request. Do not expose this key in client-side code (frontend JavaScript).

Authorization: Bearer YOUR_API_KEY_HERE

1. Single Verification

The Single Verify endpoint is optimized for real-time applications. Use this to validate emails instantly as users type them into your registration forms, newsletter signups, or contact pages.

Best for: Preventing typos, blocking disposable emails, and ensuring high-quality signups.

{
  "email": "klem@viableview.com"
}

{
  "status": "success",
  "message": "Email verified successfully.",
  "data": {
    "request_id": "b3f1c2a0-...",
    "email": "klem@viableview.com",
    "email_status": "valid",
    "credits_used": 1,
    "remaining_credits": 4999
  }
}

2. Bulk Upload

For lists larger than 100 emails, use the Bulk API. This process is asynchronous: you upload the file, we process it in the background, and you download the results later.

How it works: 1. Upload a CSV file via this endpoint. 2. You will receive a unique job_id immediately. 3. Use this ID to poll the status endpoint.

{
  "status": "success",
  "message": "File uploaded successfully. Use job_id to check status.",
  "data": {
    "job_id": "1502d7c5-7575-4b4a-816c...",
    "job_status": "processing",
    "credits_used": 5000,
    "remaining_credits": 95000,
    "total_records": 5000
  }
}

3. Check Status

Use this endpoint to monitor the progress of your bulk job. We recommend polling this endpoint every 10-30 seconds.

Note on Deep Validation: If your job triggers the Deep Validation layer, the status will stay as processing for a longer period (up to 60 mins). Do not abort the job; the system is actively working on hard-to-verify emails.

{
  "status": "success",
  "message": "Job status retrieved successfully.",
  "data": {
    "job_id": "1502d7c5...",
    "job_status": "completed",
    "total_emails": 5000,
    "completed": 5000,
    "valid": 4230,
    "invalid": 610,
    "disposable": 95,
    "catch_all": 55,
    "unknown": 10,
    "percentage_complete": "100.00",
    "started_at": "2026-08-10T09:00:00.000000Z",
    "last_updated_at": "2026-08-10T09:04:12.000000Z"
  }
}

4. Download Results

Once the status returns completed, call this endpoint to retrieve the URL of your verified file. The file will contain your original data plus new columns for verification status (Valid, Invalid, Unknown, Disposable).

{
  "status": "success",
  "message": "Download link generated successfully.",
  "data": {
    "job_id": "1502d7c5...",
    "job_status": "completed",
    "download_link": "https://zuhal.io/api/v1/bulk/download/1502d7c5.../file"
  }
}

5. Delete Job

For security and privacy, you may permanently delete your file and results from our server once you have downloaded them. Otherwise, files are automatically deleted after 30 days.

Status Codes

Zuhal uses standard HTTP response codes to indicate the success or failure of an API request. Error responses follow the same envelope as success responses, with "status": "error" and a human-readable message; a small number of errors (job/file not found) also include a machine-readable code field (e.g. ERR_NOT_FOUND).

Rate Limits

Limits are applied per API key (falling back to IP address if no key is present) and reset every 60 seconds.