External API

Overview

The WarpLeads External API allows you to programmatically access lead search functionality and supporting data. All API endpoints require authentication using your API key, which you can find in your Account Settings.

In order to use WarpLeads API you must have:
1) Unlimited WarpLeads account
2) Paid WarpLeads API account

Authentication

All API requests must include your API key in the request headers:
ApiKey: YOUR_API_KEY_HERE

Rate Limits

To ensure fair usage and system stability, the following rate limits apply to all external API endpoints:

  • 300 requests per minute
  • 800 requests per hour
  • 4,000 requests per day

When you exceed a rate limit, you’ll receive a 429 Too Many Requests response with details about which limit was exceeded and when to retry.

Base URL

https://warpleads.com/api/external

Endpoints

1. Lead Search

Search for leads based on various criteria.

Endpoint: POST /api/external/LeadSearch/Search

Headers:

Content-Type: application/json

ApiKey: YOUR_API_KEY_HERE

Request Body:

{
  "Skip": 0,
  "Take": 50,
  "HasWorkEmail": true,
  "HasPersonalEmail": false,
  "HasPhone": false,
  "FullName": "John Doe",
  "JobTitles": ["Software Engineer", "Developer"],
  "Companies": [1234, 5678],
  "CompanyIndustries": [10, 25],
  "CompanySizes": [3, 4, 5],
  "Skills": [100, 200],
  "Technologies": [50, 75],
  "HaveBachelor": true,
  "HaveMaster": false,
  "HaveDoctorate": false,
  "HaveAssociate": false,
  "Locations": ["CityId:2", "StateId:5", "CountryId:1"],
  "Countries": [1, 2]
}

Parameters:

  • Skip (integer): Number of results to skip (for pagination)
  • Take (integer): Number of results to return (max 100)
  • HasWorkEmail (boolean): Filter for leads with work emails
  • HasPersonalEmail (boolean): Filter for leads with personal emails
  • HasPhone (boolean): Filter for leads with phone numbers
  • FullName (string): Search by full name
  • JobTitles (array): Filter by job titles
  • Companies (array): Filter by company names
  • CompanyIndustries (array): Filter by company industries
  • CompanySizes (array): Filter by company sizes (1-8, see Company Sizes endpoint)
  • Skills (array): Filter by skills
  • Technologies (array): Filter by technologies
  • HaveBachelor (boolean): Filter for leads with bachelor’s degree
  • HaveMaster (boolean): Filter for leads with master’s degree
  • HaveDoctorate (boolean): Filter for leads with doctorate degree
  • HaveAssociate (boolean): Filter for leads with associate’s degree
  • Locations (array of strings): Filter by location special IDs in format “CityId:X”, “StateId:X”, or “CountryId:X” (use Location Search endpoint to find these values)
  • Countries (array of integers): Filter by country IDs (use Countries endpoint to find IDs)

Example Response:

[
    {
      "Id": 12345,
      "FullName": "John Doe",
      "JobTitle": "Software Engineer",
      "LinkedInUrl": "https://linkedin.com/in/johndoe",
      "CompanyName": "Tech Corporation",
      "PersonLocation": "San Francisco, CA, United States",
      "CompanyIndustry": "Technology",
      "VisibleData": true,
      "WorkEmail": "john.doe@techcorp.com",
      "PersonalEmail": "john.doe@gmail.com",
      "Phone1": "+1-555-123-4567",
      "Phone2": "+1-555-987-6543",
      "HasEmailPhone": 3
    }
  ]

2. Job Title Search

Search for available job titles in the system.

Endpoint: GET /api/external/JobTitle/Search?jobTitle={searchTerm}

Example request:
GET /api/external/JobTitle/Search?jobTitle=engineer

Sample response:

[
  {
    "jobTitleId": 1,
    "jobTitle": "Software Engineer"
  },
  {
    "jobTitleId": 2,
    "jobTitle": "Data Engineer"
  }
]

3. Company Search

Search for companies and company-related data.

Search Companies

Endpoint: GET /api/external/Company/Search?companyName={searchTerm}

Example response:

[
  {
    "companyId": 1,
    "companyName": "Microsoft Corporation"
  },
  {
    "companyId": 2,
    "companyName": "Microsoft Azure"
  }
]

4. Search Industries

Endpoint: GET /api/external/Company/Industries?industryName={searchTerm}

[
  {
    "industryId": 1,
    "industryName": "Technology"
  },
  {
    "industryId": 2,
    "industryName": "Software Development"
  }
]

5. Get Company Sizes

Endpoint: GET /api/external/Company/Sizes

[
  {
    "SizeId": 1,
    "Size": "1-10"
  },
  {
    "SizeId": 2,
    "Size": "11-50"
  },
  {
    "SizeId": 3,
    "Size": "51-200"
  },
  {
    "SizeId": 4,
    "Size": "201-500"
  },
  {
    "SizeId": 5,
    "Size": "501-1000"
  },
  {
    "SizeId": 6,
    "Size": "1001-5000"
  },
  {
    "SizeId": 7,
    "Size": "5001-10000"
  },
  {
    "SizeId": 8,
    "Size": "10001+"
  }
]

6. Location Search

Search for locations and countries.

Search Locations

Endpoint: GET /api/external/Location/Search?cityStateCountry={searchTerm}

[
  {
    "specialId": "CityId:1",
    "locationName": "San Francisco, CA, United States"
  },
  {
    "specialId": "CityId:2",
    "locationName": "San Jose, CA, United States"
  },
  {
    "specialId": "StateId:5",
    "locationName": "State: California"
  },
  {
    "specialId": "CountryId:1",
    "locationName": "United States"
  }
]

Note: Use the specialId field (string) directly in the Lead Search Locations parameter. The format is already correct ("CityId:X", "StateId:X", or "CountryId:X").

7. Get Countries

Endpoint: GET /api/external/Location/Countries

[
  {
    "countryId": 1,
    "countryName": "United States"
  },
  {
    "countryId": 2,
    "countryName": "Canada"
  }
]

Note: Use the countryId field (integer) in the Lead Search Countries parameter.

8. Skills Search

Search for available skills in the system.

Endpoint: GET /api/external/Skills/Search?skillName={searchTerm}

[
  {
    "skillId": 1,
    "skillName": "JavaScript"
  },
  {
    "skillId": 2,
    "skillName": "Java"
  }
]

9. Technology Search

Search for available technologies in the system.

Endpoint: GET /api/external/Technology/Search?technologyName={searchTerm}

[
  {
    "technologyId": 1,
    "technologyName": "React"
  },
  {
    "technologyId": 2,
    "technologyName": "React Native"
  }
]

Error Responses401 Unauthorized

{
  "error": "Invalid API key"
}

429 Too Many RequestsRate limit exceeded: 300 requests per minuteResponse Headers:

  • X-RateLimit-Limit: The rate limit that was exceeded
  • X-RateLimit-Window: The time window (minute/hour/day)
  • Retry-After: Seconds to wait before retrying

500 Internal Server ErrorExample

curl -X POST "https://warpleads.com/api/external/LeadSearch/Search" \
  -H "ApiKey: YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "Take": 10,
    "HasWorkEmail": true,
    "JobTitles": ["Software Engineer"],
    "Companies": ["Microsoft"]
  }'