1. Generate an API Token

First, create an API token in your API Settings.

2. Make Your First Request

Include your token in the Authorization header:

curl -X GET "https://warmer.ai/api/user" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Success Response:

{
  "success": true,
  "data": { ... }
}

Validation Error (422):

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "email": ["The email field is required."]
  }
}

Feature Access Error (403):

{
  "success": false,
  "error": "Feature not available",
  "details": {
    "feature": "email_verification",
    "message": "Email verification is only available on Pro and Enterprise plans",
    "required_plans": ["pro", "enterprise"],
    "upgrade_required": true
  }
}

Insufficient Credits (402):

{
  "success": false,
  "error": "Insufficient credits",
  "details": "You need at least 1 credit to process this lead"
}

Authentication Error (401):

{
  "success": false,
  "error": "Unauthenticated",
  "message": "Invalid or missing API token"
}

Common HTTP Status Codes:

Process a Lead

Process a single lead through enrichment and personalization pipeline.

Request Body:

{
  "email": "[email protected]",
  "linkedin": "https://linkedin.com/in/john-doe",
  "company_domain": "example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Example Corp",
  "email_verification_enabled": false
}

Response (without email verification):

{
  "success": true,
  "lead_id": 12345,
  "enriched_data": {
    "linkedin": {
      "has_data": true,
      "processed_data": "CEO at Example Corp...",
      "raw_data": { ... }
    },
    "company": {
      "has_data": true,
      "processed_data": "Example Corp helps...",
      "company_name": "Example Corp",
      "description": "...",
      "source": "linkedin"
    }
  },
  "personalizations": {
    "company_compliments": [
      "Love that Example Corp is solving...",
      "The fact that Example Corp made..."
    ],
    "personal_compliments": [
      "Saw you're on company #3 after Google...",
      "CEO to 50k followers journey..."
    ],
    "best_personalizations": {
      "company": "Love that Example Corp is solving...",
      "personal": "Saw you're on company #3 after Google..."
    }
  },
  "credits_used": 2,
  "processing_time": 3.245
}

Response (with email verification enabled):

{
  "success": true,
  "lead_id": 12346,
  "email_verification": {
    "status": "valid",
    "verified": true,
    "details": {
      "result": "valid",
      "score": 99,
      "reason": "accepted_email",
      "disposable": false,
      "role_account": false
    }
  },
  "enriched_data": {
    "linkedin": { ... },
    "company": { ... }
  },
  "personalizations": {
    "company_compliments": [ ... ],
    "personal_compliments": [ ... ],
    "best_personalizations": { ... }
  },
  "credits_used": 2,
  "processing_time": 4.123
}

Get Lead Status

Retrieve the status and results of a processed lead.

Create Campaign

Request Body:

{
  "name": "Q4 Outreach Campaign",
  "leads": [
    {
      "email": "[email protected]",
      "linkedin": "https://linkedin.com/in/john-doe",
      "company_domain": "example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Example Corp"
    },
    {
      "email": "[email protected]",
      "linkedin": "https://linkedin.com/in/jane-smith",
      "company_domain": "techcorp.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "company_name": "TechCorp"
    }
  ],
  "email_verification_enabled": true
}

Response:

{
  "success": true,
  "campaign": {
    "id": 456,
    "name": "Q4 Outreach Campaign",
    "total_leads": 2,
    "status": "processing",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Campaign created successfully. Leads are being processed in the background."
}

List Campaigns

Get Campaign Details

Retrieve detailed information about a campaign, including lead processing status and email verification results.

Response (with email verification):

{
  "success": true,
  "campaign": {
    "id": 456,
    "name": "Q4 Outreach Campaign",
    "status": "processing",
    "progress_percentage": 50,
    "total_leads": 2,
    "processing_stats": {
      "total_leads": 2,
      "pending": 0,
      "email_verifying": 0,
      "email_verified": 1,
      "email_invalid": 1,
      "email_risky": 0,
      "processing": 0,
      "personalizing": 0,
      "completed": 1,
      "failed": 0,
      "insufficient_credits": 0
    },
    "leads": [
      {
        "id": 1001,
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Doe",
        "company_name": "Example Corp",
        "status": "completed",
        "email_verification": {
          "status": "valid",
          "verified": true,
          "details": {
            "result": "valid",
            "score": 99,
            "reason": "accepted_email"
          }
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:35:00Z"
      },
      {
        "id": 1002,
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Smith",
        "company_name": "TechCorp",
        "status": "failed",
        "email_verification": {
          "status": "invalid",
          "verified": false,
          "details": {
            "result": "invalid",
            "score": 0,
            "reason": "invalid_domain"
          }
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:32:00Z"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z"
  }
}

Get Campaign Statistics

Zapier Integration

Use the Webhooks by Zapier app to send data to Warmer AI's API:

• Trigger: When a new lead is added to your CRM
• Action: POST to https://warmer.ai/api/leads/process
• Include your API token in headers
• Map lead data to the request body

Make.com Integration

Use the HTTP module to call Warmer AI's API:

• Module: HTTP > Make a request
• Method: POST
• URL: https://warmer.ai/api/leads/process
• Headers: Authorization: Bearer YOUR_TOKEN

Clay Integration

Use Clay's HTTP API enrichment to call Warmer AI:

• Add HTTP API column
• Configure POST request to https://warmer.ai/api/leads/process
• Set Authorization header with your token
• Map prospect data to API fields
• Extract personalizations from response

Python Example

import requests

# Configuration
API_TOKEN = "your_api_token_here"
BASE_URL = "https://warmer.ai/api"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Process a single lead with email verification (Pro/Enterprise only)
def process_lead_with_verification(email, linkedin=None, company_domain=None, first_name=None, last_name=None):
    lead_data = {
        "email": email,
        "linkedin": linkedin,
        "company_domain": company_domain,
        "first_name": first_name,
        "last_name": last_name,
        "email_verification_enabled": True  # Requires Pro/Enterprise plan
    }

    response = requests.post(
        f"{BASE_URL}/leads/process",
        json=lead_data,
        headers=headers
    )
    
    if response.status_code == 200:
        data = response.json()
        if data["success"]:
            # Check email verification result
            if "email_verification" in data:
                verification = data["email_verification"]
                print(f"Email verification: {verification['status']} (verified: {verification['verified']})")
                
                # Only proceed if email is valid or risky
                if verification["verified"] or verification["status"] == "risky":
                    personalizations = data["personalizations"]
                    print("Personal compliments:", personalizations["personal_compliments"])
                    print("Company compliments:", personalizations["company_compliments"])
                else:
                    print(f"Email {email} is invalid - no personalizations generated")
            
            print(f"Credits used: {data['credits_used']}")
            return data
        else:
            print("Error:", data["error"])
            if "details" in data and data["details"].get("upgrade_required"):
                print("Upgrade to Pro/Enterprise required for email verification")
    elif response.status_code == 403:
        data = response.json()
        if data.get("details", {}).get("feature") == "email_verification":
            print("Email verification requires Pro/Enterprise plan")
        else:
            print("Access denied:", data.get("error"))
    else:
        print(f"HTTP Error: {response.status_code}")
        print(response.text)
    
    return None

# Create a campaign with email verification
def create_campaign_with_verification(name, leads):
    campaign_data = {
        "name": name,
        "leads": leads,
        "email_verification_enabled": True
    }

    response = requests.post(
        f"{BASE_URL}/campaigns",
        json=campaign_data,
        headers=headers
    )
    
    if response.status_code == 201:
        data = response.json()
        if data["success"]:
            campaign = data["campaign"]
            print(f"Campaign created: {campaign['name']} (ID: {campaign['id']})")
            print(f"Processing {campaign['total_leads']} leads...")
            return campaign["id"]
    elif response.status_code == 403:
        print("Email verification requires Pro/Enterprise plan")
    else:
        print(f"Failed to create campaign: {response.status_code}")
        print(response.text)
    
    return None

# Example usage
if __name__ == "__main__":
    # Process single lead
    result = process_lead_with_verification(
        email="[email protected]",
        linkedin="https://linkedin.com/in/john-doe",
        company_domain="example.com",
        first_name="John",
        last_name="Doe"
    )
    
    # Create campaign
    leads = [
        {
            "email": "[email protected]",
            "first_name": "John", 
            "last_name": "Doe",
            "linkedin": "https://linkedin.com/in/john-doe"
        },
        {
            "email": "[email protected]",
            "first_name": "Jane",
            "last_name": "Smith",
            "company_domain": "techcorp.com"
        }
    ]
    
    campaign_id = create_campaign_with_verification("Python API Test Campaign", leads)