GET /person — Name Generation API

Authentication

Every request must include a valid API key in the X-APIKEY header. Missing or invalid keys receive 403 Forbidden.

Query parameters

Parameter	Required	Notes
`country`	Yes	Two-letter country code, case-insensitive (e.g. `ZA`, `za`).
`gender`	Yes	`male` or `female`.
`count`	No	Whole number 1–100. Defaults to 1.

Example request

GET /person?country=ZA&gender=female&count=2
X-APIKEY: your-api-key

Example response (200 OK)

{
  "success": true,
  "countryCode": "ZA",
  "gender": "female",
  "count": 2,
  "people": [
    {
      "countryCode": "ZA",
      "gender": "female",
      "firstName": {
        "original": "Thandiwe",
        "normalized": "Thandiwe"
      },
      "surname": {
        "original": "Mthembu",
        "normalized": "Mthembu"
      },
      "fullName": {
        "original": "Thandiwe Mthembu",
        "normalized": "Thandiwe Mthembu"
      }
    },
    {
      "countryCode": "ZA",
      "gender": "female",
      "firstName": {
        "original": "Naledi",
        "normalized": "Naledi"
      },
      "surname": {
        "original": "van der Merwe",
        "normalized": "van der Merwe"
      },
      "fullName": {
        "original": "Naledi van der Merwe",
        "normalized": "Naledi van der Merwe"
      }
    }
  ]
}

Error responses

Status	Code	Reason
`403`	`FORBIDDEN`	Missing or invalid API key.
`400`	`INVALID_COUNTRY`	Missing or invalid country code.
`400`	`INVALID_GENDER`	Gender is not `male` or `female`.
`400`	`INVALID_COUNT`	Count is not a whole number between 1 and 100.
`404`	`NO_NAME_DATA`	No name data available for the country and gender.
`500`	`INTERNAL_ERROR`	Unexpected server error.