Multi-factor Validation API

The validation endpoint provides a comprehensive way to check multiple factors simultaneously in a single request. This unified approach allows you to validate any combination of email addresses, domains, and IP addresses together with optional user agent data. For a complete overview of our security features, see the Getting Started guide.

Authentication

Include your API key in the request header or as a query parameter:

x-api-key: your-api-key-here

or

https://veille.io/api/v1/validate?x_api_key=your-api-key-here

Endpoint

POST https://veille.io/api/v1/validate

Request format

The validation endpoint accepts a JSON payload that can include any combination of the following fields:

{
  "email": "user@example.com",
  "domain": "example.com",
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

All fields are optional, but you must include at least one of email, domain, or ip for the validation to be meaningful. For individual validations, you can use our dedicated endpoints:

• Email Validation API
• IP Intelligence API

Key features

Response format

{
  "allowed": true,
  "email": "user@example.com",
  "domain": "example.com",
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

When all validation checks pass, the response will include the allowed field set to true along with all the input fields provided in the request.

If any validation check fails, the response will include the allowed field set to false and a reason field indicating which check failed:

{
  "allowed": false,
  "reason": "email_blocked",
  "email": "user@example.com",
  "domain": "example.com",
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

Response Fields

Possible rejection reasons

When a security rule is triggered, the response will also include information about which rules matched:

{
  "allowed": false,
  "reason": "rule_triggered",
  "matched_rules": [
    {
      "rule_id": "vpn_block",
      "name": "Block VPN Traffic",
      "action": "block",
      "rule_order": 1
    }
  ],
  "ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

For cases where multiple rules are triggered, the response will list all matching rules:

{
  "allowed": false,
  "ip": "203.55.255.204",
  "user_agent": "Mozilla/5.0 (platform; rv:gecko-version) Gecko/gecko-trail Firefox/firefox-version",
  "reason": "rule_triggered",
  "matched_rules": [
    {
      "rule_id": "block_abuser",
      "name": "block_abuser",
      "action": "block",
      "rule_order": 1
    },
    {
      "rule_id": "block_ua",
      "name": "Block UA",
      "action": "block",
      "rule_order": 2
    }
  ]
}

Security rules integration

The validation endpoint integrates with your existing security rules for IP validation. These rules are the same ones configured through:

1. The Veille dashboard interface
2. The Security Rules API (see Security Rules documentation)

Security rules are evaluated for the IP address provided in the request, using any additional context from the user agent.

Validation process

The validation endpoint follows this process for each request:

1. Validates the format of all provided fields (email, domain, IP)
2. Checks if the email is blocked (if provided)
3. Checks if the domain is blocked (if provided)
4. Checks if the IP is directly blocked in your blocklist (if provided)
5. Evaluates the IP against all active security rules (if provided)
6. Returns a response indicating if all checks passed

The validation stops at the first failing check, with the response indicating which check failed.

Error handling

For details on error responses and status codes, please refer to the Status Codes & Error Responses documentation.

Code examples

cURL

curl -X POST \
  'https://veille.io/api/v1/validate' \
  -H 'x-api-key: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "domain": "example.com",
    "ip": "192.168.1.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'

JavaScript (Fetch)

fetch('https://veille.io/api/v1/validate', {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: "user@example.com",
    domain: "example.com",
    ip: "192.168.1.1",
    user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  })
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Python (Requests)

import requests
import json

headers = {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
}

data = {
    'email': 'user@example.com',
    'domain': 'example.com',
    'ip': '192.168.1.1',
    'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
}

response = requests.post(
    'https://veille.io/api/v1/validate',
    headers=headers,
    data=json.dumps(data)
)

print(response.json())

PHP

<?php
$ch = curl_init();

$data = [
    'email' => 'user@example.com',
    'domain' => 'example.com',
    'ip' => '192.168.1.1',
    'user_agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
];

curl_setopt($ch, CURLOPT_URL, 'https://veille.io/api/v1/validate');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: your-api-key-here',
    'Content-Type: application/json'
]);

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

echo $response;
?>

Practical use cases

Form validation

Use the validate endpoint to check user inputs before form submission:

async function validateUserInput(email, domain, ip, userAgent) {
  const response = await fetch('https://veille.io/api/v1/validate', {
    method: 'POST',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email,
      domain,
      ip,
      user_agent: userAgent
    })
  });
  
  const result = await response.json();
  
  if (!result.allowed) {
    showValidationError(result.reason);
    return false;
  }
  
  return true;
}

Security screening

Block traffic from suspicious sources by checking all available factors:

app.use(async (req, res, next) => {
  const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  const userAgent = req.headers['user-agent'];
  const email = req.body.email;
  const domain = req.body.domain || (email ? email.split('@')[1] : null);
  
  try {
    const response = await fetch('https://veille.io/api/v1/validate', {
      method: 'POST',
      headers: {
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        email,
        domain,
        ip: clientIp,
        user_agent: userAgent
      })
    });
    
    const result = await response.json();
    
    if (!result.allowed) {
      return res.status(403).json({ error: 'Access denied', reason: result.reason });
    }
    
    next();
  } catch (error) {
    console.error('Validation error:', error);
    next();
  }
});

User registration

Enhance sign-up security by validating multiple factors:

async function processRegistration(userData) {
  // Check email, domain, and IP before creating user account
  const validationResponse = await fetch('https://veille.io/api/v1/validate', {
    method: 'POST',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: userData.email,
      domain: userData.email.split('@')[1],
      ip: userData.ip,
      user_agent: userData.userAgent
    })
  });
  
  const validationResult = await validationResponse.json();
  
  if (!validationResult.allowed) {
    return {
      success: false,
      message: `Registration blocked: ${validationResult.reason}`
    };
  }
  
  // Proceed with registration
  // ...
}