# Nationalize

> Predict which country a name most likely comes from. Send a surname like Nguyen or a full name like Sarah Johnson and Nationalize answers with up to five countries, each with a probability and the number of records behind it, so a workflow can route a lead to the right regional team, pick a language to write in, or fill in a likely country on a contact record. Names can be checked one at a time or a hundred at once.

App · Contact Management · 4 actions. Web page: https://docs.lodol.com/docs/integrations/nationalize

## Actions

### Check a name against a country

Check whether a name is likely to come from one particular country: for routing a lead to a regional team or picking a language to write in. Answers yes or no with a probability rather than failing, and says which country the name really points to when the answer is no.

**Inputs**

- Name (`name`, text, required): The name to place. A surname on its own works, and a full name works better -- 'Sarah Johnson' is a stronger prediction than 'Johnson'. Titles, initials and nicknames are fine, the order of the parts does not matter, and accents are optional.
- Country (`country`, text, required): The country to check the name against. One of: `AF` (Afghanistan), `AX` (Åland Islands), `AL` (Albania), `DZ` (Algeria), `AS` (American Samoa), `AD` (Andorra), `AO` (Angola), `AI` (Anguilla), `AQ` (Antarctica), `AG` (Antigua & Barbuda), and 239 more.

**Outputs**

- `country` (text): The country it was checked against.
- `country_code` (text): That country's two-letter code.
- `is_likely` (true/false): True when Nationalize lists this country among the name's likely origins.
- `name` (text): The name checked.
- `probability` (number): How likely this country is, between 0 and 1. Zero when Nationalize does not list it at all.
- `rank` (number): Where this country places among the name's countries, 1 being the most likely. Empty when it is not among them.
- `records` (number): How many records the prediction is based on.
- `top_country` (text): The country the name most likely comes from.
- `top_country_code` (text): That country's two-letter code.
- `top_probability` (number): How likely that country is, between 0 and 1.
- `url` (text): Nationalize's website.

**Example output**

```json
{
  "country": "Japan",
  "country_code": "JP",
  "is_likely": true,
  "name": "Hiroshi Tanaka",
  "probability": 0.9312,
  "rank": 1,
  "records": 41208,
  "top_country": "Japan",
  "top_country_code": "JP",
  "top_probability": 0.9312,
  "url": "https://nationalize.io/"
}
```

### Check your remaining names

Check how many names your Nationalize plan has left this billing period, so a workflow can hold off on a large batch rather than run out halfway. Nationalize reports this only alongside a lookup, so the check itself uses one name.

**Inputs**: None.

**Outputs**

- `names_allowed` (number): How many names the plan allows per period.
- `names_remaining` (number): How many are left in the current period.
- `names_used` (number): How many have been used in this period.
- `resets_at` (text): When the period resets, in UTC.
- `resets_in_days` (number): How many days until it resets.
- `url` (text): Nationalize's website.

**Example output**

```json
{
  "names_allowed": 2500,
  "names_remaining": 2371,
  "names_used": 129,
  "resets_at": "2026-10-01T00:00:00Z",
  "resets_in_days": 28,
  "url": "https://nationalize.io/"
}
```

### Predict nationality

Predict which country a name is most likely to come from. Returns the most likely country on its own, so a step can use it straight away, with up to four runners-up behind it and the number of records the prediction rests on.

**Inputs**

- Name (`name`, text, required): The name to place. A surname on its own works, and a full name works better -- 'Sarah Johnson' is a stronger prediction than 'Johnson'. Titles, initials and nicknames are fine, the order of the parts does not matter, and accents are optional.

**Outputs**

- `candidates` (list): Up to five countries, most likely first.
- `country` (text): The most likely country's English name. Empty when not found.
- `country_code` (text): The most likely country's two-letter code.
- `found` (true/false): False when Nationalize has no records for this name.
- `name` (text): The name that was looked up.
- `probability` (number): How likely the most likely country is, between 0 and 1.
- `records` (number): How many records the prediction is based on.
- `url` (text): Nationalize's website.

**Example output**

```json
{
  "candidates": [
    {
      "country": "United States",
      "country_code": "US",
      "probability": 0.4104,
      "rank": 1
    },
    {
      "country": "United Kingdom",
      "country_code": "GB",
      "probability": 0.1386,
      "rank": 2
    },
    {
      "country": "Canada",
      "country_code": "CA",
      "probability": 0.0494,
      "rank": 3
    },
    {
      "country": "Australia",
      "country_code": "AU",
      "probability": 0.0377,
      "rank": 4
    },
    {
      "country": "Nigeria",
      "country_code": "NG",
      "probability": 0.0295,
      "rank": 5
    }
  ],
  "country": "United States",
  "country_code": "US",
  "found": true,
  "name": "Sarah Johnson",
  "probability": 0.4104,
  "records": 2147809,
  "url": "https://nationalize.io/"
}
```

### Predict nationality for several names

Predict where each name in a list is from, in a single request: for enriching a list of contacts or a spreadsheet column. Takes up to 100 names at a time. Each name counts against your monthly quota, so repeated names are looked up only once.

**Inputs**

- Names (`names`, list, required): The names to place, one per entry. A surname works, a full name works better. Up to 100 at a time; repeated names are looked up once.

**Outputs**

- `found_count` (number): How many of them Nationalize could place.
- `name_count` (number): How many names were looked up.
- `results` (list): One answer per name, in the order given.
- `url` (text): Nationalize's website.

**Example output**

```json
{
  "found_count": 2,
  "name_count": 2,
  "results": [
    {
      "candidates": [
        {
          "country": "Vietnam",
          "country_code": "VN",
          "probability": 0.5612,
          "rank": 1
        },
        {
          "country": "United States",
          "country_code": "US",
          "probability": 0.0353,
          "rank": 2
        }
      ],
      "country": "Vietnam",
      "country_code": "VN",
      "found": true,
      "name": "Nguyen",
      "probability": 0.5612,
      "records": 360408
    },
    {
      "candidates": [
        {
          "country": "Germany",
          "country_code": "DE",
          "probability": 0.2245,
          "rank": 1
        },
        {
          "country": "Denmark",
          "country_code": "DK",
          "probability": 0.1201,
          "rank": 2
        }
      ],
      "country": "Germany",
      "country_code": "DE",
      "found": true,
      "name": "Schmidt",
      "probability": 0.2245,
      "records": 187032
    }
  ],
  "url": "https://nationalize.io/"
}
```