Choose the Zapier connection that matches your contract
This guide's HTTP recipe calls GenderAPI.io V2 at https://api.genderapi.io/api/v2/gender. Send type and value in the JSON body; read the estimate from data and the request and billing details from meta. Native connectors have their own contracts, as described below.
Zapier lists GenderAPI.io actions for finding gender from a name or email. The public listing does not establish the endpoint version or a V2 response contract. Existing native-action outputs must be inspected before changing downstream field mappings.
The V2 recipe below uses Webhooks by Zapier with a structured POST payload. Webhooks availability depends on a paid Zapier plan. A GenderAPI account balance and Zapier's own task usage are separate.
Prepare the account and source record
This example enriches Mailchimp records using an email address. You need access to the source and destination apps, a GenderAPI.io account key, and the platform features used by the HTTP action. No working credentials or connected accounts are supplied by this guide.
V1 and V2 use the same account key and balance. Verify the key through GET /api/v2/usage before setting up a billable lookup, and check that meta.access.mode is api_key in that endpoint's response. A missing or unrecognized key can fall back to a shared IP trial; it should not silently power a production automation.
Keep the workflow disabled while configuring it. Sending a test prediction still uses normal credits. These instructions were reviewed against public documentation and the V2 contract; an authenticated end-to-end platform workflow was not executed for this publication.
Configure the GenderAPI.io V2 request in Zapier
- Start with the Mailchimp trigger that supplies the intended subscriber record. Keep its audience and contact identifiers, and add a filter that skips blank emails before the HTTP action.
- Choose Webhooks by Zapier and its POST action. Set the URL below and Payload Type to JSON. Add data fields type = email, value = the mapped subscriber email, and options__ai_mode = off.
- Zapier's double-underscore field notation nests options__ai_mode into options.ai_mode in the JSON body. The code block below shows the resulting API body, not a fourth field to paste into the action.
- Add Authorization with value Bearer YOUR_API_KEY in Headers. Use application/json as Content-Type. Keep the key out of trigger fields, query strings and sample response data.
| HTTP setting | Value | Purpose |
|---|---|---|
Method | POST | Submit one prediction request. |
URL | https://api.genderapi.io/api/v2/gender | The GenderAPI.io V2 single-prediction endpoint. |
Authorization | Bearer YOUR_API_KEY | Replace the placeholder using the platform's authentication/header controls. |
Content-Type | application/json | Send an object with a nested options object, not form fields. |
options.ai_mode | off | A deliberate dataset-only first test; normal charge is 1 credit, even if unknown. |
Check the JSON body before sending
This is a static input illustration, not a predicted result. First verify the request shape; then replace value with the mapped source field using proper JSON serialization. Do not paste platform mapping expressions into the API as literal strings.
For another input, set type to name, email or username and provide the corresponding value. Add country only when reliable context is available; it is optional and is not a country-of-residence lookup.
{
"type": "email",
"value": "alex@example.com",
"options": {
"ai_mode": "off"
}
}Inspect the HTTP step before enabling updates
Webhooks headers are not a dedicated secret connection field: editors with access to the Zap can see them. Restrict access and avoid sharing a Zap, screenshot or export containing the credential. Zapier also offers API by Zapier with stored credentials; its request-body setup differs from this structured POST recipe.
Keep the body unwrapped and send one object, not a list or an array. Prefer the structured JSON action for mapped customer data; Custom Request sends raw text and does not automatically escape interpolated values.
Route identified, unknown and failed outcomes separately
Parse the response body before choosing a destination update. The JSON paths below refer to the V2 body; your platform may wrap or flatten it. Confirm the actual returned structure with a deliberate test and keep the result attached to the source record ID.
An estimate does not establish a person's identity or self-declared gender. Store it separately from information the person provided. Choose acceptance criteria using evidence for your own workload, and evaluate dataset and AI confidence separately.
| Check | Expected value or type | Workflow decision |
|---|---|---|
meta.access.mode | api_key for this account workflow | Stop on ip_trial; correct the key. A successful trial response does not prove account authentication and may already have used trial credits. |
meta.usage.billing_status | confirmed or unconfirmed | If unconfirmed, retain the request ID and seek billing reconciliation before retrying or proceeding. |
data.result_status / data.gender | identified with male or female; unknown with null | Route accepted identified results to a separate inferred field. Preserve unknowns without assigning a default category. |
data.confidence / data.confidence_kind | number from 0 to 1 or null; evidence kind or null | Interpret observed_frequency and model_reported separately; neither is a universal accuracy guarantee. |
data.source / data.sample_count | dataset, ai or none / integer or null | Retain how the estimate was obtained. AI has no stored sample count; a dataset count is not a product accuracy score. |
meta.request_id / meta.usage | request reference / usage object | Store with your workflow record and result. Keep API keys and unnecessary personal input out of routine logs. |
HTTP failure / missing response | Problem Details or no complete response | Pause the update and inspect error and billing state. A timeout does not prove that the server did no work. |
Update only the intended Mailchimp record
Inspect the test action's parsed response and select the fields corresponding to data.gender, data.result_status and the other V2 paths below. Zapier can flatten nested field labels in its picker; use the observed value and parent path rather than assuming a native connector's older probability field.
Test the identified, unknown and error branches before enabling updates. You can use synthetic sample responses to exercise branch conditions without issuing another prediction. A destination update should be conditional on the checks above, and should not overwrite unrelated fields or tags.
Control replays and repeated charges
Review Zapier's Autoreplay and manual replay settings before enabling the Zap. Replaying a failed webhook action submits a fresh lookup; a successful lookup should not be rerun just to repair a later Mailchimp step. Save the original subscriber identifiers and lookup result together.
Each new GenderAPI request is an independent operation. Deduplicate repeated source events in your own workflow before sending, using a stored source ID and processing state. A source-record ID is not a server-side replay protection key.
A successful unknown is a completed billable result. For a timeout or incomplete response, the result and charge may be unknown; keep the request reference when available and reconcile before resubmitting. Respect Retry-After on rate-limit responses when present.
Choose when to use AI
forceToGenderize is optional for names, email addresses and usernames. With it enabled, omit ai_mode or use fallback; off and always conflict with it and return 422. A positive starting balance is enough to begin a request even if its final charge takes the balance below zero.
Nickname mode can return a gender with name: null. It can also return an unknown result. Neither ordinary fallback nor nickname inference guarantees a correct or non-null answer.
| Request option | Behavior | Credits for a successful lookup |
|---|---|---|
| options.ai_mode: off | Use the dataset only. | 1, including an unknown result |
| options.ai_mode: fallback | Try the dataset, then ordinary AI when no gender is returned. This is the single-request default. | 1 total, including AI fallback |
| options.ai_mode: always | Ask AI directly. | 2 |
| forceToGenderize: true | Try the dataset first, then allow AI to interpret a personal nickname or alias even without a real given name. | 1 for a resolved dataset result; 2 total if AI is used |
Validate the workflow before increasing volume
- Verify the real serialized JSON, parsed output paths, API-key access and confirmed billing with one deliberate test. Test unknown and failure routing with fixtures where possible.
- Confirm which workflow steps retry and which customer fields change. Retain the source record ID, completed response and request reference so a later destination failure does not require another lookup.
- Enable a small controlled run and inspect its records and credits before increasing concurrency. GenderAPI credits and the automation platform's task or operation charges are separate.
- For a batch, use POST /api/v2/gender/batch with up to 50 items for API-key access or 10 for the IP trial. The items array can mix names, emails and usernames, with explicit per-item options and unique IDs. Inspect every result; HTTP 200 may contain partial failures. A native connector's batch support must be checked separately.
Frequently asked questions
Why does Zapier use options__ai_mode in the setup?
The structured Webhooks POST action uses double underscores to create nested JSON. The API receives options: {ai_mode: off}, with off as a string. It does not receive a literal top-level options__ai_mode field.
Does the direct HTTP example allow AI?
The first-request body sets options.ai_mode to off. Change it deliberately to fallback for ordinary AI fallback at 1 credit total, or always for AI at 2 credits. forceToGenderize tries the dataset first and costs 1 credit if resolved there or 2 total when AI is used.
Is an unknown result free, or safe to retry automatically?
No. A successful unknown is billable and complete. A replay is a new operation. For transport errors or unconfirmed billing, inspect the returned usage and request reference before deciding whether to resubmit.
Was this workflow executed in a connected account?
No. The platform setup instructions were reviewed against public documentation on 26 September 2026. The GenderAPI.io V2 request and response explanations were reviewed on 27 September 2026. Test the chosen action's current fields, authentication, body, response and retries in your own account before enabling production updates.
Reference sources
Platform references and the GenderAPI V2 contract were reviewed on . Check the listed platform documentation for current setup controls and action availability.