{
  "openapi": "3.1.0",
  "info": {
    "title": "GenderAPI Public API",
    "version": "1.0.0",
    "summary": "Gender inference and phone validation endpoints.",
    "description": "API-owner-approved contract derived from the public English documentation and verified backend handlers. Gender values are probabilistic inferences, not verified identity. Publication remains controlled by the separate GEO release gate.",
    "termsOfService": "https://www.genderapi.io/terms",
    "contact": {
      "url": "https://www.genderapi.io/contact"
    }
  },
  "x-lifecycle-policy": {
    "approvedAt": "2026-09-15",
    "canonicalTransport": "Bearer authentication on POST operations; query-key on documented GET compatibility operations.",
    "compatibility": "Existing legacy GET, authentication transports, JSONP or alternate response shapes, HTTP error mappings, and errno values remain operational until measured, announced, and migrated.",
    "breakingChange": "Removing or changing an accepted request transport, operation, response shape, field type, HTTP/application-error mapping, or errno value is a breaking change.",
    "minimumNoticeMonths": 6,
    "criticalEnterpriseNoticeMonths": 12,
    "noticeChannels": [
      "developer documentation",
      "account email"
    ],
    "sunsetSignaling": [
      "documentation deprecation notice",
      "Sunset HTTP header where technically applicable"
    ]
  },
  "servers": [
    {
      "url": "https://api.genderapi.io",
      "description": "Production API"
    }
  ],
  "tags": [
    {
      "name": "Gender inference"
    },
    {
      "name": "Phone"
    },
    {
      "name": "Quota"
    }
  ],
  "paths": {
    "/api": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromName",
        "summary": "Infer gender from one name",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-name-single",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-name-single",
        "x-credit-cost": "One lookup; AI fallback may have different usage accounting. Confirm current terms.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                    "examples": [
                      "US"
                    ]
                  },
                  "askToAI": {
                    "type": "boolean",
                    "default": false
                  }
                }
              },
              "example": {
                "name": "Alice",
                "country": "US",
                "askToAI": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SingleLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "q": "Alice",
                  "name": "Alice",
                  "gender": "female",
                  "country": "US",
                  "total_names": 10234,
                  "probability": 98,
                  "duration": "4ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/name/multi/country": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromNames",
        "summary": "Infer gender from multiple names",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-name-multiple",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-name-multiple",
        "x-credit-cost": "Credits are consumed per processed record, not per HTTP request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "name"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "country": {
                          "type": "string",
                          "pattern": "^[A-Z]{2}$",
                          "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                          "examples": [
                            "US"
                          ]
                        },
                        "id": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "integer"
                            }
                          ],
                          "description": "Caller record identifier."
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "data": [
                  {
                    "name": "Andrea",
                    "country": "DE",
                    "id": "123"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BatchLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "names": [
                    {
                      "q": "Andrea",
                      "name": "andrea",
                      "gender": "female",
                      "country": "US",
                      "total_names": 1234,
                      "probability": 92,
                      "id": "123"
                    }
                  ],
                  "duration": "5ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-live-verification": {
          "observedAt": "2026-09-14",
          "result": "A 200-record request returned all 200 results with used_credits 200. A 201-record request returned HTTP 200 with status false and errno 92.",
          "partialProcessing": "A mixed request containing one valid record and one record without the required name returned status true, one result, and used_credits 1. An empty-string name was processed and returned gender \"null\"."
        }
      }
    },
    "/api/email": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromEmail",
        "summary": "Extract a name and infer gender from one email address",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-email-single",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-email-single",
        "x-credit-cost": "One lookup; AI fallback may have different usage accounting. Confirm current terms.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "minLength": 1
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                    "examples": [
                      "US"
                    ]
                  },
                  "askToAI": {
                    "type": "boolean",
                    "default": false
                  }
                }
              },
              "example": {
                "email": "alice.smith@example.com",
                "country": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SingleLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "q": "alice.smith@example.com",
                  "name": "Alice",
                  "gender": "female",
                  "country": "US",
                  "total_names": 10234,
                  "probability": 98,
                  "duration": "4ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/email/multi/country": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromEmails",
        "summary": "Extract names and infer gender from multiple email addresses",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-email-multiple",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-email-multiple",
        "x-credit-cost": "Credits are consumed per processed record, not per HTTP request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "email"
                      ],
                      "properties": {
                        "email": {
                          "type": "string",
                          "minLength": 1
                        },
                        "country": {
                          "type": "string",
                          "pattern": "^[A-Z]{2}$",
                          "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                          "examples": [
                            "US"
                          ]
                        },
                        "id": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "integer"
                            }
                          ],
                          "description": "Caller record identifier."
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "data": [
                  {
                    "email": "anna.smith@example.com",
                    "country": "US",
                    "id": "123"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BatchLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "names": [
                    {
                      "q": "anna.smith@example.com",
                      "name": "Anna",
                      "gender": "female",
                      "country": "US",
                      "total_names": 1234,
                      "probability": 92,
                      "id": "123"
                    }
                  ],
                  "duration": "5ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/username": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromUsername",
        "summary": "Extract a name and infer gender from one username",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-username-single",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-username-single",
        "x-credit-cost": "One lookup; AI options may have different usage accounting. Confirm current terms.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "username"
                ],
                "properties": {
                  "username": {
                    "type": "string",
                    "minLength": 1
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                    "examples": [
                      "US"
                    ]
                  },
                  "askToAI": {
                    "type": "boolean",
                    "default": false
                  },
                  "forceToGenderize": {
                    "type": "boolean",
                    "default": false
                  }
                }
              },
              "example": {
                "username": "anna_smith88",
                "country": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SingleLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "q": "anna_smith88",
                  "name": "Anna",
                  "gender": "female",
                  "country": "US",
                  "total_names": 10234,
                  "probability": 98,
                  "duration": "4ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/username/multi/country": {
      "post": {
        "tags": [
          "Gender inference"
        ],
        "operationId": "inferGenderFromUsernames",
        "summary": "Extract names and infer gender from multiple usernames",
        "description": "Canonical documentation: https://www.genderapi.io/docs-gender-from-username-multiple",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-gender-from-username-multiple",
        "x-credit-cost": "Credits are consumed per processed record, not per HTTP request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "data"
                ],
                "properties": {
                  "data": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "username"
                      ],
                      "properties": {
                        "username": {
                          "type": "string",
                          "minLength": 1
                        },
                        "country": {
                          "type": "string",
                          "pattern": "^[A-Z]{2}$",
                          "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                          "examples": [
                            "US"
                          ]
                        },
                        "id": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "integer"
                            }
                          ],
                          "description": "Caller record identifier."
                        }
                      }
                    }
                  }
                }
              },
              "example": {
                "data": [
                  {
                    "username": "anna_smith88",
                    "country": "US",
                    "id": "123"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/BatchLookupResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "used_credits": 1,
                  "remaining_credits": 4999,
                  "expires": 1743659200,
                  "names": [
                    {
                      "q": "anna_smith88",
                      "name": "Anna",
                      "gender": "female",
                      "country": "US",
                      "total_names": 1234,
                      "probability": 92,
                      "id": "123"
                    }
                  ],
                  "duration": "5ms"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/remaining": {
      "get": {
        "tags": [
          "Quota"
        ],
        "operationId": "getRemainingQuota",
        "summary": "Retrieve remaining quota and expiration",
        "description": "This endpoint requires the key query parameter. Keep the request server-side and redact the full URL and query string from logs; Bearer authentication was rejected with errno 94 during live verification.",
        "security": [
          {
            "apiKeyQuery": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-usage-and-quota",
        "x-credit-cost": "Does not perform a gender lookup.",
        "responses": {
          "200": {
            "description": "Quota information",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/QuotaResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "remaining": 9443,
                  "expiresAt": 1752651601
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/phone": {
      "get": {
        "tags": [
          "Phone"
        ],
        "operationId": "validatePhoneWithQuery",
        "summary": "Validate and format a phone number using query parameters",
        "description": "POST with Bearer authentication is preferred for secret handling.",
        "security": [
          {
            "apiKeyQuery": []
          }
        ],
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-phone-validation-formatter-api",
        "x-credit-cost": "Confirm current usage accounting in account and pricing documentation.",
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PhoneResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "remaining_credits": 15709,
                  "expires": 0,
                  "duration": "18ms",
                  "regionCode": "US",
                  "countryCode": 1,
                  "country": "United States",
                  "national": "(212) 867-5309",
                  "international": "+1 212-867-5309",
                  "e164": "+12128675309",
                  "isValid": true,
                  "isPossible": true,
                  "numberType": "FIXED_LINE_OR_MOBILE"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Phone"
        ],
        "operationId": "validatePhone",
        "summary": "Validate and format a phone number",
        "description": "Canonical documentation: https://www.genderapi.io/docs-phone-validation-formatter-api",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-documentation-url": "https://www.genderapi.io/docs-phone-validation-formatter-api",
        "x-credit-cost": "Confirm current usage accounting in account and pricing documentation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "number"
                ],
                "properties": {
                  "number": {
                    "type": "string",
                    "minLength": 1
                  },
                  "address": {
                    "type": "string"
                  }
                }
              },
              "example": {
                "number": "+1 212 867 5309",
                "address": "US"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/PhoneResponse"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "status": true,
                  "remaining_credits": 15709,
                  "expires": 0,
                  "duration": "18ms",
                  "e164": "+12128675309",
                  "isValid": true
                }
              }
            }
          },
          "400": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected. Branch on errno rather than errmsg text.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Recommended server-side API-key transport."
      },
      "apiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "key",
        "description": "Supported by documented GET endpoints; keep requests server-side."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status",
          "errno",
          "errmsg"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "const": false
          },
          "errno": {
            "type": "integer",
            "enum": [
              50,
              90,
              91,
              92,
              93,
              94,
              99
            ]
          },
          "errmsg": {
            "type": "string"
          }
        },
        "example": {
          "status": false,
          "errno": 94,
          "errmsg": "invalid or missing key"
        },
        "x-error-catalog": [
          {
            "errno": 50,
            "message": "access denied",
            "action": "Review API-key IP or referrer restrictions."
          },
          {
            "errno": 90,
            "message": "invalid country code",
            "action": "Validate an ISO 3166-1 alpha-2 country code."
          },
          {
            "errno": 91,
            "message": "required input not set",
            "action": "Add the endpoint's required name, email, or username."
          },
          {
            "errno": 92,
            "message": "batch limit exceeded",
            "action": "Split input according to the documented endpoint limit."
          },
          {
            "errno": 93,
            "message": "query limit reached",
            "action": "Pause lookups and review the account quota."
          },
          {
            "errno": 94,
            "message": "invalid or missing key",
            "action": "Check server-side credential injection."
          },
          {
            "errno": 99,
            "message": "API key has expired",
            "action": "Review or renew the package before retrying."
          }
        ]
      },
      "SingleLookupResponse": {
        "allOf": [
          {
            "type": "object",
            "required": [
              "status"
            ],
            "properties": {
              "status": {
                "type": "boolean",
                "const": true
              },
              "used_credits": {
                "type": "integer",
                "minimum": 0,
                "description": "Credits consumed for processed records."
              },
              "remaining_credits": {
                "type": "integer",
                "minimum": 0
              },
              "expires": {
                "type": "integer",
                "description": "Package expiration as a UNIX timestamp."
              },
              "duration": {
                "type": "string",
                "examples": [
                  "4ms"
                ]
              }
            }
          },
          {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "q": {
                "type": "string",
                "description": "Original submitted value."
              },
              "gender": {
                "type": "string",
                "enum": [
                  "male",
                  "female",
                  "null"
                ],
                "description": "Probabilistic result. An unresolved input is returned as the literal string \"null\", not JSON null."
              },
              "country": {
                "type": "string",
                "pattern": "^[A-Z]{2}$",
                "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                "examples": [
                  "US"
                ]
              },
              "total_names": {
                "type": "integer",
                "minimum": 0
              },
              "probability": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "id": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "integer"
                  }
                ],
                "description": "Caller record identifier."
              }
            }
          }
        ]
      },
      "BatchLookupResponse": {
        "type": "object",
        "required": [
          "status",
          "names"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "const": true
          },
          "used_credits": {
            "type": "integer",
            "minimum": 0,
            "description": "Credits consumed for processed records."
          },
          "remaining_credits": {
            "type": "integer",
            "minimum": 0
          },
          "expires": {
            "type": "integer",
            "description": "Package expiration as a UNIX timestamp."
          },
          "duration": {
            "type": "string",
            "examples": [
              "4ms"
            ]
          },
          "names": {
            "type": "array",
            "description": "Contains a result for every processed input, including unresolved results with gender \"null\". Live verification observed that a malformed entry missing the required name was omitted while valid entries were processed.",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "q": {
                  "type": "string",
                  "description": "Original submitted value."
                },
                "gender": {
                  "type": "string",
                  "enum": [
                    "male",
                    "female",
                    "null"
                  ],
                  "description": "Probabilistic result. An unresolved input is returned as the literal string \"null\", not JSON null."
                },
                "country": {
                  "type": "string",
                  "pattern": "^[A-Z]{2}$",
                  "description": "ISO 3166-1 alpha-2 country code used as regional context.",
                  "examples": [
                    "US"
                  ]
                },
                "total_names": {
                  "type": "integer",
                  "minimum": 0
                },
                "probability": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 100
                },
                "id": {
                  "oneOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer"
                    }
                  ],
                  "description": "Caller record identifier."
                }
              }
            }
          }
        }
      },
      "QuotaResponse": {
        "type": "object",
        "required": [
          "status",
          "remaining",
          "expiresAt"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "const": true
          },
          "remaining": {
            "type": "integer",
            "minimum": 0
          },
          "expiresAt": {
            "type": "integer",
            "description": "Expiration as a UNIX timestamp."
          }
        }
      },
      "PhoneResponse": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "boolean",
            "const": true
          },
          "remaining_credits": {
            "type": "integer",
            "minimum": 0
          },
          "expires": {
            "type": "integer"
          },
          "duration": {
            "type": "string"
          },
          "regionCode": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "ISO 3166-1 alpha-2 country code used as regional context.",
            "examples": [
              "US"
            ]
          },
          "countryCode": {
            "type": "integer"
          },
          "country": {
            "type": "string"
          },
          "national": {
            "type": "string"
          },
          "international": {
            "type": "string"
          },
          "e164": {
            "type": "string"
          },
          "isValid": {
            "type": "boolean"
          },
          "isPossible": {
            "type": "boolean"
          },
          "numberType": {
            "type": "string",
            "enum": [
              "FIXED_LINE",
              "MOBILE",
              "FIXED_LINE_OR_MOBILE",
              "TOLL_FREE",
              "PREMIUM_RATE",
              "SHARED_COST",
              "VOIP",
              "PERSONAL_NUMBER",
              "PAGER",
              "UAN",
              "VOICEMAIL",
              "UNKNOWN"
            ]
          },
          "nationalSignificantNumber": {
            "type": "string"
          },
          "rawInput": {
            "type": "string"
          },
          "isGeographical": {
            "type": "boolean"
          },
          "areaCode": {
            "type": "string"
          },
          "location": {
            "type": "string"
          }
        }
      }
    }
  }
}