POST /predict_gender • Credits: 1 credit per call

Predict Gender takes one first name and returns the gender that is most common for that name. The response holds a gender value of male, female or unknown, a probability score, and a count of the sample behind that score. The result is a statistical prediction from the name alone, and each call costs 1 credit.

What does Predict Gender do?

A contact record often holds a first name and no gender field. Predict Gender sends that first name to a third-party name data set. The data set counts first name records and reports the majority gender for the name. Predict Gender returns that majority gender, the share of the sample behind it, and the size of the sample. The endpoint reads the first name only. It reads no photo, no pronoun, no profile text and no country.

A Predict Gender result describes a name. It does not describe the person in your record.

CAUTION: Do not use the gender field to decide anything about a person. The value is a prediction from a first name, and it can be wrong for any single record.

Decisions that affect a person include hiring, pay, pricing, credit, insurance, eligibility and access. Predict Gender is not a valid input for any of those decisions.

Which endpoint does Predict Gender use?

Method: POST
URL: https://api.richapi.ai/api/v1/predict_gender
Authentication: x-api-key header
Response: Synchronous JSON
Credits: 1 credit per call
Data source: A third-party name data set

How to send a Predict Gender request

Copy your API key from the RichAPI dashboard.
Set the name parameter to the first name of the contact.
Send a POST request to https://api.richapi.ai/api/v1/predict_gender.
Send the API key in the x-api-key header.
Read the gender field and the probability field from the response.
If gender is unknown, apply a neutral fallback in your own code.
If probability is below your own threshold, apply the same neutral fallback.

CAUTION: Each Predict Gender call costs 1 credit. A response with the gender value unknown also costs 1 credit.

cURL

curl -X POST https://api.richapi.ai/api/v1/predict_gender   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "name": "Alexandra"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/predict_gender",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"name": "Alexandra"},
    timeout=60,
)
response.raise_for_status()
result = response.json()
print(result["gender"], result["probability"])

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/predict_gender", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Alexandra" }),
});

const data = await response.json();
console.log(data.gender, data.probability);

Which parameters does Predict Gender accept?

Parameter	Type	Required	Default	Description
`name`	string	Yes	`""`	The first name to predict a gender for. RichAPI removes the leading and the trailing spaces. An empty value returns a `400` error.

Predict Gender accepts one parameter. It accepts no country parameter, no language parameter and no batch parameter. One call covers one name.

What does Predict Gender return?

The block below is an example response for the name Alexandra. The field names and the structure are exact. The probability and the count are illustrative.

{
  "name": "Alexandra",
  "gender": "female",
  "probability": 0.97,
  "count": 54032
}

Which fields does the Predict Gender response hold?

Field	Type	Description
`name`	string	The first name from the request body, without the leading and the trailing spaces.
`gender`	string	The predicted gender. The value is `male`, `female` or `unknown`. The endpoint returns no other value.
`probability`	number or null	The probability score for the returned gender, from `0` to `1`. The value is `null` for a call that the data set did not answer.
`count`	integer or null	The number of records in the data set for the name. The value is `null` for a call that the data set did not answer.

The response holds no field named confidence. The score field is probability.

What does the Predict Gender value unknown mean?

Predict Gender returns the gender value unknown in two cases:

The data set holds no gender for the name.
The data set does not answer inside the 5 second timeout, or the call to the data set fails.

For the second case, probability and count are both null. The block below is an example of that response:

{
  "name": "Xhuljano",
  "gender": "unknown",
  "probability": null,
  "count": null
}

A response with the gender value unknown returns the HTTP status 200. It is a result, not an error. RichAPI charges 1 credit for it. Treat the value unknown as "no answer" and apply your own neutral fallback.

Which limits apply to a Predict Gender result?

Predict Gender reports a majority across a name data set. Five known limits apply to every result.

Limit	Effect on the result
A name common to several genders, such as Jordan, Alex, Sam or Robin.	The response returns the majority gender for the name. The `probability` value falls toward `0.5`.
A name outside the data set.	The response returns the `gender` value `unknown`.
A transliterated name, or a second spelling of the same name.	The data set holds few records for that spelling, or none. The result is a low `count`, or the value `unknown`.
A name with a different majority gender in a different country.	The endpoint accepts only the `name` parameter, so the answer carries no country context.
A person whose gender differs from the majority for their first name.	The prediction is wrong for that record, and the `probability` value gives no warning.

A high probability value describes the name data set. It does not raise the accuracy for one person.

Which use cases fit Predict Gender?

Two use cases fit a probabilistic result. Both of them tolerate a wrong single row.

Aggregate analysis. Count the predicted genders across a list of contacts, then report the distribution of the list. The report states a property of the list, and not a fact about one person. Report the unknown share as its own group. Never write the predicted value back to the record of a person as a verified field.

Salutation defaults with a neutral fallback. Pick the salutation of an email from the gender value, and keep a neutral salutation for every other case.

Send the first name of the contact to Predict Gender.
Set a probability threshold in your own code, for example 0.9.
If gender is male and probability is at or above the threshold, use the male salutation.
If gender is female and probability is at or above the threshold, use the female salutation.
For every other case, use the neutral salutation, such as the first name alone.
Let the contact correct the salutation, and store that correction as the truth.

How much does Predict Gender cost?

Predict Gender costs 1 credit per call. 1 credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. The table uses $0.02. The credit count does not change with the gender value, so a male result, a female result and an unknown result each cost 1 credit.

Calls	Credits	Cost
1	1	$0.02
100	100	$2.00
1,000	1,000	$20.00
10,000	10,000	$200.00

A list of 10,000 contacts costs 10,000 credits, or $200.00. To lower the cost of a repeated list, cache the result per unique first name in your own store.

Which errors can Predict Gender return?

Status	Meaning	What to do
`400`	The request body is empty, the body is not valid JSON, or the `name` value is empty.	Send a JSON object with a non-empty `name` value.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	The organization has no credits left, or the team reached its monthly spend limit.	Buy credits in the RichAPI dashboard.
`403`	This API key has no access to this endpoint (`Endpoint not available on your plan`).	Call `GET /api/v1/my-endpoints` to see the endpoints that this key can use. Contact support for access.
`404`	The endpoint name is wrong.	Send the request to `/predict_gender`.
`405`	The request method is not `POST`.	Send the request with the `POST` method.
`429`	The request rate is over the limit.	Wait, then send the request again. For a higher limit, contact support.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

RichAPI charges no credit for a 400, 401, 402, 403, 404, 405, 429 or 500 response.

A failure of the name data set returns no error status. Predict Gender returns the HTTP status 200 with the gender value unknown, and RichAPI charges 1 credit. To detect that case, check for probability set to null.

Frequently asked questions

Does Predict Gender return a confidence score?

Yes. Predict Gender returns a probability field with a value from 0 to 1 for the predicted gender. The response holds no field named confidence.

Which values can the Predict Gender gender field hold?

The gender field holds one of three values: male, female or unknown. Predict Gender returns no other value, and it never returns an empty string or null for that field.

Is a Predict Gender result accurate?

A Predict Gender result is a statistical prediction from a first name, and not a verified fact about a person. It can be wrong for any single record, so it is not a valid input for a decision that affects a person.

Why does Predict Gender return unknown for some names?

The value unknown means that Predict Gender made no decision for the name. Either the data set holds no gender for the name, or the data set did not answer inside the 5 second timeout.

Where does Predict Gender get its data?

Predict Gender calls a third-party name data set, which counts first name records. The count field reports how many records support the returned gender.

Can I send a full name to Predict Gender?

Send the first name only. Predict Gender sends the whole name value to the data set as one string, so a full name lowers the chance of a match.

Can I set a country for a Predict Gender request?

No. Predict Gender accepts only the name parameter, so every result is a global majority. A name with a different majority gender in a different country returns the global answer.

Does an unknown result cost a credit?

Yes. A response with the gender value unknown returns the HTTP status 200, and RichAPI charges 1 credit for it. Only a 400, 401, 402, 403, 404, 405, 429 or 500 response costs no credit.

Predict Gender API