🔐 Authentication
All API requests require authentication using your personal API key. Include your API key in the request body for POST requests or as a query parameter for GET requests.
API Key Format
ess_[32-character-random-string]
Authentication Methods
Method 1: Request Body (Recommended for POST)
{
"api_key": "your-api-key-here",
"niche": "your niche or description of your target audience"
}
Method 2: Query Parameter (for GET requests)
GET /api/ess/balance?api_key=your-api-key-here
Method 3: Header (Alternative)
X-API-Key: your-api-key-here
⚠️ Security Note: Keep your API key secure and never share it publicly. Regenerate your key immediately if compromised.
🔧 Code Examples
Here are complete examples in different programming languages:
JavaScript (Node.js)
const axios = require('axios');class EmailScraperAPI {
constructor(apiKey, baseUrl = 'https://efficientpim.com/api/ess') {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
}async submitJob(niche, targetCount) {
try {
const response = await axios.post(`${this.baseUrl}/submit`, {
api_key: this.apiKey,
niche: niche,
target_count: targetCount
});
return response.data;
} catch (error) {
throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
}
}async checkStatus(jobId) {
try {
const response = await axios.get(`${this.baseUrl}/status/${jobId}`, {
params: { api_key: this.apiKey }
});
return response.data;
} catch (error) {
throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
}
}async getResults(jobId, format = 'json') {
try {
const response = await axios.get(`${this.baseUrl}/results/${jobId}`, {
params: { api_key: this.apiKey, format: format }
});
return response.data;
} catch (error) {
throw new Error(`API Error: ${error.response?.data?.message || error.message}`);
}
}
}// Usage example
async function main() {
const api = new EmailScraperAPI('ess_your_api_key_here');
try {
// Submit job
const job = await api.submitJob('digital marketing agencies', 100);
console.log('Job submitted:', job.job_id);
// Monitor progress
let status;
do {
await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
status = await api.checkStatus(job.job_id);
console.log(`Progress: ${status.progress_percentage}%`);
} while (status.status === 'processing');
// Get results
if (status.status === 'completed') {
const results = await api.getResults(job.job_id);
console.log(`Found ${results.total_count} emails`);
}
} catch (error) {
console.error('Error:', error.message);
}
}main();
Python
import requests
import time
import jsonclass EmailScraperAPI:
def __init__(self, api_key, base_url='https://efficientpim.com/api/ess'):
self.api_key = api_key
self.base_url = base_url
def submit_job(self, niche, target_count):
"""Submit a new scraping job"""
url = f"{self.base_url}/submit"
data = {
'api_key': self.api_key,
'niche': niche,
'target_count': target_count
}
response = requests.post(url, json=data)
response.raise_for_status()
return response.json()
def check_status(self, job_id):
"""Check job status"""
url = f"{self.base_url}/status/{job_id}"
params = {'api_key': self.api_key}
response = requests.get(url, params=params)
response.raise_for_status()
return response.json()
def get_results(self, job_id, format='json'):
"""Get job results"""
url = f"{self.base_url}/results/{job_id}"
params = {'api_key': self.api_key, 'format': format}
response = requests.get(url, params=params)
response.raise_for_status()
if format == 'csv':
return response.text
return response.json()
def get_balance(self):
"""Get credit balance"""
url = f"{self.base_url}/balance"
params = {'api_key': self.api_key}
response = requests.get(url, params=params)
response.raise_for_status()
return response.json()# Usage example
def main():
api = EmailScraperAPI('ess_your_api_key_here')
try:
# Check balance
balance = api.get_balance()
print(f"Credits available: {balance['credits_available']}")
# Submit job
job = api.submit_job('digital marketing agencies in NYC', 150)
print(f"Job submitted: {job['job_id']}")
# Monitor progress
while True:
status = api.check_status(job['job_id'])
print(f"Status: {status['status']} - Progress: {status['progress_percentage']}%")
if status['status'] in ['completed', 'failed']:
break
time.sleep(10) # Wait 10 seconds
# Get results if completed
if status['status'] == 'completed':
results = api.get_results(job['job_id'])
print(f"Found {results['total_count']} emails")
# Save as CSV
csv_data = api.get_results(job['job_id'], format='csv')
with open(f"emails_{job['job_id']}.csv", 'w') as f:
f.write(csv_data)
print("Results saved to CSV file")
except requests.RequestException as e:
print(f"API Error: {e}")if __name__ == "__main__":
main()
PHP
apiKey = $apiKey;
$this->baseUrl = $baseUrl;
}
public function submitJob($niche, $targetCount) {
$url = $this->baseUrl . '/submit';
$data = [
'api_key' => $this->apiKey,
'niche' => $niche,
'target_count' => $targetCount
];
return $this->makeRequest('POST', $url, $data);
}
public function checkStatus($jobId) {
$url = $this->baseUrl . '/status/' . $jobId;
$params = ['api_key' => $this->apiKey];
return $this->makeRequest('GET', $url . '?' . http_build_query($params));
}
public function getResults($jobId, $format = 'json') {
$url = $this->baseUrl . '/results/' . $jobId;
$params = ['api_key' => $this->apiKey, 'format' => $format];
return $this->makeRequest('GET', $url . '?' . http_build_query($params));
}
private function makeRequest($method, $url, $data = null) {
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
]);
if ($data && $method === 'POST') {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
}
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode >= 400) {
throw new Exception("API Error: HTTP $httpCode - $response");
}
return json_decode($response, true);
}
}// Usage example
try {
$api = new EmailScraperAPI('ess_your_api_key_here');
// Submit job
$job = $api->submitJob('digital marketing agencies', 100);
echo "Job submitted: " . $job['job_id'] . "\n";
// Monitor progress
do {
sleep(5); // Wait 5 seconds
$status = $api->checkStatus($job['job_id']);
echo "Progress: " . $status['progress_percentage'] . "%\n";
} while ($status['status'] === 'processing');
// Get results
if ($status['status'] === 'completed') {
$results = $api->getResults($job['job_id']);
echo "Found " . $results['total_count'] . " emails\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>