> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Infer Record Country

> Infer country location from email addresses and phone numbers

<div style={{ display: 'none' }} aria-hidden="false">
  ## 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
</div>

## 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

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  application/json
</ParamField>

### Request Body

<ParamField body="records" type="object[]" required>
  An array of records containing contact information. Maximum 1000 records per request.

  <Expandable title="Record object properties">
    <ParamField body="record_id" type="string" required>
      Your unique identifier for this record
    </ParamField>

    <ParamField body="emails" type="string[]">
      Array of email addresses to analyze. Emails are validated and analyzed for country-specific TLDs.
    </ParamField>

    <ParamField body="phones" type="string[]">
      Array of phone numbers to analyze. Supports various formats including E.164, international format with `+`, and local formats.
    </ParamField>

    <ParamField body="first_name" type="string">
      First name (optional, accepted but not used for country inference)
    </ParamField>

    <ParamField body="last_name" type="string">
      Last name (optional, accepted but not used for country inference)
    </ParamField>

    <ParamField body="middle_name" type="string">
      Middle name (optional, accepted but not used for country inference)
    </ParamField>

    <ParamField body="full_name" type="string">
      Full name (optional, accepted but not used for country inference)
    </ParamField>

    <ParamField body="name_suffix" type="string">
      Name suffix (optional, accepted but not used for country inference)
    </ParamField>

    **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.
  </Expandable>
</ParamField>

### Request Example

```json theme={null}
{
  "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

<ResponseField name="record_id" type="string">
  Your identifier from the request
</ResponseField>

<ResponseField name="is_intl" type="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
</ResponseField>

<ResponseField name="most_likely_country" type="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.
</ResponseField>

<ResponseField name="inferred_countries" type="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.
</ResponseField>

<ResponseField name="email_metadata" type="array">
  Detailed metadata for each email address analyzed
</ResponseField>

<ResponseField name="phone_metadata" type="array">
  Detailed metadata for each phone number analyzed
</ResponseField>

##### Email Metadata Object

<ResponseField name="email" type="string">
  The email address as provided in the request
</ResponseField>

<ResponseField name="is_valid" type="boolean">
  Whether the email address passed basic validation (format check, sanitization)
</ResponseField>

<ResponseField name="is_intl" type="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
</ResponseField>

<ResponseField name="country_code" type="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.
</ResponseField>

<ResponseField name="location" type="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.
</ResponseField>

##### Phone Metadata Object

<ResponseField name="phone" type="string">
  The phone number as provided in the request
</ResponseField>

<ResponseField name="is_valid" type="boolean">
  Whether the phone number passed validation and could be parsed successfully
</ResponseField>

<ResponseField name="is_intl" type="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
</ResponseField>

<ResponseField name="standardized_phone" type="string | null">
  Phone number in E.164 format (e.g., "+442071234567"). `null` if the phone number is invalid.
</ResponseField>

<ResponseField name="country_code" type="string | null">
  Uppercase ISO country code (e.g., "GB", "FR", "US"). `null` if the phone number is invalid or country could not be determined.
</ResponseField>

<ResponseField name="location" type="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.
</ResponseField>

<Note>
  Error responses include `statusCode` and `body` fields for backward compatibility with existing integrations. These are deprecated — prefer reading the HTTP status code and the top-level `api_request_id` / `error_message` fields directly.
</Note>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "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"
        }
      ]
    }
  ]
  ```

  ```json 400 theme={null}
  {
    "api_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "error_message": "Input data must contain a 'records' key with a list of inputs"
  }
  ```

  ```json 401 theme={null}
  {
    "api_request_id": "b2c3d4e5-f6a7-1234-bcde-f12345678901",
    "error_message": "Unauthorized"
  }
  ```

  ```json 413 theme={null}
  {
    "api_request_id": "d4e5f6a7-b8c9-3456-def0-234567890123",
    "error_message": "Maximum number of records for /v2/infer_record_country endpoint is 1000"
  }
  ```

  ```json 422 theme={null}
  {
    "api_request_id": "e5f6a7b8-c9d0-4567-ef01-345678901234",
    "error_message": "Input data must contain a 'records' key with a list of inputs"
  }
  ```

  ```json 429 theme={null}
  {
    "api_request_id": "f6a7b8c9-d0e1-5678-f012-456789012345",
    "error_message": "You reached your total request-rate limit, please contact help@minerva.io for help"
  }
  ```
</ResponseExample>

## 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