Check Validation Status

Monitor the progress of your bulk email validation requests using our status check endpoint.

API Reference

Endpoint

GET https://api.cliova.com/v1/webhooks/email-validations/bulk-emails/${listId}/status?apiKey=${apiKey}

List ID

The id parameter is returned in the response of your bulk upload request (e.g., list_12345)

Parameters

Path Parameters

Parameter	Required	Type	Description
id	Yes	string	The unique identifier of your email list

Query Parameters

Parameter	Required	Type	Description
apiKey	Yes	string	Your API authentication key

Code Examples

JavaScript

statusChecker.js

async function checkValidationStatus(apiKey, listId) {
  const url = `https://api.cliova.com/v1/webhooks/email-validations/bulk-emails/${listId}/status?apiKey=${apiKey}`;
  const response = await fetch(url, {
    method: "GET",
    headers: { Accept: "application/json" },
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return response.json();
}

// Usage Example
checkValidationStatus("your_api_key", "list_12345")
  .then((status) => console.log("Status:", status))
  .catch((error) => console.error("Status check failed:", error));

Python

status_checker.py

import requests
from typing import Dict, Any

def check_validation_status(api_key: str, list_id: str) -> Dict[str, Any]:
    """
    Check the status of an email validation job with a single request.

    Args:
        api_key (str): Your API key.
        list_id (str): The ID of the validation job.

    Returns:
        Dict[str, Any]: The API response in JSON format.

    Raises:
        requests.exceptions.RequestException: If the API request fails.
    """
    url = f'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails/{list_id}/status'
    response = requests.get(url, params={'apiKey': api_key})
    response.raise_for_status()
    return response.json()

# Usage Example
if __name__ == '__main__':
    try:
        status = check_validation_status('your_api_key', 'list_12345')
        print('Status:', status)
    except Exception as e:
        print('Status check failed:', e)

PHP

StatusChecker.php

<<?php

function checkValidationStatus(string $apiKey, string $listId): array {
    $baseUrl = 'https://api.cliova.com/v1/webhooks/email-validations/bulk-emails';
    $url = sprintf(
        '%s/%s/status?apiKey=%s',
        $baseUrl,
        urlencode($listId),
        urlencode($apiKey)
    );

    $curl = curl_init();
    curl_setopt_array($curl, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Accept: application/json']
    ]);

    $response = curl_exec($curl);
    if ($response === false) {
        throw new RuntimeException(curl_error($curl));
    }

    $statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);

    if ($statusCode !== 200) {
        throw new RuntimeException("API request failed with status code: {$statusCode}");
    }

    return json_decode($response, true);
}

// Usage Example
try {
    $status = checkValidationStatus('your_api_key', 'list_12345');
    echo "Status:\n" . json_encode($status, JSON_PRETTY_PRINT);
} catch (Exception $e) {
    echo "Status check failed: " . $e->getMessage();
}

Response Example

{
  "code": "SUCCESS",
  "message": "Successfully performed operation.",
  "payload": [
    {
      "id": "10a65f89-5de0-403a-a1ea-8ceea94a4ad9",
      "name": "Email List",
      "orgId": "8e69b5b1248716cf",
      "totalEmails": 2000,
      "totalValidEmails": 1500,
      "totalCreditsUsed": 2000,
      "status": "COMPLETED",
      "environment": "production",
      "apiKeyId": "6510a65f-10a65f8-90a25h8",
      "userId": "user_2sc3RYDvOtBEXNHtXH7Qm8jaFUW",
      "createdAt": "2025-02-12T12:43:13.087Z",
      "updatedAt": "2025-02-12T12:43:13.087Z",
      "deletedAt": null
    }
  ]
}

Status Codes

Status	Description
IN PROGRESS	Validation is in progress
COMPLETED	Validation completed successfully
FAILED	Validation failed due to an error

Need Help?

Support Resources

• 📘 API Documentation
• 📧 Support Email