API Lead Qualification

The Fuego API allows you to qualify leads in real-time directly from your application. This is ideal for qualifying leads at the point of collection, such as during user registration or form submission.

API Basics

• Base URL: https://app.fuegoverify.com/api/v1/
• Authentication: API token (required for all requests)
• Rate Limit: 10 requests per second
• Format: JSON

Authentication

Fuego uses API tokens for authentication. You must include your token with every request using one of these methods:

Method 1: Query Parameter

Add your token as a query parameter:

https://app.fuegoverify.com/api/v1/qualify?token=YOUR_API_TOKEN&email=example@domain.com

Method 2: Authorization Header

Send your token in the Authorization header (preferred for security):

Authorization: Bearer YOUR_API_TOKEN

Keep your API token secure - never expose it in client-side code or public repositories.

Getting Started

1. Log in to your Fuego account at app.fuegoverify.com
2. Navigate to “API Settings” in your account dashboard
3. Generate a new API token
4. Use this token in your API requests as shown above

Qualifying a Lead

Endpoint

GET https://app.fuegoverify.com/api/v1/qualify

Parameters

Example Request

# Using query parameter
curl -X GET "https://app.fuegoverify.com/api/v1/qualify?token=YOUR_API_TOKEN&email=lister@jmc.com"

# Using Authorization header (recommended)
curl -X GET "https://app.fuegoverify.com/api/v1/qualify?email=lister@jmc.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "email": "lister@jmc.com",
  "valid_format": true,
  "valid_mx": true,
  "free": false,
  "disposable": false,
  "did_you_mean": null,
  "domain": "jmc.com",
  "user": "lister",
  "success": true,
  "domain_insight": {
    "category": "organization",
    "name": "Jupiter Mining Corporation",
    "industry": "Mining",
    "country": "UK",
    "ticker": "JMC",
    "employees": 58000,
    "description": "Jupiter Mining Corporation is a large mining conglomerate that operates throughout the solar system, specializing in mineral extraction and deep space exploration."
  }
}

Response Fields

Integration Examples

JavaScript

async function qualifyLead(email, forceRefresh = false) {
  // Method 1: Using query parameters
  const params = new URLSearchParams({
    token: "YOUR_API_TOKEN",
    email: email
  });
  
  if (forceRefresh) {
    params.append("force", "true");
  }
  
  const response = await fetch(`https://app.fuegoverify.com/api/v1/qualify?${params.toString()}`);
  const data = await response.json();
  return data;
  
  // Method 2: Using Authorization header (recommended)
  /*
  const params = new URLSearchParams({
    email: email
  });
  
  if (forceRefresh) {
    params.append("force", "true");
  }
  
  const response = await fetch(
    `https://app.fuegoverify.com/api/v1/qualify?${params.toString()}`, 
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_TOKEN'
      }
    }
  );
  const data = await response.json();
  return data;
  */
}

Python

import requests

def qualify_lead(email, force_refresh=False):
    # Method 1: Using query parameters
    params = {
        "token": "YOUR_API_TOKEN", 
        "email": email
    }
    
    if force_refresh:
        params["force"] = "true"
        
    response = requests.get(
        "https://app.fuegoverify.com/api/v1/qualify",
        params=params
    )
    return response.json()
    
    # Method 2: Using Authorization header (recommended)
    """
    params = {
        "email": email
    }
    
    if force_refresh:
        params["force"] = "true"
        
    headers = {
        "Authorization": "Bearer YOUR_API_TOKEN"
    }
    
    response = requests.get(
        "https://app.fuegoverify.com/api/v1/qualify",
        headers=headers,
        params=params
    )
    return response.json()
    """

Ruby

require 'net/http'
require 'json'
require 'uri'

def qualify_lead(email, force_refresh = false)
  # Method 1: Using query parameters
  uri = URI("https://app.fuegoverify.com/api/v1/qualify")
  params = { token: "YOUR_API_TOKEN", email: email }
  params[:force] = "true" if force_refresh
  
  uri.query = URI.encode_www_form(params)
  
  response = Net::HTTP.get(uri)
  JSON.parse(response)
  
  # Method 2: Using Authorization header (recommended)
  =begin
  uri = URI("https://app.fuegoverify.com/api/v1/qualify")
  params = { email: email }
  params[:force] = "true" if force_refresh
  
  uri.query = URI.encode_www_form(params)
  
  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer YOUR_API_TOKEN"
  
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  response = http.request(request)
  
  JSON.parse(response.body)
  =end
end

Best Practices

• Store your API token securely and never expose it in client-side code
• Implement proper error handling in your integration
• Utilize our built-in caching system - we automatically cache results for 30 days
• Use the force=true parameter only when you need a fresh qualification
• Use webhook notifications for long-running batch qualifications
• Implement rate limiting in your application to stay within API limits

Error Handling

The API will return HTTP status codes to indicate success or failure:

• 200: Success
• 400: Bad request (invalid parameters)
• 401: Unauthorized (invalid API token)
• 422: Unprocessable entity (invalid email format)
• 429: Too many requests (rate limit exceeded)
• 500: Server error

Error Response Format

When an error occurs, the API will return a JSON response with details:

{
  "error": "Invalid email format",
  "email": "invalid-email",
  "valid_format": false,
  "valid_mx": false
}

For technical errors not related to email validation, the response will include:

{
  "error": "Error message",
  "success": false
}

Handling Email Format Errors

When an email has an invalid format, our system will still attempt to provide a useful response with email validation fields to help you handle the case appropriately in your application.

For more information on interpreting qualification results, see our Understanding Results guide.