BillionVerify Account API

openapi: 3.2.0
info:
  title: BillionVerify Account API
  description: 'BillionVerify provides a powerful email verification API for validating email addresses in real-time.


    ## Authentication


    All API endpoints require authentication using an API key. Include your API key in the request header:


    ```

    BILLIONVERIFY-API-KEY: your_api_key_here

    ```


    The following header names are all accepted, in priority order:

    - `BV-API-KEY` *(recommended)*

    - `BILLIONVERIFY-API-KEY`

    - `Authorization: Bearer {api_key}`


    ## Rate Limits


    | Endpoint | Rate Limit |

    |----------|------------|

    | Single Verification (`/verify/single`) | 6,000 requests/minute |

    | Batch Verification (`/verify/bulk`) | 1,500 requests/minute |

    | File Upload (`/verify/file`) | 300 requests/minute |

    | Other endpoints | 200 requests/minute |


    ## Credits & Billing


    - **Unknown** status: 0 credits (we could not reach a deterministic conclusion, so you are not charged)

    - All other statuses (valid, invalid, risky, disposable, catchall, role): 1 credit each


    `invalid` is a deterministic result — we confirmed the address is not deliverable (SMTP 550, missing MX, mailbox not found, etc.) — and is just as valuable for list cleaning as `valid`, so it is billed the same.


    `risky` is likewise deterministic: we completed the full SMTP check *and* found the recipient domain listed by an external blocklist. See `risk_reasons` on the result object.


    > **Changed 2026-08-04.** `risky` previously meant "we could not finish verifying" (an internal capacity fallback) and was not billed. That case is now returned as `unknown`, unchanged in behaviour and still free. `risky` now exclusively means "deliverable, but the domain has a confirmed abuse history — do not send", is billed 1 credit, and is never retryable. If your integration treats `risky` as "retry later", update it.


    ## Base URL


    Production: `https://api.billionverify.com`'
  version: 1.0.0
  contact:
    name: BillionVerify Support
    email: support@billionverify.com
    url: https://billionverify.com
  license:
    name: Proprietary
    url: https://billionverify.com/terms
servers:
- url: https://api.billionverify.com
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Account
  description: Account and credits management
paths:
  /v1/credits:
    get:
      tags:
      - Account
      summary: Get credit balance
      description: Get current credit balance and usage information for the authenticated account.
      operationId: getCreditBalance
      responses:
        '200':
          description: Credit balance retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                success: true
                code: '0'
                message: Success
                data:
                  account_id: abc123
                  api_key_id: key_xyz
                  api_key_name: Default API Key
                  credits_balance: 9500
                  credits_consumed: 500
                  credits_added: 10000
                  last_updated: '2026-02-04T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: '4010'
            message: Unauthorized
            error:
              code: INVALID_API_KEY
              message: API key is invalid or missing
  schemas:
    ErrorResponse:
      type: object
      description: 'Standard error response shape. Mirrors Go `response.StandardResponse`

        with Error populated. F23 (2026-05-09) replaced inline error object

        with `$ref ErrorInfo` so all typed wrappers + ErrorResponse share one

        canonical schema.

        '
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Top-level error code (mirrors Go StandardResponse.Code)
        message:
          type: string
          description: Top-level error message
        error:
          $ref: '#/components/schemas/ErrorInfo'
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        code:
          type: string
          description: Response code ("0" for success)
        message:
          type: string
          description: Human-readable message
        data:
          type: object
          description: Response data (varies by endpoint)
    ErrorInfo:
      type: object
      properties:
        code:
          type: string
          description: Detailed error code
        message:
          type: string
          description: Detailed error message
        description:
          type:
          - string
          - 'null'
          description: Additional human-readable context (omitempty in Go)
        details:
          description: Additional structured context (any type; usually map or string; omitempty in Go).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: BV-API-KEY
      description: 'API key for authentication. The following header names are accepted, in priority order:

        - `BV-API-KEY` (recommended)

        - `BILLIONVERIFY-API-KEY`

        - `Authorization: Bearer {api_key}`

        '