DV
DataVerifData Verification
ServicesDocumentationContact

API Documentation

Complete guide to integrate DataVerif API into your applications

Navigation
Getting Started
Validation Results
Verify Endpoint
Bulk Verify
Code Examples

Getting Started

Démarrage

🇬🇧 English

How to obtain an API Key

  1. Visit our website and create an account
  2. Purchase credits according to your needs
  3. Generate your API key from your account dashboard
  4. Check your remaining credits anytime on your account page
🇫🇷 Français

Comment obtenir une clé API

  1. Visitez notre site web et créez un compte
  2. Achetez des crédits selon vos besoins
  3. Générez votre clé API depuis le tableau de bord de votre compte
  4. Vérifiez vos crédits restants à tout moment sur votre page de compte
🇬🇧 English

Authentication Priority

The API accepts authentication through multiple methods with the following priority order:

  1. Authorization header (Recommended): Authorization: Bearer YOUR_API_KEY
  2. X-API-Key header: X-API-Key: YOUR_API_KEY
  3. Request body field: api_key parameter (fallback only)
🇫🇷 Français

Priorité d'authentification

L'API accepte l'authentification via plusieurs méthodes avec l'ordre de priorité suivant :

  1. En-tête Authorization (Recommandé) : Authorization: Bearer VOTRE_CLE_API
  2. En-tête X-API-Key : X-API-Key: VOTRE_CLE_API
  3. Champ dans le corps : paramètre api_key (solution de secours uniquement)

Validation Result Messages

Messages de Résultats de Validation

All validation responses include a verdict field with a clear, user-friendly message and optional details.message for more context.

Toutes les réponses de validation incluent un champ verdict avec un message clair et convivial, et un details.message optionnel pour plus de contexte.

📧 Email Address Verdicts

Verdict MessageCondition
Valid emailEmail is valid and passes all checks
Valid email (generic account)Valid email but it's a generic account (admin, support, contact)
Invalid email formatEmail doesn't match the standard format (e.g., name@domain.com)
Disposable email detectedEmail domain is identified as a temporary/disposable email service
Email domain not foundThe email domain doesn't have a mail server configured
Email domain is blacklistedThe mail server is on an anti-spam blacklist
Email rejected by serverThe mail server rejected this email address (SMTP check)

📱 Phone Number Verdicts

Verdict MessageCondition
Valid phone numberPhone number is valid with all information available
Valid phone number (warning: carrier not identified)Valid but carrier information couldn't be determined
Valid phone number (warning: line type not identified)Valid but line type (mobile/fixed) couldn't be determined
Invalid phone numberThe phone number structure doesn't match the expected format
Unsupported phone type: [TYPE]Phone type (VoIP, Toll free, etc.) is not accepted
Cannot parse phone numberThe number cannot be parsed - check format and country code prefix

📍 Physical Address Response Fields

FieldTypeDescription
verdictstringClear validation message for end users
codestringStatus code: OK, INVALID, MISSING_ADDRESS, etc.
confidencestringConfidence level: HIGH, MEDIUM, LOW
formatted_addressstringProperly formatted and validated address
details.messagestringDetailed explanation of the validation result
details.validation_granularitystringValidation level: PREMISE, STREET, RANGE, etc.
details.has_unconfirmed_componentsbooleanTrue if address has unconfirmed components
details.has_unexpected_componentsbooleanTrue if unnecessary information was provided (doesn't invalidate)
details.address_diffobjectDifferences (only if actual changes exist): {added: [], removed: []}

📍 Address Verdict Examples

Verdict MessageCondition
Valid addressAddress validated at PREMISE level
Valid address (some provided information was unnecessary...)Valid PREMISE but had unexpected components (e.g., region)
Address validated at street level only (street number not confirmed)Validated at STREET or RANGE level
Address found but some components need confirmationPREMISE level but has unconfirmed components
Address is incomplete or impreciseLower granularity or missing components
Address is missingNo address provided
Address validation service unavailableValidation service temporarily unavailable

📋 Complete Response Examples

/verify Endpoint

Endpoint de vérification unique

POST
/verify
20 req/min
🇬🇧 English

Description: Verify single phone/email/address with detailed validation and confidence level.

🇫🇷 Français

Description : Vérifiez un téléphone/email/adresse unique avec validation détaillée et niveau de confiance.

Request Parameters / Paramètres de requête

NameTypeRequiredDescription (EN)Description (FR)
numberstring
Optional
Phone number to verifyNuméro de téléphone à vérifier
emailstring
Optional
Email address to verifyAdresse email à vérifier
street_numberstring
Optional
Street numberNuméro de rue
street_namestring
Required
Street nameNom de rue
postal_codestring
Required
Postal codeCode postal
citystring
Required
CityVille
countrystring
Required
CountryPays
country_codestring
Required
ISO country code (e.g., FR)Code pays ISO (ex: FR)

Response Example / Exemple de réponse

✅ 200 OK
{
  "result": {
    "email_address": {
      "input": "contact@data-verif.fr",
      "valid": true,
      "complete_result": {
        "valid": true,
        "verdict": "Valid email (generic account)",
        "details": {
          "message": "Valid email but it's a generic account (e.g., admin, support, contact)"
        }
      }
    },
    "phone_number": {
      "input": "0644884434",
      "valid": true,
      "complete_result": {
        "valid": true,
        "number": "+33 6 44 88 44 34",
        "carrier": "La poste telecom",
        "line_type": "Mobile",
        "verdict": "Valid phone number",
        "warnings": []
      }
    },
    "physical_address": {
      "input": "29 Rue de Rivoli, 75004 Paris, Île-de-France, France",
      "valid": true,
      "complete_result": {
        "valid": true,
        "verdict": "Valid address (some provided information was unnecessary but doesn't affect validity)",
        "code": "OK",
        "confidence": "HIGH",
        "formatted_address": "29 Rue de Rivoli, 75004 Paris, France",
        "details": {
          "message": "Valid address (some provided information was unnecessary but doesn't affect validity)",
          "has_unconfirmed_components": false,
          "has_unexpected_components": true,
          "validation_granularity": "PREMISE"
        }
      }
    }
  },
  "status_code": 200
}

Error Responses / Réponses d'erreur

CodeMessageDescription (EN/FR)
401
Api key not recognizedInvalid API key / Clé API invalide
401
Not enough creditCredit exhausted / Crédit insuffisant
400
Invalid JSON bodyRequest body malformed / Body JSON invalide
429
Rate limit exceededToo many requests / Trop de requêtes

/bulk_verify Endpoint

Vérification en masse par CSV

POST
/bulk_verify
20 req/min
🇬🇧 English

Description: Verify multiple rows (CSV) of emails/phones/addresses. Each row is validated individually with detailed results.

🇫🇷 Français

Description : Vérifiez plusieurs lignes (CSV) d'emails/téléphones/adresses. Chaque ligne est validée individuellement avec des résultats détaillés.

CSV Example / Exemple CSV

📄 data.csv
Mail;Phone;Address
contact@example.com;0644884434;29 Rue de Rivoli, 75004 Paris
info@test.fr;0123456789;10 Avenue des Champs-Élysées, 75008 Paris

Request Parameters / Paramètres de requête

NameTypeRequiredDescription (EN/FR)
filefile
Required
CSV file / Fichier CSV
country_codestring
Required
ISO country code (e.g., FR) / Code pays ISO

Response Example / Exemple de réponse

✅ 200 OK
[
  {
    "row": 1,
    "input": {
      "Mail": "contact@data-verif.fr",
      "Phone": "0644884434",
      "Address": "29 Rue de Rivoli, 75004 Paris, Île-de-France, France"
    },
    "email_result": {
      "valid": true,
      "verdict": "Valid email (generic account)",
      "details": {
        "message": "Valid email but it's a generic account (e.g., admin, support, contact)"
      }
    },
    "phone_result": {
      "valid": true,
      "number": "+33 6 44 88 44 34",
      "line_type": "Mobile",
      "carrier": "La poste telecom",
      "verdict": "Valid phone number",
      "warnings": []
    },
    "address_result": {
      "valid": true,
      "verdict": "Valid address (some provided information was unnecessary but doesn't affect validity)",
      "code": "OK",
      "confidence": "HIGH",
      "formatted_address": "29 Rue de Rivoli, 75004 Paris, France",
      "details": {
        "message": "Valid address (some provided information was unnecessary but doesn't affect validity)",
        "has_unconfirmed_components": false,
        "has_unexpected_components": true,
        "validation_granularity": "PREMISE"
      }
    }
  },
  {
    "row": 2,
    "input": {"Mail": "", "Phone": "", "Address": ""},
    "email_result": {"valid": false, "error": "Missing"},
    "phone_result": {"valid": false, "error": "Missing"},
    "address_result": {"valid": false, "error": "Missing"}
  }
]

Code Examples

Exemples de code

Python - /verify

🐍 Python (requests)
import requests

url = "https://YOUR_API_URL/verify"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "number": "0644884434",
    "email": "contact@example.com",
    "street_number": "29",
    "street_name": "Rue de Rivoli",
    "postal_code": "75004",
    "city": "Paris",
    "country": "France",
    "country_code": "FR"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

JavaScript - /verify

🟨 JavaScript (fetch)
const url = "https://YOUR_API_URL/verify";
const headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
};
const data = {
    number: "0644884434",
    email: "contact@example.com",
    street_name: "Rue de Rivoli",
    postal_code: "75004",
    city: "Paris",
    country: "France",
    country_code: "FR"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

Python - /bulk_verify

🐍 Python (requests)
import requests

url = "https://YOUR_API_URL/bulk_verify"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("data.csv", "rb")}
data = {"country_code": "FR"}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())