Documentation7 min read

Integration Examples: cURL, Node.js, Web, and PHP

This article provides a minimal working request for each of five common integration environments. Each example sends a GET request to the /validate endpoint and reads the status field from the response. The request and response format are described in the API Reference article.

cURL

The command sends a request using an API key stored in an environment variable.

curl -H "X-API-Key: $CLEANCONTACT_KEY" \
  "https://api.cleancontact.ru/validate?email=someone@example.com"

Node.js (JavaScript)

The example uses the fetch function built into Node.js 18 and later. No additional package is required. The key is read from an environment variable and does not appear in source code.

const API_KEY = process.env.CLEANCONTACT_KEY

async function validateEmail(email) {
  const params = new URLSearchParams({ email })
  const response = await fetch(`https://api.cleancontact.ru/validate?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json()
}

validateEmail('someone@example.com')
  .then((data) => console.log(data.result.status))

Node.js (TypeScript)

The same request with explicit types for the response shape. The status field is restricted to the three values returned by the endpoint.

const API_KEY = process.env.CLEANCONTACT_KEY as string

type ValidationStatus = 'Good' | 'Bad' | 'Unknown'

interface ValidationResult {
  value: string
  result: {
    status: ValidationStatus
    detail: string
  }
}

async function validateEmail(email: string): Promise<ValidationResult> {
  const params = new URLSearchParams({ email })
  const response = await fetch(`https://api.cleancontact.ru/validate?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  })
  return response.json() as Promise<ValidationResult>
}

validateEmail('someone@example.com')
  .then((data) => console.log(data.result.status))

Web (JavaScript)

A request issued directly from the browser requires a key of the public type, protected by a captcha challenge, as described in the Authentication and API Keys article. A server key must not appear in browser code. The captchaToken value in the example is obtained from the captcha widget before the request is sent.

const params = new URLSearchParams({ email, captchaToken })

fetch(`https://api.cleancontact.ru/validate?${params}`, {
  headers: { 'X-API-Key': 'your-public-key' }
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data.result.status)
  })

PHP

The example uses the cURL extension included in a standard PHP installation. PHP syntax requires a semicolon at the end of each statement, so the code below retains it.

<?php

$apiKey = getenv('CLEANCONTACT_KEY');
$email = 'someone@example.com';
$url = 'https://api.cleancontact.ru/validate?' . http_build_query(['email' => $email]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . $apiKey]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data['result']['status'];

Error handling is omitted from the examples for brevity. A production integration should check the HTTP status code and handle the 400, 401, and 429 responses documented in the API Reference article.