Enterprise-Grade API

API Documentation

Everything you need to integrate 1Lookup's data validation platform. Simple REST API, sub-300ms response times, enterprise-grade accuracy.

Enterprise

Accuracy Grade

< 300ms

Response Time

10M+

Monthly Validations

200+

Countries

⚠️ Deprecation Notice

The fraud_score field is deprecated and will be removed on November 23, 2025.

Please update your integration to use risk_level (LOW/MEDIUM/HIGH/CRITICAL) and confidence_level instead. These fields provide more actionable insights for your validation workflows.

Getting Started

Quick Start

The 1lookup API provides programmatic access to all our validation services. Follow these steps to get started:

Create an API key from your dashboard

Include the API key in your request headers

Make your first API call

Base URL

https://app.1lookup.io/api/v1

Your First Request

SHBash

curl -X POST https://app.1lookup.io/api/v1/phone \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+1234567890"}'

Authentication

API Key Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token format.

Authorization: Bearer YOUR_API_KEY

Security Best Practices

Keep your API keys secure and don't share them publicly
Use environment variables for API keys
Rotate keys regularly for enhanced security

API Endpoints

The 1lookup API provides several endpoints for different validation services:

POST

/v1/phone

Phone Validation

Validate phone numbers and get carrier information

POST

/v1/email

Email Validation

Validate email addresses and check deliverability

POST

/v1/phone-spam

Spam Detection

Check if phone numbers are associated with spam

POST

/v1/ip

IP Lookup

Get geolocation and threat intelligence for IPs

Rate Limiting

Request Limits

Our API implements fair usage limits to ensure optimal performance for all users.

Rate Limit100 requests/minute

Credit LimitsBased on your subscription plan

Note: Rate limits are applied per organization and reset every minute.

Rate Limit Headers

Every API response includes headers to help you track your usage.

HTTPHTTP

HTTP/1.1 200 OK
X-Ratelimit-Limit: 100
X-Ratelimit-Remaining: 98
X-Ratelimit-Reset: 2025-08-14T09:33:00.000Z
Content-Type: application/json
Date: Thu, 14 Aug 2025 09:32:18 GMT

Tip: Monitor these headers to implement client-side rate limiting and avoid 429 errors.

Error Handling

Error Response Format

All errors follow a consistent JSON structure with helpful details for debugging.

JSONJSON

{
  "success": false,
  "error": {
    "message": "Invalid email format",
    "code": "INVALID_EMAIL",
    "type": "validation_error",
    "details": {
      "field": "email",
      "provided": "invalid-email"
    }
  }
}

Common HTTP Status Codes

400Bad Request

401Unauthorized

402Insufficient Credits

429Rate Limited

500Server Error

Best Practices for Error Handling

JSJavaScript

async function apiRequest(endpoint, data) {
  try {
    const response = await fetchWithDedupe(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
 
    if (!response.ok) {
      const error = await response.json();
      
      // Handle specific error types
      switch (response.status) {
        case 400:
          console.error('Invalid request:', error.error.message);
          break;
        case 401:
          console.error('Invalid API key');
          break;
        case 402:
          console.error('Insufficient credits:', error.error.message);
          break;
        case 429:
          console.error('Rate limited. Retry after:', response.headers.get('Retry-After'));
          // Also check rate limit info
          console.log('Limit:', response.headers.get('X-Ratelimit-Limit'));
          console.log('Remaining:', response.headers.get('X-Ratelimit-Remaining'));
          console.log('Reset:', response.headers.get('X-Ratelimit-Reset'));
          break;
        case 500:
          console.error('Server error. Please try again later');
          break;
        default:
          console.error('Unexpected error:', error.error.message);
      }
      
      throw new Error(error.error.message);
    }
 
    return await response.json();
  } catch (error) {
    console.error('Request failed:', error.message);
    throw error;
  }
}

Code Examples

Ready-to-use code examples in popular programming languages:

JS
JavaScript / Node.js

JSPhone Validation Client - validator.js

1const axios = require('axios');
2 
3const api = axios.create({
4  baseURL: 'https://app.1lookup.io/api/v1',
5  headers: {
6    'Authorization': 'Bearer YOUR_API_KEY',
7    'Content-Type': 'application/json'
8  }
9});
10 
11// Validate a phone number
12async function validatePhone(phoneNumber) {
13  try {
14    const response = await api.post('/phone', {
15      phone_number: phoneNumber
16    });
17    return response.data;
18  } catch (error) {
19    console.error('Error:', error.response?.data || error.message);
20    throw error;
21  }
22}
23 
24// Example usage
25validatePhone('+1234567890')
26  .then(result => console.log('Valid:', result))
27  .catch(error => console.error('Invalid:', error));

PY
Python

PY1lookup API Client - onelookup.py

1import requests
2import json
3 
4class OneLookupAPI:
5    def __init__(self, api_key):
6        self.api_key = api_key
7        self.base_url = 'https://app.1lookup.io/api/v1'
8        self.headers = {
9            'Authorization': f'Bearer {api_key}',
10            'Content-Type': 'application/json'
11        }
12    
13    def validate_phone(self, phone_number):
14        """Validate a phone number"""
15        response = requests.post(
16            f'{self.base_url}/phone',
17            json={'phone_number': phone_number},
18            headers=self.headers
19        )
20        response.raise_for_status()
21        return response.json()
22    
23    def validate_email(self, email):
24        """Validate an email address"""
25        response = requests.post(
26            f'{self.base_url}/email',
27            json={'email': email},
28            headers=self.headers
29        )
30        response.raise_for_status()
31        return response.json()
32 
33# Example usage
34api = OneLookupAPI('your_api_key_here')
35result = api.validate_phone('+1234567890')
36print(json.dumps(result, indent=2))

SH
cURL / Bash

SHAPI Test Script - test.sh

#!/bin/bash
 
API_KEY="your_api_key_here"
BASE_URL="https://app.1lookup.io/api/v1"
 
# Test phone validation
echo "Testing phone validation..."
curl -s -X POST "$BASE_URL/phone" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+1234567890"}' | jq
 
# Test email validation  
echo "Testing email validation..."
curl -s -X POST "$BASE_URL/email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "robby@voicedrop.ai"}' | jq

Pro Tip

Want to see more examples? Check out our integration library for platform-specific implementations including Zapier, Make, and n8n.

Best Practices

Security

Never expose API keys in client-side code
Use environment variables for API keys
Rotate keys regularly for enhanced security

Performance

Cache validation results to reduce API calls
Use batch processing for multiple validations
Implement exponential backoff for rate limits

Example: Robust Error Handling

JSJavaScript

async function validateWithRetry(phoneNumber, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await api.post('/phone', {
        phone_number: phoneNumber
      });
      return response.data;
    } catch (error) {
      if (error.response?.status === 429) {
        // Rate limited - wait and retry
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error; // Don't retry on other errors
    }
  }
  throw new Error('Max retries exceeded');
}

{ "success": false, "error": { "message": "Invalid email format", "code": "INVALID_EMAIL", "type": "validation_error", "details": { "field": "email", "provided": "invalid-email" } } }

async function apiRequest(endpoint, data) { try { const response = await fetchWithDedupe(endpoint, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(data) }); if (!response.ok) { const error = await response.json(); // Handle specific error types switch (response.status) { case 400: console.error('Invalid request:', error.error.message); break; case 401: console.error('Invalid API key'); break; case 402: console.error('Insufficient credits:', error.error.message); break; case 429: console.error('Rate limited. Retry after:', response.headers.get('Retry-After')); // Also check rate limit info console.log('Limit:', response.headers.get('X-Ratelimit-Limit')); console.log('Remaining:', response.headers.get('X-Ratelimit-Remaining')); console.log('Reset:', response.headers.get('X-Ratelimit-Reset')); break; case 500: console.error('Server error. Please try again later'); break; default: console.error('Unexpected error:', error.error.message); } throw new Error(error.error.message); } return await response.json(); } catch (error) { console.error('Request failed:', error.message); throw error; } }

1const axios = require('axios'); 2 3const api = axios.create({ 4 baseURL: 'https://app.1lookup.io/api/v1', 5 headers: { 6 'Authorization': 'Bearer YOUR_API_KEY', 7 'Content-Type': 'application/json' 8 } 9}); 10 11// Validate a phone number 12async function validatePhone(phoneNumber) { 13 try { 14 const response = await api.post('/phone', { 15 phone_number: phoneNumber 16 }); 17 return response.data; 18 } catch (error) { 19 console.error('Error:', error.response?.data || error.message); 20 throw error; 21 } 22} 23 24// Example usage 25validatePhone('+1234567890') 26 .then(result => console.log('Valid:', result)) 27 .catch(error => console.error('Invalid:', error));

1import requests 2import json 3 4class OneLookupAPI: 5 def __init__(self, api_key): 6 self.api_key = api_key 7 self.base_url = 'https://app.1lookup.io/api/v1' 8 self.headers = { 9 'Authorization': f'Bearer {api_key}', 10 'Content-Type': 'application/json' 11 } 12 13 def validate_phone(self, phone_number): 14 """Validate a phone number""" 15 response = requests.post( 16 f'{self.base_url}/phone', 17 json={'phone_number': phone_number}, 18 headers=self.headers 19 ) 20 response.raise_for_status() 21 return response.json() 22 23 def validate_email(self, email): 24 """Validate an email address""" 25 response = requests.post( 26 f'{self.base_url}/email', 27 json={'email': email}, 28 headers=self.headers 29 ) 30 response.raise_for_status() 31 return response.json() 32 33# Example usage 34api = OneLookupAPI('your_api_key_here') 35result = api.validate_phone('+1234567890') 36print(json.dumps(result, indent=2))

#!/bin/bash API_KEY="your_api_key_here" BASE_URL="https://app.1lookup.io/api/v1" # Test phone validation echo "Testing phone validation..." curl -s -X POST "$BASE_URL/phone" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone_number": "+1234567890"}' | jq # Test email validation echo "Testing email validation..." curl -s -X POST "$BASE_URL/email" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "robby@voicedrop.ai"}' | jq

async function validateWithRetry(phoneNumber, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await api.post('/phone', { phone_number: phoneNumber }); return response.data; } catch (error) { if (error.response?.status === 429) { // Rate limited - wait and retry const delay = Math.pow(2, i) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); continue; } throw error; // Don't retry on other errors } } throw new Error('Max retries exceeded'); }

{ "success": false, "error": { "message": "Invalid email format", "code": "INVALID_EMAIL", "type": "validation_error", "details": { "field": "email", "provided": "invalid-email" } } }

API Documentation

⚠️ Deprecation Notice

Getting Started

Quick Start

Base URL

Your First Request

Authentication

API Key Authentication

Security Best Practices

API Endpoints

Phone Validation

Email Validation

Spam Detection

IP Lookup

Rate Limiting

Request Limits

Rate Limit Headers

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices for Error Handling

Code Examples

JSJavaScript / Node.js

PYPython

SHcURL / Bash

Pro Tip

Best Practices

Security

Performance

Example: Robust Error Handling

API Documentation

⚠️ Deprecation Notice

Getting Started

Quick Start

Base URL

Your First Request

Authentication

API Key Authentication

Security Best Practices

API Endpoints

Phone Validation

Email Validation

Spam Detection

IP Lookup

Rate Limiting

Request Limits

Rate Limit Headers

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices for Error Handling

Code Examples

JSJavaScript / Node.js

PYPython

SHcURL / Bash

Pro Tip

Best Practices

Security

Performance

Example: Robust Error Handling

API Documentation

⚠️ Deprecation Notice

Getting Started

Quick Start

Base URL

Your First Request

Authentication

API Key Authentication

Security Best Practices

API Endpoints

Phone Validation

Email Validation

Spam Detection

IP Lookup

Rate Limiting

Request Limits

Rate Limit Headers

Error Handling

Error Response Format

Common HTTP Status Codes

JS
JavaScript / Node.js

PY
Python

SH
cURL / Bash

JS
JavaScript / Node.js

PY
Python

SH
cURL / Bash

JS
JavaScript / Node.js

PY
Python

SH
cURL / Bash