Connect GenderAPI.io V2 with Pipedream

Prepare the account and source record

This example enriches Twilio SendGrid 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.

• Authentication and the free usage check →

Configure the GenderAPI.io V2 request in Pipedream

• Choose the Twilio SendGrid event or schedule that matches your account and workflow. Inspect one test contact, retain its stable ID, and skip empty email values before the enrichment step. The trigger's available interval is a platform setting, not a GenderAPI guarantee.
• Add the Send any HTTP Request action, select POST, and set the URL below. Configure a JSON body with type = email, value = the contact email, and options.ai_mode = off.
• Store your key using Pipedream's credential or environment-variable controls. Set Authorization to Bearer followed by that secret, and set Content-Type to application/json. Do not reuse native query-key authentication or print the key in a step.
• Build the body as a JSON object using the action's supported mapping controls. Avoid assembling raw JSON by concatenating unescaped contact values. Inspect the request preview before deliberately running one test.

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"
  }
}

• All request fields, types and defaults →

Inspect the HTTP step before enabling updates

Inspect the HTTP step's exported response and locate the parsed body. If your chosen action returns body text, parse it once before reading data and meta. A transport wrapper's own data field is distinct from the V2 body's data field.

For a code-based workflow with explicit timeout, redirect and retry behavior, use the tested Node.js guide linked below. The generic action and native app can have different transport defaults.

• Pipedream public GenderAPI.io component →
• Pipedream HTTP request actions →
• Pipedream secret environment variables →
• Pipedream workflow settings and retries →

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.

• Full V2 response reference →
• Error and retry decisions →

Update only the intended Twilio SendGrid record

Keep the returned contact ID from the trigger with the parsed V2 body. After applying the result checks below, update only the intended SendGrid custom fields. Preserve a name supplied by the contact; data.name from an email is an inferred candidate, not a verified replacement.

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.

• Response fields and unknown outcomes →
• Accuracy and confidence explained →
• Data sources and the dated database profile →

Control replays and repeated charges

Pipedream documents plan-dependent automatic retries from the failed step. Review those settings and any retry behavior in the selected HTTP action. A retry of a failed enrichment step can charge again; a later destination failure should be repaired from the saved enrichment output.

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.

• Credit and billing states →

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.

• AI options and nickname inference →
• Credits and usage →

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.

• Batch mapping and partial failures →
• Python implementation guide →
• Node.js implementation guide →

Frequently asked questions