canonical: https://jentic.com/apis/nationalize.io/nationalize

# Nationalize API

The Nationalize API predicts the most likely countries of origin for a given first name based on a probabilistic model trained on hundreds of millions of name-to-country pairings. A single GET request accepts one or more names and returns ranked country codes with probability scores. It is designed for quick contact enrichment, audience segmentation, and personalisation tasks where a country guess is enough to drive downstream logic.

## For AI agents

Predict the most likely countries of origin for any first name and return ranked country codes with probability scores.

## Scope

Does not predict gender, age, ethnicity, or full identity from names - use for first-name to country probability prediction only.

## Capabilities

- Predict the country of origin for a single first name with probability scores
- Run batch nationality predictions across up to 10 names per request
- Return ISO 3166-1 alpha-2 country codes ranked by likelihood for downstream routing
- Enrich CRM contact records with a probable country signal where address data is missing
- Localise marketing and onboarding flows based on predicted nationality of the user's first name

## Use cases

### Lead Enrichment by Predicted Nationality

Sales and marketing teams often capture only a first name on a lead form yet still need a country signal to route the lead or personalise outreach. A single call to the Nationalize API returns ranked country codes with probability scores, letting downstream automation decide which sales region or language template to apply. Integration is a one-endpoint job and typically takes under an hour to wire into a CRM webhook.

Example prompt: Send a GET to / with name=Lukas and return the top country code along with its probability for use in lead routing.

### Audience Segmentation in Marketing

Marketers running multi-region campaigns can group audiences by the predicted nationality of subscribers when explicit country fields are unreliable. The API supports up to ten name lookups per request, so list cleanup workflows can score a contact list at low cost. The output integrates cleanly into ESPs and customer data platforms as an enrichment column.

Example prompt: Pass ten subscriber first names to / and tag each contact in the ESP with the highest-probability country code returned.

### Demographic Research and Analytics

Researchers and product analysts use Nationalize to study patterns in user names across product cohorts without requesting personal data from users. Aggregating predictions over a cohort gives a rough country distribution that informs internationalisation and product decisions, while staying within the privacy boundary of using only first names. The endpoint returns deterministic probabilities that can be cached for repeat lookups.

Example prompt: Iterate over a cohort of 500 first names, call / for each, and produce a histogram of predicted country codes.

### Agent-Driven Contact Enrichment via Jentic

Agent assistants enriching contact records in a CRM need a quick nationality estimate without managing a Nationalize key directly. Through Jentic, the agent searches by intent and executes the single Nationalize operation against a name input, receiving country probabilities back as JSON. Jentic stores the API key and injects it at runtime, isolating the secret from the agent context.

Example prompt: Search Jentic for 'predict nationality from a first name', load the operation schema, and execute it with the lead's first name to populate a 'predicted_country' CRM field.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | / | Predict country of origin for one or more first names |

## Key resources

- **Name Prediction** — Single endpoint that accepts a first name and returns ranked country probability predictions

## Why Jentic

- **Setup:** Wiring Nationalize by hand means passing the apikey as a query parameter on the api.nationalize.io host and handling rate limits and errors yourself. Through Jentic you install once, import the Nationalize API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Nationalize exposes a single read-only operation that takes a first name in the query, so scope the agent to just that operation. It predicts the country probabilities for a name and does nothing else, since no other operation is in the allowed set.
- **Credential handling:** Your Nationalize api_key is stored once, encrypted, by your own Jentic One instance and injected as the apikey query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'predict nationality from a first name', and Jentic returns the single Nationalize operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Genderize API** — Predicts gender from a first name and is commonly chained with Nationalize for richer profile inference.
- **Agify API** — Predicts an age range for a first name from the same family of name-statistics APIs.
- **NamSor API** — Commercial onomastic API that predicts nationality, ethnicity, and gender from full names with higher accuracy.

## FAQ

### What authentication does the Nationalize API use?

The API uses an API key passed as the apikey query parameter. Free usage is available without a key up to a daily limit; paid plans require a key. Jentic stores the key in its vault and appends it at request time.

### Can I predict the country for multiple names in one Nationalize API call?

Yes. The single GET / endpoint accepts up to 10 name parameters per request and returns a ranked country list with probability scores for each name in the response array.

### What are the rate limits for the Nationalize API?

Free tier is capped at 100 requests per day across an IP. Paid plans on nationalize.io raise the daily quota and add commercial-use rights; the OpenAPI spec does not publish per-second limits.

### How do I predict a name's country of origin through Jentic?

Run pip install jentic, search for 'predict nationality from a first name', load the schema for the / operation, and execute it with the name parameter. Run it through Jentic One, the self-hosted execution layer, to obtain an agent API key.

### Does the Nationalize API return ISO country codes?

Yes. Each prediction in the response carries a country_id field containing the ISO 3166-1 alpha-2 code together with a probability score, suitable for direct use in routing or segmentation logic.

### Can I limit what my agent is allowed to do with the Nationalize API?

Yes. Nationalize exposes a single read-only operation that takes a first name and returns ranked country probabilities, so in your self-hosted Jentic One you set the rules and scope the agent to just that one prediction call. Because no other operation is in the allowed set, the agent can predict country probabilities for a name and nothing else. Your Nationalize API key stays with your own instance and is injected as the query parameter at request time, so the agent never sees it.