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
live-api-demo
Live

Try it with your phone number

Enter a phone number to see our validation in action

API Request
SHBash
"text">-blue-400 font">-medium">curl "text-yellow-400">-X POST https://app.1lookup.io/api/v1/v1/phone \
  "text-yellow-400">-H "Authorization: Bearer YOUR_API_KEY" \
  "text-yellow-400">-H "Content">-Type: application/json" \
  "text-yellow-400">-d '{"phone_number": "+1234567890"}"}

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
"text">-blue-400 font">-medium">curl "text-yellow-400">-X POST https://app.1lookup.io/api/v1/phone \
  "text-yellow-400">-H "Authorization: Bearer YOUR_API_KEY" \
  "text-yellow-400">-H "Content">-Type: application/json" \
  "text-yellow-400">-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

Code Examples

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

JS
JavaScript / Node.js

JSPhone Validation Client - validator.js
1400">"text-purple-400 font-medium">const axios = 400">"text-purple-400 font-medium">require(400">'axios');
2 
3400">"text-purple-400 font-medium">const api = axios.create({
4  baseURL: 400">'https:500 italic">//app.1lookup.io/api/v1',
5  headers: {
6    400">'Authorization': 400">'Bearer YOUR_API_KEY',
7    400">'Content-Type': 400">'application/json'
8  }
9});
10 
11500 italic">// Validate a phone number
12400">"text-purple-400 font-medium">async 400">"text-purple-400 font-medium">function validatePhone(phoneNumber) {
13  400">"text-purple-400 font-medium">try {
14    400">"text-purple-400 font-medium">const response = 400">"text-purple-400 font-medium">await api.post(400">'/phone', {
15      phone_number: phoneNumber
16    });
17    400">"text-purple-400 font-medium">return response.data;
18  } 400">"text-purple-400 font-medium">catch (error) {
19    console.error(400">'Error:', error.response?.data || error.message);
20    400">"text-purple-400 font-medium">throw error;
21  }
22}
23 
24500 italic">// Example usage
25validatePhone(400">'+1234567890')
26  .then(result => console.log(400">'Valid:', result))
27  .400">"text-purple-400 font-medium">catch(error => console.error(400">'Invalid:', error));

PY
Python

PY1lookup API Client - onelookup.py
1400">"text-purple-400 font-medium">import requests
2400">"text-purple-400 font-medium">import json
3 
4400">"text-purple-400 font-medium">class OneLookupAPI:
5    400">"text-purple-400 font-medium">def __init__(400">"text-purple-400 font-medium">self, api_key):
6        400">"text-purple-400 font-medium">self.api_key = api_key
7        400">"text-purple-400 font-medium">self.base_url = 400">'https://app.1lookup.io/api/v1'
8        400">"text-purple-400 font-medium">self.headers = {
9            400">'Authorization': f400">'Bearer {api_key}',
10            400">'Content-Type': 400">'application/json'
11        }
12    
13    400">"text-purple-400 font-medium">def validate_phone(400">"text-purple-400 font-medium">self, phone_number):
14        400">""400">"Validate a phone number"400">""
15        response = requests.post(
16            f400">'{400 font-medium">self.base_url}/phone',
17            json={400">'phone_number': phone_number},
18            headers=400">"text-purple-400 font-medium">self.headers
19        )
20        response.raise_for_status()
21        400">"text-purple-400 font-medium">return response.json()
22    
23    400">"text-purple-400 font-medium">def validate_email(400">"text-purple-400 font-medium">self, email):
24        400">""400">"Validate an email address"400">""
25        response = requests.post(
26            f400">'{400 font-medium">self.base_url}/email',
27            json={400">'email': email},
28            headers=400">"text-purple-400 font-medium">self.headers
29        )
30        response.raise_for_status()
31        400">"text-purple-400 font-medium">return response.json()
32 
33500 italic"># Example usage
34api = OneLookupAPI(400">'your_api_key_here')
35result = api.validate_phone(400">'+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
"text">-blue-400 font">-medium">echo "Testing phone validation..."
"text">-blue-400 font">-medium">curl "text-yellow-400">-s "text-yellow-400">-X POST "$BASE_URL/phone" \
  "text-yellow-400">-H "Authorization: Bearer $API_KEY" \
  "text-yellow-400">-H "Content">-Type: application/json" \
  "text-yellow-400">-d '{"phone_number": "+1234567890"}' | "text">-blue-400 font">-medium">jq
 
# Test email validation  
"text">-blue-400 font">-medium">echo "Testing email validation..."
"text">-blue-400 font">-medium">curl "text-yellow-400">-s "text-yellow-400">-X POST "$BASE_URL/email" \
  "text-yellow-400">-H "Authorization: Bearer $API_KEY" \
  "text-yellow-400">-H "Content">-Type: application/json" \
  "text-yellow-400">-d '{"email": "test@example.com"}' | "text">-blue-400 font">-medium">jq

Pro Tip

Want to see more examples? Check out our integration guides 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
400">"text-purple-400 font-medium">async 400">"text-purple-400 font-medium">function validateWithRetry(phoneNumber, maxRetries = 3) {
  400">"text-purple-400 font-medium">for (400">"text-purple-400 font-medium">let i = 0; i < maxRetries; i++) {
    400">"text-purple-400 font-medium">try {
      400">"text-purple-400 font-medium">const response = 400">"text-purple-400 font-medium">await api.post(400">'/phone', {
        phone_number: phoneNumber
      });
      400">"text-purple-400 font-medium">return response.data;
    } 400">"text-purple-400 font-medium">catch (error) {
      400">"text-purple-400 font-medium">if (error.response?.status === 429) {
        500 italic">// Rate limited - wait and retry
        400">"text-purple-400 font-medium">const delay = Math.pow(2, i) * 1000;
        400">"text-purple-400 font-medium">await 400">"text-purple-400 font-medium">new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      400">"text-purple-400 font-medium">throw error; 500 italic">// Don't retry on other errors
    }
  }
  400">"text-purple-400 font-medium">throw 400">"text-purple-400 font-medium">new Error(400">'Max retries exceeded');
}