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

x-api-key

string

required

Your API key for authentication

Content-Type

string

required

application/json

Request Body

records

object[]

required

An array of records containing contact information. Maximum 1000 records per request.

Show Record object properties

record_id

string

required

Your unique identifier for this record

emails

string[]

Array of email addresses to analyze. Emails are validated and analyzed for country-specific TLDs.

phones

string[]

Array of phone numbers to analyze. Supports various formats including E.164, international format with +, and local formats.

first_name

string

First name (optional, accepted but not used for country inference)

last_name

string

Last name (optional, accepted but not used for country inference)

middle_name

string

Middle name (optional, accepted but not used for country inference)

full_name

string

Full name (optional, accepted but not used for country inference)

name_suffix

string

Name suffix (optional, accepted but not used for country inference)

Note: At least one of emails or phones should be provided for meaningful country inference. Name fields are accepted for compatibility with other endpoints but are not used in the country inference logic.

Request Example

{
  "records": [
    {
      "record_id": "user_001",
      "emails": ["[email protected]", "[email protected]"],
      "phones": ["+44 20 7123 4567"]
    },
    {
      "record_id": "user_002",
      "first_name": "Marie",
      "last_name": "Dubois",
      "emails": ["[email protected]"],
      "phones": ["+33 1 23 45 67 89", "+33 6 12 34 56 78"]
    }
  ]
}

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

record_id

string

Your identifier from the request

is_intl

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

most_likely_country

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.

inferred_countries

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.

email_metadata

array

Detailed metadata for each email address analyzed

phone_metadata

array

Detailed metadata for each phone number analyzed

Email Metadata Object

string

The email address as provided in the request

is_valid

boolean

Whether the email address passed basic validation (format check, sanitization)

is_intl

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

country_code

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.

location

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

phone

string

The phone number as provided in the request

is_valid

boolean

Whether the phone number passed validation and could be parsed successfully

is_intl

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

standardized_phone

string | null

Phone number in E.164 format (e.g., “+442071234567”). null if the phone number is invalid.

country_code

string | null

Uppercase ISO country code (e.g., “GB”, “FR”, “US”). null if the phone number is invalid or country could not be determined.

location

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.

[
  {
    "record_id": "user_001",
    "is_intl": true,
    "most_likely_country": "United Kingdom",
    "inferred_countries": ["United Kingdom"],
    "email_metadata": [
      {
        "email": "[email protected]",
        "is_valid": true,
        "is_intl": true,
        "country_code": "UK",
        "location": "United Kingdom"
      },
      {
        "email": "[email protected]",
        "is_valid": true,
        "is_intl": null,
        "country_code": null,
        "location": null
      }
    ],
    "phone_metadata": [
      {
        "phone": "+44 20 7123 4567",
        "is_valid": true,
        "is_intl": true,
        "standardized_phone": "+442071234567",
        "country_code": "GB",
        "location": "United Kingdom"
      }
    ]
  },
  {
    "record_id": "user_002",
    "is_intl": true,
    "most_likely_country": "France",
    "inferred_countries": ["France"],
    "email_metadata": [
      {
        "email": "[email protected]",
        "is_valid": true,
        "is_intl": true,
        "country_code": "FR",
        "location": "France"
      }
    ],
    "phone_metadata": [
      {
        "phone": "+33 1 23 45 67 89",
        "is_valid": true,
        "is_intl": true,
        "standardized_phone": "+33123456789",
        "country_code": "FR",
        "location": "France"
      },
      {
        "phone": "+33 6 12 34 56 78",
        "is_valid": true,
        "is_intl": true,
        "standardized_phone": "+33612345678",
        "country_code": "FR",
        "location": "France"
      }
    ]
  },
  {
    "record_id": "user_003",
    "is_intl": false,
    "most_likely_country": "United States",
    "inferred_countries": ["United States"],
    "email_metadata": [
      {
        "email": "[email protected]",
        "is_valid": true,
        "is_intl": null,
        "country_code": null,
        "location": null
      }
    ],
    "phone_metadata": [
      {
        "phone": "+1-555-123-4567",
        "is_valid": true,
        "is_intl": false,
        "standardized_phone": "+15551234567",
        "country_code": "US",
        "location": "United States"
      }
    ]
  }
]

Error Responses

400 - Bad Request: Invalid input format
401 - Unauthorized: Invalid API key
404 - Not Found: This endpoint only supports v2 API version (calling /v1/infer_record_country will return this error)
413 - Payload Too Large: More than 1000 records in request
422 - Unprocessable Entity: Invalid data format, including:
- Input data is not a JSON object with a records key
- records field is not a list
- Required fields are missing (e.g., record_id)
- Invalid field types or values
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

Getting Started

Core Endpoints

Validation Workflows

Segments

Quick Answer

Overview

Request

Headers

Request Body

Request Example

Response

Response Structure

Result Object

Email Metadata Object

Phone Metadata Object

Error Responses

Notes

API Version Support

Country Inference Logic

Field Behavior

Validation

Input Field Compatibility

Getting Started

Core Endpoints

Validation Workflows

Segments

​Quick Answer

​Overview

​Request

​Headers

​Request Body

​Request Example

​Response

​Response Structure

​Result Object

Email Metadata Object

Phone Metadata Object

​Error Responses

​Notes

​API Version Support

​Country Inference Logic

​Field Behavior

​Validation

​Input Field Compatibility

Quick Answer

Overview

Request

Headers

Request Body

Request Example

Response

Response Structure

Result Object

Error Responses

Notes

API Version Support

Country Inference Logic

Field Behavior

Validation

Input Field Compatibility