Nationalize API
Official vendor OpenAPI document · agent-readyData EnrichmentContact EnrichmentapiKey1 EndpointsREST
For Agents
Predict the most likely countries of origin for any first name and return ranked country codes with probability scores.
Use for: Predict the country of origin for the first name 'Liam', Get nationality probabilities for a list of customer first names, Find the most likely country for a name in my signup form, Enrich a contact record with a probable nationality field
Not supported: Does not predict gender, age, ethnicity, or full identity from names - use for first-name to country probability prediction only.
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.
Install Jentic One Beta
Connect the Nationalize API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Nationalize API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnationalize.io%2Fnationalize" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnationalize.io%2Fnationalize" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Nationalize API.
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
Patterns agents use Nationalize API for, with concrete tasks.
★ 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.
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.
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.
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.
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
1 endpoints — 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.
METHOD
PATH
DESCRIPTION
GET
/
Predict country of origin for one or more first names
GET
/
Predict country of origin for one or more first names
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Nationalize API through Jentic.
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.
GET STARTED