Skip to main content
POST
Infer Record Country

Quick Answer

How do I determine someone’s country from their contact information? Use this endpoint to infer country location by analyzing email domains and phone number country codes.Common questions this endpoint answers:
  • How do I find out what country someone is from?
  • How can I detect international contacts?
  • How do I identify non-US leads?
  • How can I route leads based on country?
  • How do I check if a contact is international?
  • How can I filter contacts by location?
What you need: Email addresses and/or phone numbers.What you get back: Inferred country, international flag, and detailed metadata for each email/phone showing country codes and validation status.Common use cases:
  • International lead routing and assignment
  • Geographic segmentation for campaigns
  • Compliance filtering (e.g., GDPR vs US regulations)
  • Sales territory assignment
  • Multi-market customer analysis

Overview

The Infer Record Country endpoint analyzes email addresses and phone numbers to determine the likely country location of a person. This endpoint infers country information by:
  • Analyzing email domain top-level domains (TLDs) such as .co.uk, .fr, .de
  • Parsing phone number country codes and validating phone number formats

Request

Headers

string
required
Your API key for authentication
string
required
application/json

Request Body

object[]
required
An array of records containing contact information. Maximum 1000 records per request.

Request Example

Response

Response Structure

The endpoint returns an array of result objects, one for each input record. Results maintain the same order as the input records.

Result Object

string
Your identifier from the request
boolean | null
Whether the record appears to be international (non-US).
  • true: Non-US country detected
  • false: US country detected
  • null: No country could be determined from the provided information
string | null
The most likely country name based on the analysis. If multiple countries are detected, returns the first one from the inferred list. null if no country could be determined.
string[] | null
Array of unique country names inferred from the contact information. Combines results from both email TLDs and phone number country codes. null if no countries could be inferred.
array
Detailed metadata for each email address analyzed
array
Detailed metadata for each phone number analyzed
Email Metadata Object
string
The email address as provided in the request
boolean
Whether the email address passed basic validation (format check, sanitization)
boolean | null
Whether the email domain indicates a non-US location based on TLD analysis
  • true: Non-US TLD detected (e.g., .co.uk, .fr, .de)
  • false: US TLD detected or generic TLD with no country inference
  • null: Email is invalid or no country could be determined
string | null
Uppercase ISO country code extracted from the email TLD (e.g., “GB”, “FR”, “DE”). null if no country-specific TLD detected or email is invalid.
string | null
Full country name corresponding to the TLD (e.g., “United Kingdom”, “France”, “Germany”). null if no country-specific TLD detected or email is invalid.
Phone Metadata Object
string
The phone number as provided in the request
boolean
Whether the phone number passed validation and could be parsed successfully
boolean | null
Whether the phone number is international (non-US)
  • true: Non-US country code detected
  • false: US country code detected (+1)
  • null: Phone is invalid or country could not be determined
string | null
Phone number in E.164 format (e.g., “+442071234567”). null if the phone number is invalid.
string | null
Uppercase ISO country code (e.g., “GB”, “FR”, “US”). null if the phone number is invalid or country could not be determined.
string | null
Full country name (e.g., “United Kingdom”, “France”, “United States”). null if the phone number is invalid or country could not be determined.
Error responses include statusCode and body fields for backward compatibility with existing integrations. These are deprecated — prefer the HTTP status code and the top-level code / message / api_request_id fields directly. (The deprecated nested body still carries the legacy error_message.)

Error Responses

  • 400 - Bad Request: Invalid input format
  • 401 - Unauthorized: Invalid API key
  • 413 - Payload Too Large: More than 1000 records in request
  • 422 - Unprocessable Entity: Invalid data format
  • 429 - Too Many Requests: Rate limit exceeded
  • 500 - Internal Server Error

Notes

API Version Support

  • This endpoint only supports API version v2 (/v2/infer_record_country)
  • Maximum 1000 records per request

Country Inference Logic

Country inference is based on:
  • Email TLD analysis: Extracts country from top-level domains (e.g., .co.uk → United Kingdom, .fr → France, .de → Germany)
    • Generic TLDs like .com, .org, .net do not provide country information
    • Email addresses without country-specific TLDs will have null values for country fields
  • Phone number parsing: Uses international phone number validation library to:
    • Parse and validate phone numbers in various formats
    • Extract country codes
    • Standardize to E.164 format

Field Behavior

  • is_intl: Determined by checking if any non-US country was inferred
    • true: At least one non-US country detected
    • false: Only US detected
    • null: No country information could be extracted
  • most_likely_country: Returns the first country from the inferred_countries list
    • When multiple countries are detected from different emails/phones, the order depends on the order they appear in your input
  • inferred_countries: Contains unique country names from all emails and phones analyzed
    • Duplicates are removed
    • Returns null if empty (no countries inferred)

Validation

  • Invalid emails (failed format validation) are included in results with is_valid: false and null country fields
  • Invalid phone numbers are included in results with is_valid: false and null country fields
  • Duplicate emails and phones within a single record are automatically deduplicated before processing

Input Field Compatibility

  • Name fields (first_name, last_name, middle_name, full_name, name_suffix) are accepted for API compatibility with the resolve endpoint but are not used in country inference logic
  • The endpoint uses the same ResolveInput model as the resolve endpoint, allowing seamless integration