BulkRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/namegender/main/json-schema/namegender-bulk-request-schema.json",
  "title": "BulkRequest",
  "x-generated": "2026-10-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/namegender-api-openapi.json#/components/schemas/BulkRequest",
  "type": "object",
  "required": [
    "names"
  ],
  "properties": {
    "names": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "description": "The values to resolve, each at most 200 characters. Each one costs one credit."
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "ISO-3166 alpha-2 code applied to every value in the batch."
    },
    "locale": {
      "type": "string",
      "maxLength": 35,
      "description": "Language tag whose region becomes the batch country when `country` is not sent, for example `it-IT`. A tag without a region sets no country."
    },
    "ip": {
      "type": "string",
      "maxLength": 45,
      "description": "End user IP address whose country becomes the batch country when neither `country` nor a regional `locale` is sent. Not stored. IP geolocation by DB-IP (db-ip.com), CC BY 4.0."
    },
    "type": {
      "type": "string",
      "enum": [
        "name",
        "email",
        "username"
      ],
      "default": "name",
      "description": "How to read the values in `names`."
    },
    "ai_fallback": {
      "type": "boolean",
      "default": false,
      "description": "Ask a language model for values the dataset cannot answer. Requires AI lookups to be enabled in account settings; otherwise the batch fails with `ai_consent_required`."
    },
    "best_guess": {
      "type": "boolean",
      "default": false,
      "description": "Return the most likely gender even below the confidence threshold, instead of null. For `email` and `username` batches it applies to the extracted first name."
    }
  }
}