1lookup logo1lookup
Sign InGet Started
Enterprise-Grade API

API Documentation

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

99.97%
Accuracy Rate
< 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:

1
Create an API key from your dashboard
2
Include the API key in your request headers
3
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 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();
      
      // 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');
}