Reading predictions

Every gender endpoint returns a prediction object:

{
  "data": {
    "result_status": "identified",
    "gender": "female",
    "confidence": 0.97,
    "country": "US"
  }
}

Fields

string

required

identified when Finowl intelligence made a prediction, unknown when the input did not carry enough signal. Both are successful responses.

string | null

required

male or female when identified, null when unknown.

number

How confident the estimate is. Higher means more certain. Use it to decide when a prediction is strong enough for your use case.

string | null

The country context used for the prediction. This is never proof of where a person lives.

The prediction object can include additional fields, and new ones may be added over time. Read the fields you need and ignore the rest.

Handle unknown results

unknown is a real answer, not an error. You are charged for it, and you should store it so you do not ask again.

const { data } = await response.json();

const gender = data.result_status === "identified" ? data.gender : null;

Never replace unknown with a default value. A contact with no prediction is better than a contact with a wrong one.

Use a confidence threshold

Pick a threshold that matches the cost of being wrong:

Use case	Suggested approach
Aggregate analytics, such as audience mix	Use all identified predictions
Light personalization, such as a greeting	Use only high confidence predictions
Anything with real consequences for a person	Do not use predictions. Ask the person.

AI modes

Finowl intelligence first looks the input up in a large name dataset. The options.ai_mode field controls whether AI is used when the dataset has no answer.

Mode	Behavior	Default for
`fallback`	Dataset first, AI only when the dataset has no answer	Single lookups
`off`	Dataset only. More `unknown` results, most predictable	Batch items
`always`	Always use AI	Neither

{ "name": "Kiri", "options": { "ai_mode": "always" } }

The mode does not change what you pay. Every lookup costs 1 credit.

Using predictions responsibly

A gender prediction is a statistical guess based on how a name is typically used. It does not tell you how a person identifies, and it is wrong for some people every time.

Use predictions for aggregate insight and low-stakes personalization only.
Never use them to decide eligibility, pricing, access or anything else that significantly affects someone.
Give people a way to state or correct their own gender, and always prefer what they tell you.
Mention the lookup in your privacy notice, because it processes personal data.

Get started

Core concepts

Guides

Reading predictions

Fields

Handle unknown results

Use a confidence threshold

AI modes

Using predictions responsibly

​Fields

​Handle unknown results

​Use a confidence threshold

​AI modes

​Using predictions responsibly

Fields

Handle unknown results

Use a confidence threshold

AI modes

Using predictions responsibly