GenderAPI.io V2: Batch names, emails and usernames

Batch names, emails and usernames

Parameter	Type	Required	Default	Description
`items`	`array<object>`	Yes	`—`	Between 1 and 50 prediction items; at most 10 for IP trials. Results preserve input order.
`items[].type`	`string`	Yes	`—`	Input category: name, email or username.
`items[].value`	`string`	Yes	`—`	Required. 1–254 characters; nonblank, without control characters. Email values must be valid email syntax.
`items[].country`	`string`	No	`—`	Optional uppercase ISO 3166-1 alpha-2 code, for example TR or US. Country-specific lookup can fall back to the global dataset.
`items[].forceToGenderize`	`boolean`	No	`false`	Try the dataset first, then nickname-aware AI if unresolved. Supported for name, email and username.
`items[].options`	`object`	No	`—`	Container for per-input AI options.
`items[].options.ai_mode`	`string`	No	`off`	Allowed values: off, fallback, always. With forceToGenderize: true, omit this field or use fallback.
`items[].id`	`string`	No	`—`	Optional 1–64 character identifier in POST JSON. Returned beside each batch result; unique within a batch. Accepted but not echoed for single predictions. Not supported in GET queries.

GenderAPI.io V2 accepts name, email and username items together at POST https://api.genderapi.io/api/v2/gender/batch. Send an items array with 1–50 items for API-key access, or at most 10 for the IP trial. Each item uses type and value and can have its own country, forceToGenderize and options. IDs are optional and must be unique within the batch.

Results preserve input order and include index, your optional id, charged_credits and exactly one of data or error. HTTP 200 can contain item-level failures, so inspect every item. meta.summary reports total, succeeded, identified, unknown and failed. An unknown prediction is a successful, billable item.

Request validation or planning failure rejects the batch before debit. If every executed item fails, the API returns a non-2xx Problem response with a data array and a legacy results alias. Failed items cost zero after a confirmed refund. If billing is unconfirmed, do not assume item charges are final.

Choose your language. Set up your API key, then run the example on your server.

Every prediction request is a new billable operation, including retries. These examples do not automatically retry. Check billing status before sending another request.

Before you run: access and error handling

Run these examples on your server. Set GENDERAPI_API_KEY in the process environment to your existing API key. Confirm meta.access.mode is api_key: an unrecognized key can fall back to the IP trial.

HTTP 4xx and 5xx JSON responses preserve the error body and return a nonzero exit status. Check code, action and meta.usage.billing_status before retrying. For HTTP 200 batch responses, also inspect each item's data or error.

Error and retry guide →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Olivia",
      "country": "US"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ in a POSIX shell. Run in your terminal. Runtime documentation

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Olivia",
      "country": "US"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; built-in fetch. Save as example.mjs and run node example.mjs. Runtime documentation

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Olivia\",\"country\":\"US\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender/batch",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; standard library. Save as example.py and run python3 example.py. Runtime documentation

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Olivia","country":"US"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+ with the cURL extension. Save as example.php and run php example.php. Runtime documentation

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Olivia\",\"country\":\"US\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender/batch"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; standard HTTP client. Save as GenderApiExample.java and run java GenderApiExample.java. Runtime documentation

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Olivia\",\"country\":\"US\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

.NET 8+ console application. Use as Program.cs in a console project, then run dotnet run. Runtime documentation

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Olivia\",\"country\":\"US\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; standard library. Save as main.go and run go run main.go. Runtime documentation

Read a batch response

This example combines two real results captured on 1 October 2026, a dataset match and an unknown result, with an illustrative provider failure. It shows a partial-success HTTP 200 response, not the expected output of the batch request above. The two successful items cost 1 credit each; the failed item has a confirmed zero charge.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Olivia",
          "country": "US"
        },
        "name": "olivia",
        "gender": "female",
        "country": "US",
        "confidence": 0.9968760276224926,
        "confidence_kind": "observed_frequency",
        "sample_count": 6082,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "olivia",
          "method": "normalized",
          "scope": "country",
          "country": "US"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 2,
      "remaining_credits": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}

Batch result fields

Field	Type	Nullable	Example	Description
`data`	`array<object>`	No	`[…]`	Ordered results. Each item contains a prediction or an error; inspect every item.
`data[].index`	`integer`	No	`0`	Zero-based position in the submitted items array.
`data[].id`	`string`	No	`"contact-1"`	Your input identifier, present only when supplied.
`data[].charged_credits`	`integer`	No	`1`	Net item charge after confirmed refunds. Do not treat it as final if overall billing is unconfirmed.
`data[].data`	`object`	No	`{…}`	Present for a successful item, including unknown results. Uses the prediction fields documented in the response guide.
`data[].error`	`object`	No	`{…}`	Present for a failed item instead of data. Uses the Problem Details fields documented in the error guide.

Batch summary fields

Field	Type	Nullable	Example	Description
`meta.summary.total`	`integer`	No	`3`	Total number of items in the batch.
`meta.summary.succeeded`	`integer`	No	`2`	Successful items, including unknown predictions.
`meta.summary.identified`	`integer`	No	`1`	Successful items with a non-null gender.
`meta.summary.unknown`	`integer`	No	`1`	Successful items with a null gender; these are billable results.
`meta.summary.failed`	`integer`	No	`1`	Failed items. total = succeeded + failed; succeeded = identified + unknown.

Access, billing and request metadata

Field	Type	Nullable	Example	Description
`meta.request_id`	`string`	No	`"550e8400-e29b-41d4-a716-446655440000"`	Unique identifier for this HTTP attempt; also sent in X-Request-ID.
`meta.duration_ms`	`integer`	No	`42`	Request processing time in milliseconds.
`meta.access.mode`	`string`	No	`"api_key"`	api_key, ip_trial or unauthenticated. Verify api_key when using a paid account.
`meta.access.reason`	`string`	Yes	`null`	Trial fallback reason: api_key_missing, api_key_invalid or api_key_not_found; null otherwise.
`meta.usage.charged_credits`	`integer`	Yes	`1`	Net credits charged. Zero before charging or after a full confirmed refund; null when billing is unconfirmed.
`meta.usage.remaining_credits`	`integer`	Yes	`99`	Balance when the operation completes. May be negative; null when unavailable or billing is unconfirmed.
`meta.usage.billing_status`	`string`	No	`"confirmed"`	not_charged, confirmed or unconfirmed. Check this before retrying a failed prediction.
`meta.usage.resets_at`	`string`	Yes	`"2026-09-27T12:00:00.000Z"`	IP trial reset time in UTC (ISO 8601); null for API-key accounts or when unknown.
`meta.usage.limit`	`integer`	Yes	`10`	IP trial allowance; null for API-key accounts.
`meta.usage.period_seconds`	`integer`	Yes	`86400`	IP trial window in seconds; null for API-key accounts.

Plan batch credits and retries

Authenticate with your existing Bearer API key and send Content-Type: application/json. Every submitted batch is a new operation. If retrying a partial failure, submit only the failed items after checking billing; resending successful items charges them again.

Batch items default to AI off and cost 1 credit per successful item. Explicit fallback also costs 1 total, including AI. Always costs 2. forceToGenderize costs 1 for a resolved dataset result or 2 if AI is used. Successful unknowns are charged. One positive starting credit is enough to begin the batch; its final charge may leave a negative balance.

Process a contact list and keep every row accounted for

The batch endpoint handles name-only lists, email-only lists and mixed inputs. Split an API-key job into chunks of at most 50 items; the IP trial allows at most 10 per request. Store your own job position and give each item a unique id within its batch. The returned index is zero-based within that submitted chunk, not within the whole contact list.

Step	What to save or check	Why it matters
1. Prepare each chunk	Preserve your source row and item id; set country and AI options per item.	Do not depend on a name being unique across contacts.
2. Read the whole response	Save meta.request_id and map each data[] entry using id or index.	HTTP 200 can contain both successful predictions and item errors.
3. Store successful outcomes	Keep identified and unknown predictions, including JSON nulls and the evidence fields.	An unknown is a completed, billable result; it is not a failed row to retry automatically.
4. Reconcile errors and credits	Inspect each error and meta.usage.billing_status before deciding on another request.	When billing is confirmed, only retry failed items whose error warrants a retry. Successful items would be charged again.
5. Pause uncertain retries	Retain the request ID when billing is unconfirmed or a network failure leaves the outcome unknown.	Do not blindly resend the whole chunk; follow the errors and billing guidance first.

Choose an inference mode for each contact

This runnable request uses three different policies: dataset-only for a full name, ordinary AI fallback for an email, and nickname-aware fallback for a username. It is an example input, not a promise that all three contacts will receive a gender. Choose a language above the code and set GENDERAPI_API_KEY before running it.

Without forceToGenderize, batch items default to AI off, unlike single lookups. Set fallback explicitly for ordinary AI fallback. Both off and ordinary fallback cost 1 credit per successful item; always skips the dataset and costs 2. forceToGenderize costs 1 for a resolved dataset result or 2 total if AI is used. Successful unknown outcomes are also charged. Do not combine forceToGenderize with off or always.