POST /country/:countryCode/names — Name Generation API

Authentication

Requires a valid X-APIKEY header. The key must have upload permission. Keys without upload permission receive 403 Forbidden.

URL parameter

Parameter	Notes
`:countryCode`	Two-letter country code for an existing country (e.g. `ZA`). Must already exist in the database.

Request body

{
  "male": {
    "mode": "add",
    "names": [
      "Sipho",
      "Themba"
    ]
  },
  "female": {
    "mode": "replace",
    "names": [
      "Naledi",
      "Thandiwe"
    ]
  },
  "surnames": {
    "mode": "add",
    "names": [
      "Mthembu",
      "Ndlovu"
    ]
  }
}

Each collection requires a mode ("add" or "replace") and a names array. Collections are processed independently.

Upload modes

Mode	Behaviour
`add`	Keeps existing names. Inserts new names not already present. Empty list makes no changes.
`replace`	Deletes all existing names for that category, then inserts the supplied list. An empty list clears the category.

Example response (200 OK)

{
  "success": true,
  "countryCode": "ZA",
  "male": {
    "mode": "add",
    "submitted": 2,
    "inserted": 2,
    "duplicates": 0,
    "rejected": 0,
    "removed": 0,
    "rejectedNames": []
  },
  "female": {
    "mode": "replace",
    "submitted": 2,
    "inserted": 2,
    "duplicates": 0,
    "rejected": 0,
    "removed": 50,
    "rejectedNames": []
  },
  "surnames": {
    "mode": "add",
    "submitted": 2,
    "inserted": 1,
    "duplicates": 0,
    "rejected": 1,
    "removed": 0,
    "rejectedNames": [
      {
        "value": "",
        "reason": "EMPTY_NAME"
      }
    ]
  }
}

Name rejection reasons

Reason	Description
`EMPTY_NAME`	Name is empty or contains only whitespace.
`INVALID_TYPE`	Name value is not a string.
`NAME_TOO_LONG`	Name exceeds 255 characters.
`UNSUPPORTED_CHARACTERS`	Name contains non-Latin characters.

Error responses

Status	Code	Reason
`403`	`FORBIDDEN`	Missing, invalid, or insufficiently-permissioned API key.
`400`	`INVALID_COUNTRY`	Country code not found in database.
`400`	`INVALID_REQUEST`	Malformed body, missing collection, or invalid mode.
`500`	`INTERNAL_ERROR`	Unexpected server error. All changes rolled back.