openapi: 3.2.0
info:
  title: GenderAPI Public Phone 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
servers:
- url: https://api.genderapi.io
  description: Production API
tags:
- name: Phone
paths:
  /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:
  schemas:
    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
    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.
  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.
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