Introduction

The Number Intelligence Service API provides detailed information about phone numbers, including carrier information, spam status, caller ID name (CNAME), and enhanced location routing number (LRN) data.

Authentication

All API requests require authentication using an API key. You can generate an API key from your dashboard after signing up for an account.

Include your API key in the request header:

X-API-Key: your_api_key_here

Endpoints

{
  "phone_number": "15551234567",
  "include_spam_check": true,
  "include_cname": true,
  "include_enhanced_lrn": false
}

{
  "phone_number": "15551234567",
  "lookups_performed": {
    "basic_info": {
      "voice_provider": "Example Carrier",
      "messaging_provider": "Example Messaging",
      "lrn": "5551234000"
    },
    "spam_status": {
      "is_spam": false,
      "spam_score": 0.2,
      "spam_categories": []
    },
    "caller_id": {
      "name": "JOHN SMITH",
      "type": "CONSUMER"
    }
  },
  "source": "provider",
  "timestamp": "2023-06-15T14:22:31Z"
}

Response Fields

Error Responses

The API returns standard HTTP status codes to indicate success or failure:

Example Error Response

{
  "error": "Missing phone_number"
}

Code Examples

Python

import requests
import json

url = "https://api.numberintelligence.com/api/v1/lookup"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here"
}
data = {
    "phone_number": "15551234567",
    "include_spam_check": True,
    "include_cname": True
}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    result = response.json()
    print(f"Voice Provider: {result['lookups_performed']['basic_info']['voice_provider']}")
    if 'spam_status' in result['lookups_performed']:
        print(f"Spam Score: {result['lookups_performed']['spam_status']['spam_score']}")
    if 'caller_id' in result['lookups_performed']:
        print(f"Caller Name: {result['lookups_performed']['caller_id']['name']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript

fetch('https://api.numberintelligence.com/api/v1/lookup', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    phone_number: '15551234567',
    include_spam_check: true,
    include_cname: true
  })
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
  return response.json();
})
.then(data => {
  console.log('Voice Provider:', data.lookups_performed.basic_info.voice_provider);
  if (data.lookups_performed.spam_status) {
    console.log('Spam Score:', data.lookups_performed.spam_status.spam_score);
  }
  if (data.lookups_performed.caller_id) {
    console.log('Caller Name:', data.lookups_performed.caller_id.name);
  }
})
.catch(error => {
  console.error('Error:', error);
});

Best Practices

• Cache Results: Phone number information doesn't change frequently. Consider caching results to reduce API calls.
• Error Handling: Implement proper error handling to manage API failures gracefully.
• Rate Limiting: Be aware of rate limits and implement backoff strategies for high-volume requests.
• Secure Your API Key: Never expose your API key in client-side code. Make API calls from your server.

Support

If you need assistance with the API, please contact our support team at support@numberintelligence.com.