# API v2 JSON responses and confidence

> Understand GenderAPI v2 data and meta fields: gender, unknown reasons, confidence, dataset evidence, AI scores, access mode and billing metadata.

Canonical HTML: https://www.genderapi.io/docs/v2/responses

Last reviewed: 2026-09-25

## Understand the JSON response

Successful single responses contain data and meta. The following dataset example is synthetic and illustrative; it does not represent measured product accuracy or promise the same result for a live request. It shows IP-trial access. Authenticated requests report access.mode: api_key and null trial-only quota fields.

| Field | Meaning |
| --- | --- |
| data.input | Input type, value and country. forceToGenderize is included when true. |
| data.name | Matched or extracted given name; null when none is available. |
| data.gender | male, female or JSON null. An inference, not verified personal identity. |
| data.result_status / reason | identified with a null reason, or unknown with not_found, no_name_candidate, ambiguous or insufficient_evidence. |
| data.confidence | 0–1 score or null. Null gender has null confidence. |
| data.confidence_kind | observed_frequency: dominant dataset count / total. model_reported: AI score, not a calibrated probability. Null when unavailable. |
| data.sample_count | Dataset sample size or null. AI does not invent a sample count. |
| data.source | dataset, ai or none. |
| data.country / country_source | Country association from dataset or ai_association, or null. Does not establish nationality, residence or ethnicity. |
| data.match | Matched dataset name, method (normalized, token, substring or model_inference), country/global scope and matched country. Unavailable evidence is null. |
| meta.request_id / duration_ms | Operation identifier and processing duration in milliseconds. |
| meta.access | How access was granted and the reason for trial fallback, if any. |
| meta.usage | Net charge, completion-time balance, billing status and trial reset information. |

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [Complete response schemas and batch examples](https://api.genderapi.io/api/v2/openapi.json)

## A successful unknown result

HTTP 200 means the operation completed; it does not guarantee a gender. Preserve JSON null rather than converting it to male, female, an empty string or zero confidence. Check data.result_status and data.reason separately from HTTP errors.

This synthetic dataset-only example returns source: none and reason: not_found and still costs 1 credit. A tied dataset row can return reason: ambiguous with its sample_count retained. An unknown AI result uses source: ai and reason: insufficient_evidence.

```json
{
  "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
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## Interpret confidence and matching evidence

A confidence of 0.9 is on a 0–1 scale. For observed_frequency it means the dominant count divided by the selected dataset total; it is not measured end-to-end product accuracy. A model_reported score is provided by AI and is not calibrated against dataset frequencies.

Choose any application threshold using your own evaluation data and confidence_kind. Do not directly rank dataset and AI scores as if they measured the same thing. AI match.name, match.scope and match.country are null because no dataset row was selected; match.method is model_inference.

For full names, a dataset result may come from a component rather than the full string. data.input preserves the submitted value; data.name describes the returned name, and data.match describes the candidate and lookup scope.

## Related guides

- [Batch response and per-item errors](https://www.genderapi.io/docs/v2/batch#batch-response)
- [Billing status and remaining credits](https://www.genderapi.io/docs/v2/credits-and-usage)
- [Response compatibility and retries](https://www.genderapi.io/docs/v2/errors-and-retries#retries)