Phone Intelligence API Integration Guide

Getting Started

VeriRoute Intel provides a RESTful API for phone intelligence. To get started:

1. Sign up for free (10 lookups/month included)
2. Get your API key from the dashboard
3. Make your first API call

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://api-service.verirouteintel.io/api/v1/

Basic Usage

Simple Lookup

curl "https://api-service.verirouteintel.io/api/v1/lrn?phone=+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

Full Lookup (All Data)

curl "https://api-service.verirouteintel.io/api/v1/lrn?phone=+15551234567&cnam=true&lrn=true&spam=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

{
  "success": true,
  "data": {
    "phone": "+15551234567",
    "cnam": {
      "name": "JOHN SMITH",
      "type": "person"
    },
    "lrn": {
      "lrn": "5551230000",
      "ocn": "6006",
      "carrier": "Verizon Wireless",
      "line_type": "wireless",
      "ported": true,
      "activation_date": "2023-06-15"
    },
    "spam": {
      "is_spam": false,
      "score": 5
    }
  }
}

Integration Patterns

Python

import requests

class VeriRouteClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api-service.verirouteintel.io/v1"

    def lookup(self, phone, cnam=False, lrn=True, spam=False):
        params = {
            "phone": phone,
            "cnam": str(cnam).lower(),
            "lrn": str(lrn).lower(),
            "spam": str(spam).lower(),
        }
        response = requests.get(
            f"{self.base_url}/lookup",
            params=params,
            headers={"Authorization": f"Bearer {self.api_key}"},
            timeout=10
        )
        response.raise_for_status()
        return response.json()

# Usage
client = VeriRouteClient("your_api_key")
result = client.lookup("+15551234567", cnam=True, lrn=True)

JavaScript/Node.js

const axios = require('axios');

class VeriRouteClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api-service.verirouteintel.io/v1';
  }

  async lookup(phone, options = {}) {
    const { cnam = false, lrn = true, spam = false } = options;

    const response = await axios.get(`${this.baseUrl}/lookup`, {
      params: { phone, cnam, lrn, spam },
      headers: { Authorization: `Bearer ${this.apiKey}` },
      timeout: 10000,
    });

    return response.data;
  }
}

// Usage
const client = new VeriRouteClient('your_api_key');
const result = await client.lookup('+15551234567', { cnam: true, lrn: true });

Error Handling

Handle errors gracefully to ensure your application remains responsive:

def safe_lookup(phone):
    try:
        result = client.lookup(phone, lrn=True)
        return result['data']

    except requests.exceptions.Timeout:
        # API timeout - proceed without data or retry
        logger.warning(f"Lookup timeout for {phone}")
        return None

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            # Rate limited - back off and retry
            time.sleep(1)
            return safe_lookup(phone)
        elif e.response.status_code == 402:
            # Payment required - out of credits
            logger.error("Out of API credits")
            return None
        else:
            raise

    except Exception as e:
        logger.error(f"Lookup error: {e}")
        return None

Caching Strategy

Phone data doesn't change frequently. Implement caching to reduce costs and latency:

import redis
import json

redis_client = redis.Redis()
CACHE_TTL = 86400 * 7  # 7 days

def cached_lookup(phone):
    # Check cache first
    cache_key = f"phone:{phone}"
    cached = redis_client.get(cache_key)
    if cached:
        return json.loads(cached)

    # Not in cache - do lookup
    result = client.lookup(phone, lrn=True)

    # Cache the result
    redis_client.setex(cache_key, CACHE_TTL, json.dumps(result))

    return result

Rate Limits

VeriRoute Intel enforces rate limits to ensure fair usage:

• Free tier — 10 lookups/month
• Paid plans — Based on your plan
• Burst limit — 100 requests/minute

If you hit rate limits, you'll receive a 429 response. Implement exponential backoff:

def lookup_with_backoff(phone, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.lookup(phone)
        except RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 1s, 2s, 4s
            else:
                raise

Best Practices

1. Request only what you need — Skip CNAM if you only need carrier data
2. Cache aggressively — Phone data rarely changes
3. Handle errors gracefully — Don't block user flows on API failures
4. Use timeouts — Set reasonable timeouts (5-10 seconds)
5. Monitor usage — Track API calls to stay within limits
6. Batch when possible — Use bulk uploads for large lists