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.

Get API Key

Enterprise

Accuracy Grade

< 300ms

Response Time

10M+

Monthly Validations

200+

Countries

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:

Global parameter: All POST endpoints accept an optional bypass_cache (boolean) in the request body to skip the 7-day cache and force a fresh lookup.

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 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

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_INPUT",
    "type": "api_error"
  }
}

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 fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
 
    if (!response.ok) {
      const error = await response.json();
      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'); break;
        case 429: console.error('Rate limited'); break;
        case 500: console.error('Server error'); break;
      }
      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 
11async function validatePhone(phoneNumber) {
12  try {
13    const response = await api.post('/phone', {
14      phone_number: phoneNumber
15    });
16    return response.data;
17  } catch (error) {
18    console.error('Error:', error.response?.data || error.message);
19    throw error;
20  }
21}
22 
23validatePhone('+1234567890')
24  .then(result => console.log('Valid:', result))
25  .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        response = requests.post(
15            f'{self.base_url}/phone',
16            json={'phone_number': phone_number},
17            headers=self.headers
18        )
19        response.raise_for_status()
20        return response.json()
21 
22api = OneLookupAPI('your_api_key_here')
23result = api.validate_phone('+1234567890')
24print(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"
 
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
 
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) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

async function apiRequest(endpoint, data) { try { const response = await fetch(endpoint, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(data) }); if (!response.ok) { const error = await response.json(); 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'); break; case 429: console.error('Rate limited'); break; case 500: console.error('Server error'); break; } 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 11async function validatePhone(phoneNumber) { 12 try { 13 const response = await api.post('/phone', { 14 phone_number: phoneNumber 15 }); 16 return response.data; 17 } catch (error) { 18 console.error('Error:', error.response?.data || error.message); 19 throw error; 20 } 21} 22 23validatePhone('+1234567890') 24 .then(result => console.log('Valid:', result)) 25 .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 response = requests.post( 15 f'{self.base_url}/phone', 16 json={'phone_number': phone_number}, 17 headers=self.headers 18 ) 19 response.raise_for_status() 20 return response.json() 21 22api = OneLookupAPI('your_api_key_here') 23result = api.validate_phone('+1234567890') 24print(json.dumps(result, indent=2))

#!/bin/bash API_KEY="your_api_key_here" BASE_URL="https://app.1lookup.io/api/v1" 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 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) { const delay = Math.pow(2, i) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); continue; } throw error; } } throw new Error('Max retries exceeded'); }

API Documentation

Getting Started

Quick Start

Base URL

Your First Request

Authentication

API Key Authentication

Security Best Practices

API Endpoints

Phone Validation

Email Validation

Spam Detection

Phone Scrub

IP Lookup

Reverse IP Append

Website Scraper

Domain SEO Intelligence

Website Contacts Scraper

Phone Append

Email Append

Reverse Email Append

Reverse Phone Lookup

HLR Lookup

MNP Lookup

Number Type Lookup

Account Status

Rate Limiting

Request Limits

Rate Limit Headers

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices for Error Handling

Code Examples

JS JavaScript / Node.js

PY Python

SH cURL / Bash

Pro Tip

Best Practices

Security

Performance

Example: Robust Error Handling

API Documentation

Getting Started

Quick Start

Base URL

Your First Request

Authentication

API Key Authentication

Security Best Practices

API Endpoints

Phone Validation

Email Validation

Spam Detection

Phone Scrub

IP Lookup

Reverse IP Append

Website Scraper

Domain SEO Intelligence

Website Contacts Scraper

Phone Append

Email Append

Reverse Email Append

Reverse Phone Lookup

HLR Lookup

MNP Lookup

Number Type Lookup

Account Status

Rate Limiting

Request Limits

Rate Limit Headers

Error Handling

Error Response Format

Common HTTP Status Codes

Best Practices for Error Handling

Code Examples

JS JavaScript / Node.js

PY Python

SH cURL / Bash

Pro Tip