BulkResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/bestprintondemand/main/json-schema/bestprintondemand-bulk-response-schema.json",
  "title": "BulkResponse",
  "x-generated": "2026-10-06",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bestprintondemand-openapi.json#/components/schemas/BulkResponse",
  "allOf": [
    {
      "$ref": "#/$defs/Envelope"
    },
    {
      "type": "object",
      "required": [
        "results",
        "summary"
      ],
      "properties": {
        "took_ms": {
          "type": "integer",
          "description": "Whole milliseconds spent resolving the batch on our side, network time excluded."
        },
        "country_source": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "country",
            "locale",
            "ip",
            null
          ],
          "description": "Where the country came from: the `country` parameter, the region of `locale`, the `ip` address, or none of them (null, worldwide answer)."
        },
        "summary": {
          "type": "object",
          "description": "Counts for the whole batch.",
          "properties": {
            "total": {
              "type": "integer",
              "description": "Values sent."
            },
            "identified": {
              "type": "integer",
              "description": "Values with a non-null `gender`."
            },
            "unknown": {
              "type": "integer",
              "description": "Values with `gender: null`."
            },
            "match_rate": {
              "type": "number",
              "description": "Percentage identified."
            }
          }
        },
        "results": {
          "type": "array",
          "description": "Same order as the names you sent.",
          "items": {
            "$ref": "#/$defs/GenderResult"
          }
        }
      }
    }
  ],
  "$defs": {
    "Envelope": {
      "type": "object",
      "required": [
        "credits_charged",
        "credits_remaining"
      ],
      "properties": {
        "credits_charged": {
          "type": "integer",
          "description": "How many credits this call took from the balance: one per value resolved."
        },
        "credits_remaining": {
          "type": "integer",
          "description": "Balance once this call is paid for: purchased credits plus whatever is left of today's free quota."
        },
        "data_version": {
          "type": [
            "string",
            "null"
          ],
          "description": "Name-dataset snapshot that produced the answer."
        },
        "request_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Identifier of this call, also sent as the `X-Request-Id` header. Quote it in support requests."
        }
      }
    },
    "GenderResult": {
      "type": "object",
      "required": [
        "query",
        "name",
        "gender",
        "probability",
        "sample_size",
        "source"
      ],
      "properties": {
        "query": {
          "type": "string",
          "description": "The input exactly as you sent it."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The first name actually looked up, after stripping titles and surnames."
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Given name parsed from the input. Present even when `gender` is null, and not charged separately. Titles and initials are never returned. For Chinese, Korean and Japanese script the surname comes first in the input and is returned in `last_name`."
        },
        "middle_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Any further given names between the first name and the surname, for example \"Fitzgerald\" in \"John Fitzgerald Kennedy\". Initials are dropped."
        },
        "last_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Surname parsed from the input, including particles such as \"van\" or \"de la\". \"Smith, John\" is read as surname first. With a Spanish-speaking `country` the last two words are both surnames (Pérez García). Always null for usernames, where a surname cannot be told apart from any other word."
        },
        "name_type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "personal",
            "organization",
            "role",
            null
          ],
          "description": "`organization` when the input carries a company marker (Acme LLC, Müller GmbH, Stanford University); `role` for shared mailboxes and placeholder accounts (info@, Customer Service, guest). Both return `gender: null` and no name parts. `personal` means no such marker was found; it does not confirm the input is a real name. null when the input is not a name at all."
        },
        "gender": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "male",
            "female",
            null
          ],
          "description": "null means the dataset has no confident answer. This is not an error."
        },
        "probability": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Share of people with this name who have the reported gender. 0 when unknown. Measured against held-out data, answers at 80+ come true about 95% of the time, so this number runs slightly conservative rather than optimistic."
        },
        "sample_size": {
          "type": "integer",
          "description": "How many real people the answer is based on. A probability of 100 from a sample of 3 is weaker than 85 from a sample of 90,000 — read the two fields together. 0 means the source recorded proportions rather than counts."
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "description": "The country the answer came from, when narrowed."
        },
        "took_ms": {
          "type": "integer",
          "description": "Whole milliseconds spent resolving this value on our side; network time is not included."
        },
        "source": {
          "type": "string",
          "enum": [
            "db",
            "script",
            "fuzzy",
            "llm",
            "cache",
            "none"
          ],
          "description": "How the answer was reached. `db` exact match; `script` matched after transliterating a non-Latin script; `fuzzy` closest spelling; `llm` language model; `none` no answer. Use it to decide how much to trust a row."
        },
        "confidence": {
          "type": "string",
          "enum": [
            "high",
            "medium",
            "low",
            "unverified",
            "unknown"
          ],
          "description": "Sample size bucket: high ≥100 people, medium ≥25, low ≥1, unverified when the source gave proportions instead of counts."
        },
        "matched_as": {
          "type": [
            "string",
            "null"
          ],
          "description": "For `fuzzy` and `script` sources, the dictionary entry that was actually matched. Always inspect this before accepting a fuzzy result."
        }
      }
    }
  }
}