GenderAPI help center
Frequently asked questions
Answers about API V2, free access, AI options, credit costs and privacy. Maintaining an existing integration? Read the V1 reference.
Results & confidence
Understand a prediction and its limits
Country context, confidence scores and unknown results in API V2.
Does a GenderAPI result identify a person’s gender?
No. GenderAPI infers gender from name-related evidence, or from nickname evidence when that option is enabled. A prediction is not a verified personal fact. Preserve uncertainty, respect self-described identity and do not use the inference alone for high-impact decisions.
How does country context affect a result?
An optional uppercase ISO country code provides regional context for the lookup. Supply it only when it is relevant and known. The same name can have different usage across regions; the returned country is a name association, not proof of nationality or residence.
What does the V2 confidence score mean?
confidence is a value from 0 to 1, or null when unavailable. Read confidence_kind with it: observed_frequency describes the dataset’s dominant count divided by its total; model_reported is an AI score. These scores are not calibrated probabilities about a person or measured product accuracy. Set review thresholds using representative data.
What does a null gender mean, and is it charged?
A successful V2 result with gender: null means the available evidence did not identify a gender. It uses native JSON null, not the string "null". A successful unknown result is billable at the selected tariff. Preserve it as unknown; a provider or request failure is a separate error.
Can I submit names in different writing systems?
Yes. Send Unicode names with their original characters and meaningful accents. Coverage and confidence vary by name, region and available evidence, so test a representative sample of the scripts and countries your application serves.
API & AI
Choose a request and AI option
V2 lookup types, batches, AI behavior and usage limits.
Can I analyze names, emails and usernames in one batch?
Yes. POST /api/v2/gender/batch accepts up to 50 items with an API key, or 10 on the IP trial. Each item has its own type, value, optional country and AI settings. Items default to AI off. Inspect each result: a batch can return HTTP 200 with some failed items, and credits are charged per successful item, including unknowns.
How does an email lookup work?
Use type: email with a valid address. The API looks for a usable name signal in the local part before the @ sign; a domain does not establish a person’s identity or country. Shared inboxes and opaque addresses may return unknown. A single request uses AI fallback by default if the dataset is unresolved.
How does a username lookup work?
Use type: username. Ordinary lookup looks for a recognizable given name in a handle or display name. Abstract aliases can return unknown. Enable forceToGenderize when you want nickname-aware AI after an unresolved dataset lookup; this can produce a gender without extracting a real given name.
When does V2 use AI?
Single requests default to options.ai_mode: fallback: the dataset is checked first, then AI is used if gender is unresolved, for 1 credit total. off uses only the dataset for 1 credit; always skips the dataset and uses AI for 2 credits. Batch items default to off and can enable AI individually. None of these modes guarantees a non-null result.
What does forceToGenderize do?
This optional flag works with name, email and username inputs, including individual batch items. A resolved dataset result costs 1 credit. Otherwise, nickname-aware AI is used for 2 credits total, including a successful unknown result. A real given name is not required. Omit ai_mode or use fallback; combining the flag with off or always returns 422.
How are credits deducted in V2?
Read meta.usage.charged_credits for the operation’s net charge and billing_status for its confirmation. Ordinary dataset and fallback predictions cost 1 credit per successful item; always and nickname-aware AI cost 2. Completed phone checks cost 1, including invalid results. A positive starting balance is enough, so the final charge can make it negative. Failed predictions are refunded; unconfirmed billing needs support review.
Does V2 have request limits?
Yes. Current defaults include 120 requests per minute per account, 600 per minute per IP and 2 concurrent operations per account. Shared service capacity also applies. POST bodies are limited to 64 KiB; batches allow 50 items with a key or 10 on the IP trial. Respect HTTP 429 and Retry-After rather than assuming requests will always be accepted at these ceilings.
Can I retry a failed or timed-out request?
Every prediction request is a new operation with normal billing. A timeout or lost response does not prove that no charge occurred. Check billing_status before retrying; contact support with request_id if billing is unconfirmed. For a partial batch, retry only failed items once billing is confirmed. Follow Retry-After on 429.
Where can I find V2 code examples and tools?
The V2 guides include examples in cURL, JavaScript, Python, PHP, Java, C# and Go. Swagger and Postman use the same V2 contract. Choose the input type and keep your API key in server-side configuration.
Can I keep using V1?
Yes. Existing V1 integrations keep their original endpoints and response formats. V1 and V2 share the same API key and credit balance, but their request fields, responses and errors differ. Use the separate V1 reference to maintain an existing client and the migration guide when you are ready to update it.
Privacy & files
Understand data handling
Where to find the current processing, retention and deletion information.
Are successful GenderAPI queries stored?
The Privacy Policy explains which query records, operational records and security logs may be retained, why they are processed and how deletion works. Review those details for your integration and avoid sending unnecessary personal data.
Are email query inputs stored?
Use the Privacy Policy for the current handling of email inputs and related technical records. An email address can be personal data; send only what the lookup requires and avoid including full addresses in your own diagnostic logs.
How long are uploaded Excel or CSV files retained?
The Privacy Policy sets out uploaded-file retention, deletion and backup handling. Export the results you need and use the workspace deletion controls when you no longer need the upload. Contact support for questions about your organization’s retention requirements.
Can service providers process query or uploaded-file data?
The Privacy Policy and subprocessor information describe service-provider processing and the applicable safeguards. Review these resources and any agreement that applies to your account when assessing where your data is processed.
Account & support
Connect your key and manage your account
Free access, authentication, balance checks and support.
Can I try GenderAPI for free?
Yes. A free registered account includes 200 credits per day. Separately, the keyless V2 trial provides 10 credits per public IP in a 24-hour window, shared with V1 and other users on that IP. Both use the normal credit tariffs; credits are not always equal to the number of HTTP requests.
How do I authenticate and protect my API key?
Use Authorization: Bearer YOUR_API_KEY from trusted server-side code; POST requests also need Content-Type: application/json. Keep the real key out of browser code, public repositories and logs. Missing, malformed or unknown keys can use the IP trial, so confirm meta.access.mode is api_key. Known disabled, expired or restricted keys do not fall back to the trial.
How can I check my remaining credits?
Call GET /api/v2/usage with your Bearer key. This balance check is free and returns data.remaining_credits. Without a key, it reads the shared IP trial. V1 and V2 use the same account balance; a prediction’s remaining_credits value is a completion-time snapshot.
Where can I manage or cancel a subscription?
Sign in to the GenderAPI application to manage the subscription associated with your API key. Use the current account controls to review the plan and cancellation options.
Where can I update billing details?
Manage billing and payment settings in the signed-in GenderAPI application for the relevant API key or subscription.
How can I report an incorrect result or request integration help?
Send the API version, endpoint, request_id and a small reproducible example to support. Include the error code when available, but remove your API key and sensitive personal data.
Technical knowledge base
Implementation and responsible-use guides
Detailed answers about V2 responses, errors, authentication and responsible use.
Results, confidence, and responsible use
An unresolved V2 prediction uses native JSON null for gender, not the string "null". A name may be ambiguous or the available evidence insufficient; check result_status and reason when present. Preserve the unknown outcome instead of forcing a category. A successful unknown prediction is billable at the selected tariff. Request or provider errors are separate failures with billing information in meta.usage.
Read the full answer →How is GenderAPI accuracy measured?A useful accuracy evaluation reports its test population, date, sampling method, coverage of unknown results and results by region and writing system. The current methodology page describes an evaluation protocol, not a measured accuracy percentage. V2 confidence and confidence_kind explain each result’s evidence; they are not a substitute for a benchmark on representative data.
Read the full answer →Data sources, privacy, and compliance
The data-provenance page describes the framework for documenting source categories, selection criteria, licensing and geographic or script limitations. It does not currently publish a reviewed source catalogue. Consult that page and contact support for source requirements specific to your integration; do not assume a source, dataset size or coverage figure that has not been documented.
Read the full answer →How often is GenderAPI name data updated?GenderAPI does not state one update schedule for every name record or processing rule on the current provenance page. If freshness affects your use case, ask support about the relevant dataset or workflow and assess representative results. A page’s review date is not evidence that every underlying record was refreshed on that date.
Read the full answer →How does GenderAPI support GDPR and DPA requirements?The Privacy Policy, GDPR information, Data Processing Agreement and subprocessor register describe the published processing terms and safeguards. Review the current documents and any agreement that applies to your account. Contact GenderAPI for organization-specific questions about processing roles, transfers or data-subject requests; a general FAQ does not replace the applicable agreement.
Read the full answer →API operations, errors, and billing
Use Authorization: Bearer YOUR_API_KEY from trusted server-side code. V2 POST requests also require Content-Type: application/json. GET /api/v2/gender additionally accepts a query key, but headers keep credentials out of browser URLs. Missing, malformed or unknown keys can use the shared IP trial; check meta.access.mode is api_key for an account integration. Known disabled, expired or restricted keys do not fall back to a trial.
Read the full answer →How should clients handle rate limits and retries?V2 applies rate and concurrency limits; respect HTTP 429 and Retry-After. Every repeated prediction is a new operation with normal billing. Do not automatically retry a timeout, lost response or unconfirmed billing outcome. Inspect code, action and meta.usage.billing_status first; contact support with request_id for billing_reconciliation_required. Use bounded backoff only when billing is confirmed and the documented action permits a new attempt.
Read the full answer →How should I handle GenderAPI error codes?V2 API errors use HTTP error statuses and RFC 9457 Problem Details with stable code and action fields. Read those fields rather than matching detail wording, and retain request_id for support. A successful unknown result is different from an error. Batch responses can contain item errors even with HTTP 200. A proxy may return a non-JSON error, and a lost or unreadable response does not establish that no charge occurred.
Read the full answer →How can I check remaining credits and quota?Call GET /api/v2/usage with your Bearer API key from trusted server-side code. This request is free and returns data.remaining_credits; omitting a key reads the shared IP trial. V1 and V2 use the same account balance. A prediction’s meta.usage reports that operation’s charge and completion-time balance, which can change with concurrent requests. Keep credentials out of logs and do not treat a balance read as proof that a particular lost request was uncharged.
Read the full answer →How are API versions and breaking changes handled?Use V2 for new integrations and keep existing V1 clients on their documented paths until you choose to migrate them. Both versions share API keys and credits, but use different request fields, response structures and error formats. Follow the migration guide, test successful, unknown and error outcomes, and update your parser before switching endpoints. The V1 reference remains available for existing integrations.
Read the full answer →Where can I check GenderAPI service status and uptime?If requests fail, check the returned error code to distinguish service failures from invalid input, account access, exhausted credits or rate limits. Monitor request success and latency in your own integration. Contact support with request_id for an unexplained failure or billing uncertainty. Use measured monitoring evidence for availability claims; this FAQ does not state a guaranteed uptime percentage.
Read the full answer →Still need help?
Bring us a reproducible example
Include the API version, endpoint, request_id and a small example. Remove your API key and sensitive personal data before sending it.