Infer Record Country
Validation Workflows
Infer Record Country
Infer country location from email addresses and phone numbers
POST
Infer Record Country
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 detectedfalse: US country detectednull: 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 inferencenull: 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 detectedfalse: 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 format401- Unauthorized: Invalid API key413- Payload Too Large: More than 1000 records in request422- Unprocessable Entity: Invalid data format429- Too Many Requests: Rate limit exceeded500- 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,.netdo not provide country information - Email addresses without country-specific TLDs will have
nullvalues for country fields
- Generic TLDs like
- 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 inferredtrue: At least one non-US country detectedfalse: Only US detectednull: No country information could be extracted
most_likely_country: Returns the first country from theinferred_countrieslist- 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
nullif empty (no countries inferred)
Validation
- Invalid emails (failed format validation) are included in results with
is_valid: falseandnullcountry fields - Invalid phone numbers are included in results with
is_valid: falseandnullcountry 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
ResolveInputmodel as the resolve endpoint, allowing seamless integration