Skip to main content
POST
/
v2
/
infer_record_country
Infer Record Country
curl --request POST \
  --url https://api.minerva.io/v2/infer_record_country \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "records": [
    {
      "record_id": "<string>",
      "emails": [
        "<string>"
      ],
      "phones": [
        "<string>"
      ],
      "first_name": "<string>",
      "last_name": "<string>",
      "middle_name": "<string>",
      "full_name": "<string>",
      "name_suffix": "<string>"
    }
  ]
}'
[
  {
    "record_id": "user_001",
    "is_intl": true,
    "most_likely_country": "United Kingdom",
    "inferred_countries": ["United Kingdom"],
    "email_metadata": [
      {
        "email": "john.smith@example.co.uk",
        "is_valid": true,
        "is_intl": true,
        "country_code": "UK",
        "location": "United Kingdom"
      },
      {
        "email": "j.smith@gmail.com",
        "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": "marie@example.fr",
        "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": "contact@example.com",
        "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"
      }
    ]
  }
]

​
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
This is useful for international data processing, lead routing, and compliance purposes.

​
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.

​
Request Example

{
  "records": [
    {
      "record_id": "user_001",
      "emails": ["john.smith@example.co.uk", "j.smith@gmail.com"],
      "phones": ["+44 20 7123 4567"]
    },
    {
      "record_id": "user_002",
      "first_name": "Marie",
      "last_name": "Dubois",
      "emails": ["marie@example.fr"],
      "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
​
email
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": "john.smith@example.co.uk",
        "is_valid": true,
        "is_intl": true,
        "country_code": "UK",
        "location": "United Kingdom"
      },
      {
        "email": "j.smith@gmail.com",
        "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": "marie@example.fr",
        "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": "contact@example.com",
        "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