Phone Number Lookup API

API Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header with the Bearer scheme:

GET /api/phone-lookup?phone=+12345678900 HTTP/1.1
Host: www.sent.dm
Authorization: Bearer YOUR_API_KEY

Obtain your API key from your account administrator or the API dashboard. Keep your API key secure – never share it publicly or commit it to version control.

The Phone Number Lookup API retrieves comprehensive phone number intelligence in real-time. Get carrier identification, number portability status, and fraud detection data for any phone number worldwide. The REST API supports E.164 international phone number format and returns Location Routing Number (LRN), Service Provider ID (SPID), Operating Company Number (OCN), line type classification, and porting history. Use it to validate customer phone numbers, prevent fraud, optimize SMS delivery routes, and maintain accurate contact databases.

Quick Start: Phone Number Validation Example

Get started with a complete example:

curl -X GET "https://www.sent.dm/api/phone-lookup?phone=%2B12345678900" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Node.js example
const axios = require('axios');

async function lookupPhoneNumber(phoneNumber) {
  try {
    const response = await axios.get('https://www.sent.dm/api/phone-lookup', {
      params: { phone: phoneNumber },
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Lookup failed:', error.response.data);
  }
}

lookupPhoneNumber('+12345678900');

# Python example
import requests

def lookup_phone_number(phone_number):
    url = 'https://www.sent.dm/api/phone-lookup'
    headers = {'Authorization': 'Bearer YOUR_API_KEY'}
    params = {'phone': phone_number}

    response = requests.get(url, headers=headers, params=params)
    if response.status_code == 200:
        print(response.json())
    else:
        print(f"Error: {response.status_code} - {response.text}")

lookup_phone_number('+12345678900')

Overview: How Phone Lookup Works

The Phone Number Lookup API retrieves detailed information about phone numbers, including carrier details, portability status, and fraud detection. Use E.164 format for global compatibility.

Coverage: This API supports phone number lookups worldwide. Data availability and detail level vary by country and carrier. North American numbers (US, Canada) include comprehensive LRN and portability data through integration with the Number Portability Administration Center (NPAC). International number data depends on local carrier database availability.

E.164 Format Requirements: E.164 is the ITU-T (International Telecommunication Union) international standard for telephone numbering. Start numbers with a plus sign (+), followed by the country code (1–3 digits), and the subscriber number. Total length: 15 digits maximum (excluding the + sign). Example: +12345678900 (US number with country code 1).

Key Features

• Carrier Information: Identify the service provider, network type, mobile country code (MCC), and mobile network code (MNC). Use this data to optimize message routing and understand network characteristics.

• Fraud Detection: Detects high-risk indicators including VoIP numbers (non-fixed VoIP services like Google Voice are commonly associated with fraud), recent porting activity (frequent number porting may indicate suspicious behavior), and invalid or disconnected numbers. The fraud field returns risk indicators when suspicious patterns are detected. A null value indicates no fraud flags.

• Portability Status: Check if a number has been ported to a different carrier. Returns porting date, original and current service providers, and Location Routing Number (LRN) for proper call routing. Essential for TCPA compliance and accurate carrier billing.

Common Use Cases:

• SMS Delivery Optimization: Filter out landline numbers before sending SMS campaigns to improve deliverability
• Fraud Prevention & VoIP Detection: Identify non-fixed VoIP and high-risk numbers during user registration
• Contact Database Hygiene: Validate and enrich phone numbers with current carrier data
• TCPA Compliance: Verify wireless vs. wireline status for Telephone Consumer Protection Act compliance
• Cost Optimization: Route calls efficiently using LRN data and avoid expensive misrouted calls

API Rate Limits

• Multi-region: 15 requests per 60 seconds

Rate Limit Best Practices:

• Implement exponential backoff when receiving 429 responses
• Cache lookup results to avoid redundant queries (recommended cache TTL: 24–48 hours for stable data)
• Distribute bulk lookups over time rather than in bursts
• Monitor your rate limit headers in responses to track remaining quota
• For high-volume needs, contact support for rate limit increases

Retry Strategy: When a 429 error occurs, wait 60 seconds before retrying. For 5xx errors, implement exponential backoff starting with a 1-second delay, doubling after each failure, up to a maximum of 32 seconds.

API Base URL

https://www.sent.dm/api

API Endpoints

GET /phone-lookup - Validate and Lookup Phone Numbers

Summary

Perform a lookup for a phone number in E.164 format. Returns comprehensive data including carrier, portability, and fraud status.

Request Parameters

Required Headers:

Response

200 OK

A successful response includes detailed phone number information.

{
  "data": {
    "country_code": "US",
    "national_format": "(234) 567-8900",
    "phone_number": "+12345678900",
    "fraud": null,
    "carrier": {
      "mobile_country_code": "310",
      "mobile_network_code": "004",
      "name": "Verizon Wireless",
      "type": "mobile",
      "error_code": null,
      "normalized_carrier": "Verizon"
    },
    "caller_name": null,
    "nnid_override": null,
    "portability": {
      "lrn": "2345678900",
      "ported_status": "not_ported",
      "ported_date": null,
      "ocn": "6959",
      "line_type": "mobile",
      "spid": "6959",
      "spid_carrier_name": "CELLCO PARTNERSHIP DBA VERIZON",
      "spid_carrier_type": "wireless",
      "altspid": "",
      "altspid_carrier_name": "",
      "altspid_carrier_type": "",
      "city": "MAHOPAC",
      "state": "New York"
    },
    "valid_number": true,
    "record_type": "number_lookup"
  },
  "poweredBy": "Powered by Sent.dm - [Visit Sent.dm](https://www.sent.dm)"
}

Response Fields Explained

Top-Level Fields:

• country_code: Two-letter ISO 3166-1 alpha-2 country code (e.g., "US", "GB", "CA").
• national_format: Phone number formatted according to national conventions (e.g., "(234) 567-8900" for US).
• phone_number: The original phone number in E.164 format as queried.
• fraud: Fraud risk indicators. Returns null if no fraud flags detected. When populated, may include risk scores, VoIP detection flags, or other security indicators.
• caller_name: CNAM (Caller Name) lookup result displaying the registered name associated with the phone number. Returns null if CNAM data is unavailable or not subscribed. Useful for caller identification and trust scoring.
• nnid_override: Network Numbering ID override value used in specialized routing scenarios. Typically null for standard lookups.
• valid_number: Boolean indicating whether the phone number is valid according to E.164 format and numbering plan rules. true means the number is properly formatted and assigned; false indicates an invalid or unassigned number.
• record_type: Always returns "number_lookup" to identify the response type.

Portability Fields:

• lrn (Location Routing Number): A 10-digit number assigned to the telephone switch serving the number. Used for call routing in the North American Numbering Plan (NANP). When a number is ported, the LRN identifies the destination switch regardless of the original number's area code. Format: NPA-NXX-XXXX (e.g., "2345678900"). Source: NPAC
• ported_status: Indicates whether the number has been moved from its original carrier. Possible values:
  • "not_ported": Number remains with original carrier
  • "ported": Number has been ported to a different service provider
  • "" (empty string): Porting status unknown or unavailable
• ported_date: ISO 8601 timestamp of when the number was most recently ported (e.g., "2024-03-15T10:30:00Z"). Returns null if never ported or date unavailable.
• ocn (Operating Company Number): A 4-character code assigned by NECA (National Exchange Carrier Association) that uniquely identifies the telecommunications service provider. Used for billing and regulatory purposes. Source: NECA Company Codes
• line_type: Type of telephone line. Possible values based on Twilio Line Type Intelligence:
  • "mobile": Mobile/cellular number that can receive SMS
  • "landline": Fixed landline that typically cannot receive SMS
  • "fixedVoip": VoIP number tied to a physical location (e.g., Comcast, Vonage)
  • "nonFixedVoip": Virtual VoIP number not tied to physical device (e.g., Google Voice) – higher fraud risk
  • "tollFree": Toll-free number (800, 888, 877, etc.)
  • "premium": Premium-rate number with higher charges
  • "voicemail": Voicemail service number
  • "unknown": Valid number but line type cannot be determined
• spid (Service Provider ID): A 4-character alphanumeric identifier assigned by the Number Portability Administration Center (NPAC) to identify the current service provider in the number portability system. Often matches the OCN. Source: NPAC SPID Documentation
• spid_carrier_name: Full legal name of the service provider identified by the SPID.
• spid_carrier_type: Type of service provider. Common values: "wireless", "wireline", "voip", or empty string if unavailable.
• altspid (Alternative Service Provider ID): The 4-character identifier for a wholesale or reseller service provider associated with the number. Used when a number is served through a wholesale relationship (e.g., MVNO on a host carrier's network). Returns empty string if not applicable. Source: NPAC AltSPID Documentation
• altspid_carrier_name: Name of the alternative/wholesale service provider.
• altspid_carrier_type: Type of alternative service provider (e.g., "wireless", "voip"). Empty string if not applicable.
• city: City where the number's switch or rate center is located.
• state: State or province where the number's switch is located (full name, e.g., "New York", "California").

Carrier Fields:

• mobile_country_code (MCC): A 3-digit code identifying the country per ITU-T E.212 standard. Used in mobile networks as part of IMSI identification. Examples: "310" (USA), "234" (UK), "262" (Germany). Source: ITU-T E.212
• mobile_network_code (MNC): A 2–3 digit code identifying the mobile network operator within the country. Combined with MCC to uniquely identify a carrier globally.
• name: Commercial name of the carrier (e.g., "Verizon Wireless", "AT&T Mobility").
• type: Carrier/line type classification. Values align with line_type field: "mobile", "landline", "voip", "fixedVoip", "nonFixedVoip", "unknown".
• error_code: Error code if carrier lookup failed. Returns null on success. Non-null values indicate data retrieval issues for specific carrier fields.
• normalized_carrier: Simplified, standardized carrier name for easier matching and deduplication (e.g., "Verizon" instead of "CELLCO PARTNERSHIP DBA VERIZON WIRELESS"). May be empty string if normalization unavailable.

Field Null/Empty Handling: Fields return null or empty strings ("") when:

• Data is unavailable from upstream carrier databases
• The number is outside the service's coverage area
• The specific data element doesn't apply to the line type (e.g., MCC/MNC for landlines)
• Regional databases don't track that field (e.g., LRN only exists for NANP)

Error Responses

400 Bad Request

Returned when the phone number format is incorrect.

{
  "error": "Invalid phone number format. Must be in E.164 format."
}

Common causes: Missing + prefix, invalid country code, exceeds 15 digits, contains non-numeric characters after the +.

401 Unauthorized

Returned when authentication fails or API key is invalid.

{
  "error": "Invalid or missing API key."
}

Resolution: Verify your API key is correct and included in the Authorization: Bearer YOUR_API_KEY header.

403 Forbidden

Returned when the API key is valid but lacks permission for this operation.

{
  "error": "Access denied. Phone lookup feature not enabled for your account."
}

Resolution: Contact support to enable phone lookup permissions for your account.

429 Too Many Requests

Returned when the rate limit is exceeded.

{
  "error": "Rate limit exceeded. Please wait and try again."
}

Resolution: Implement exponential backoff. Wait 60 seconds before retrying.

500 Internal Server Error

Returned when there is an internal error processing the request.

{
  "error": "Failed to retrieve phone data."
}

Resolution: Retry with exponential backoff. If the issue persists, contact support with the timestamp and phone number queried.

Troubleshooting Common Scenarios

Partial Data Returned: Some fields may be null or empty if:

• The number is outside primary coverage regions (best coverage: US, Canada, major European countries)
• Carrier databases don't provide certain data points
• The number is newly assigned and not yet in all databases

Ported Numbers: When ported_status is "ported", use the spid and spid_carrier_name for current carrier, not the original NPA-NXX assignment. The lrn field is critical for proper call routing.

VoIP Detection for Fraud Prevention: Numbers with line_type: "nonFixedVoip" have higher fraud risk. Consider additional verification steps for these numbers during user registration.

TCPA Compliance: Use ported_status and line_type to determine if a number is wireless or wireline. The Telephone Consumer Protection Act requires prior express consent before calling/texting wireless numbers.

Data Freshness and Caching

Update Frequency: Carrier and portability data updates in near real-time, typically within 15 minutes of database changes. LRN and porting data syncs from NPAC occur every 15–30 minutes.

Recommended Caching: Cache lookup results for 24–48 hours to balance data freshness with API efficiency. Use shorter TTLs (4–6 hours) for fraud-sensitive applications.

Performance: Typical API response time is 200–500 ms for North American numbers, 500 ms–2 s for international numbers depending on upstream carrier database latency.

Best Practices

• Validate Before Lookup: Pre-validate E.164 format client-side to avoid unnecessary API calls and 400 errors
• Batch Processing: For bulk lookups, distribute requests over time to stay within rate limits
• Error Handling: Implement retry logic with exponential backoff for transient errors (429, 5xx)
• Security: Never expose API keys in client-side code; make lookups from backend services only
• Optimize Costs: Cache results appropriately and avoid duplicate lookups for the same number
• Fraud Workflows: For high-risk line types (nonFixedVoip), implement additional verification (SMS OTP, email confirmation)

Common Use Cases and Code Examples

How to Filter Landlines for SMS Campaigns

Filter out landlines before sending SMS to avoid failed deliveries:

const result = await lookupPhoneNumber('+12345678900');
if (result.data.portability.line_type === 'mobile') {
  sendSMS(result.data.phone_number, 'Your message here');
} else {
  console.log('Skipping landline number');
}

How to Detect VoIP Numbers for Fraud Prevention

Detect high-risk VoIP numbers:

result = lookup_phone_number('+12345678900')
if result['data']['portability']['line_type'] == 'nonFixedVoip':
    require_additional_verification(user)
elif result['data']['fraud'] is not None:
    flag_for_manual_review(user)

How to Verify Wireless Numbers for TCPA Compliance

Verify wireless vs. wireline status:

const result = await lookupPhoneNumber('+12345678900');
const isWireless = ['mobile', 'nonFixedVoip', 'fixedVoip'].includes(
  result.data.portability.line_type
);
if (isWireless && !hasExpressConsent(user)) {
  throw new Error('TCPA: Express consent required for wireless numbers');
}

For more information on the E.164 format, visit the official E.164 documentation.

Technical References

Standards and Specifications:

• ITU-T Recommendation E.164: The international public telecommunication numbering plan – https://www.itu.int/rec/T-REC-E.164/en
• ITU-T Recommendation E.123: Notation for national and international telephone numbers – https://www.itu.int/rec/T-REC-E.123/en
• ITU-T Recommendation E.212: International mobile subscriber identity (IMSI) and mobile country codes – https://www.itu.int/rec/T-REC-E.212

Number Portability and Carrier Identification:

• Number Portability Administration Center (NPAC): How LNP Works – https://numberportability.com/about/how-lnp-works
• NPAC General FAQs (SPID, LRN, OCN definitions) – https://numberportability.com/support/faq/general
• Location Routing Number (LRN) specification – https://en.wikipedia.org/wiki/Location_routing_number
• NECA Company Codes (OCN) Administration – https://www.neca.org/business-solutions/company-codes
• ATIS-0300251: Codes for Identification of Service Providers for Information Exchange (OCN standard)
• Twilio Line Type Intelligence Documentation – https://www.twilio.com/docs/lookup/v2-api/line-type-intelligence

Regulatory:

• FCC Telecommunications Act of 1996 (LNP regulatory framework) – https://www.fcc.gov/general/telecommunications-act-1996
• Telephone Consumer Protection Act (TCPA) compliance – https://www.fcc.gov/consumer-protection-bureau/telephone-consumer-protection-act