Personalized onboarding with name greetings, done responsibly

A little personalization makes onboarding feel less like filling in a form. Greeting someone by name, picking a friendly avatar placeholder or matching the tone of a welcome email can all help. Name-based gender predictions can play a small part in that, but only if you use them carefully, default to neutral choices and let people decide for themselves.

This guide shows how to wire Finowl's gender API into onboarding in a way that is low risk, easy to override and respectful.

#Start with the safest personalization

Before reaching for any prediction, use what the user gave you. Their first name is already personal. "Welcome, Priya" needs no gender inference at all, and it is the single most effective personalization in most onboarding flows.

Gender predictions are only relevant when a choice in your interface would otherwise be gendered, for example:

• Choosing a default avatar placeholder from an illustrated set.
• Picking a salutation in languages or regions where formal greetings are gendered.
• Pre-selecting an option in a profile form that the user can change.

If your product can avoid gendered choices altogether, that is usually the better design. Gender-neutral avatars, neutral greetings and "Hi Sam" instead of "Dear Mr. Sam" remove the need for inference entirely.

#Understand what a prediction is

A Finowl prediction is a statistical estimate of how a name is typically used, not how a person identifies. It is wrong for some people. That is true of every name-based method, no matter how good the data is.

This shapes everything below. Treat the prediction as a hint for a default that is cheap to get wrong and easy to change, never as a fact about the user. The estimate reflects how often a name is used for each gender in the underlying data, which is why sample_count matters.

#Responsible-use rules for onboarding

• Use predictions only for low-stakes personalization or aggregate analytics.
• Never use them for eligibility, pricing, access or decisions with significant effects on a person.
• Always let people state or correct their own gender, and let their choice override any prediction permanently.
• Mention name-based lookups in your privacy notice, because names are personal data.

The responsible gender prediction post covers these guardrails in more depth.

#Calling the API during signup

The name endpoint takes a name and an optional country hint. Sending a country helps with names like Andrea, Jean or Kim, which lean differently by country.

curl -X POST https://api.finowl.co/v1/gender/name \
  -H "Authorization: Bearer $FINOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane", "country": "US" }'

A response looks like this:

{
  "data": {
    "result_status": "identified",
    "gender": "female",
    "confidence": 0.98,
    "confidence_kind": "observed_frequency",
    "sample_count": 2570,
    "name": "jane",
    "country": "US",
    "source": "dataset",
    "reason": null
  }
}

If the name is not found or is ambiguous, you get result_status: "unknown", gender: null and a reason such as not_found, no_name_candidate, ambiguous or insufficient_evidence. Unknown is a normal, successful result, and it is charged like any other lookup.

#Send only the first name

For onboarding you only need the given name. There is no reason to send the full name, email or any other field. That keeps the request minimal, which is good data minimization practice.

#Gate on confidence

The most important rule in this design is a confidence gate. Only personalize when the prediction is identified, comes from the dataset, and has high confidence with enough observations behind it. Otherwise fall back to a neutral default.

const NEUTRAL = { avatar: "neutral", salutation: null };

async function onboardingDefaults(firstName, countryCode) {
  try {
    const res = await fetch("https://api.finowl.co/v1/gender/name", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FINOWL_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: firstName,
        country: countryCode,
        options: { ai_mode: "off" },
      }),
    });
    if (!res.ok) return NEUTRAL;

    const { data } = await res.json();
    const confident =
      data.result_status === "identified" &&
      data.source === "dataset" &&
      data.confidence >= 0.95 &&
      data.sample_count >= 100;

    if (!confident) return NEUTRAL;
    return { avatar: data.gender, salutation: data.gender, predicted: true };
  } catch {
    return NEUTRAL;
  }
}

A few choices in this snippet are deliberate.

#Why ai_mode is off here

For single lookups the default ai_mode is fallback, which uses the dataset first and asks AI only if there is no answer. For onboarding defaults, a dataset-only lookup is simpler: you get an observed frequency and a sample_count you can reason about, and anything uncertain becomes neutral. Setting ai_mode: "off" also keeps the cost at 1 credit per lookup, while lookups that force AI with ai_mode: "always" or forceToGenderize: true cost 3 credits. The AI mode guide explains when AI results are worth it.

#Why the threshold is high

A threshold like 0.95 means you only act on names that are strongly associated with one gender in the data. Everything else, including ambiguous names, unfamiliar spellings and unknown results, gets the neutral default. Our post on confidence scores and unknown results covers how to choose thresholds, and the interpreting predictions guide documents each field.

#Why errors fall back silently

Onboarding should never block on enrichment. If the API is slow, rate limited or returns an error, the user gets the neutral default and moves on. Keep a short timeout on the request so it never delays signup.

#Gender-neutral defaults that work

Neutral defaults are not a compromise. Done well, they are the best experience for many users.

Notice the last row. Pronouns should always come from the user. A prediction about a name says nothing reliable about pronouns, so never pre-fill that field.

#Let users choose, and remember it

Every personalized default should be visible and changeable. Show the avatar placeholder with an obvious "Change" control. If you use a gendered salutation, offer a setting for it in the profile. When the user makes a choice:

1. Store it as user-provided and mark the prediction as superseded.
2. Never call the prediction API again for that user.
3. Use the user's choice everywhere the prediction was used.

Store whether a value was predicted or chosen. That distinction helps support teams, keeps analytics honest and makes it easy to honor deletion requests.

#Measure the impact honestly

If you add predicted personalization, measure whether it helps. Compare onboarding completion for a neutral-only variant against the personalized variant. Many teams find that the first-name greeting does most of the work, and the gendered elements add little. If that is true for you, removing them simplifies your stack and your privacy notice.

#Cost and setup

Each name lookup costs 1 credit, and every account gets 100 free credits each month, so small products can test this at no cost. For larger volumes, prepaid packs start at 10,000 credits for $29. See pricing for all packs, and try requests in the Sandbox before writing code. The gender API feature page summarizes the name, email and username endpoints.

#Frequently asked questions

#Is it okay to use gender prediction for onboarding personalization?

It can be, for low-stakes choices such as an avatar placeholder or salutation, if you only act on high-confidence results, default to neutral options and let users change them. Never use predictions for eligibility, pricing, access or other decisions with significant effects.

#What confidence threshold should I use?

For onboarding, a high threshold such as 0.95 combined with a minimum sample_count is a sensible starting point. Anything below it, and every unknown result, should fall back to a neutral default.

#Should I pre-fill pronouns from a name prediction?

No. A name prediction is a statistical estimate of how a name is typically used, not how a person identifies, so pronouns should always be chosen by the user.

#Do unknown results cost credits?

Yes. An unknown result is a normal, successful lookup and costs 1 credit, the same as an identified one. Requests rejected before running, such as invalid input, are free.