ClearBounce API

openapi: 3.1.0
info:
  title: ClearBounce API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 15 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; ClearBounce has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 7
    documentation: 8
    pages-with-code: 9
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://clearbounce.net/email-verification-api
  - https://docs.clearbounce.net/api-reference/errors
  - https://docs.clearbounce.net/api-reference/credits
  - https://docs.clearbounce.net/api-reference/overview
  - https://docs.clearbounce.net/api-reference/email-finder
  - https://docs.clearbounce.net/api-reference/authentication
  - https://docs.clearbounce.net/api-reference/batch-verification
  - https://docs.clearbounce.net/api-reference/single-verification
  - https://clearbounce.net/audiences/developers
  - https://api.clearbounce.net
paths:
  /api-keys:
    get:
      operationId: get_api_keys
      tags:
      - Api Keys
      summary: List your API keys
      x-source: https://docs.clearbounce.net/api-reference/overview
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiKeysResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_keys
      tags:
      - Api Keys
      summary: Create a new API key
      x-source: https://docs.clearbounce.net/api-reference/overview
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiKeysResponse'
      x-evidence:
        kind: documentation
  /api-keys/{id}:
    delete:
      operationId: delete_api_keys_id
      tags:
      - Api Keys
      summary: Delete an API key
      x-source: https://docs.clearbounce.net/api-reference/overview
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiKeysIdResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_api_keys_id
      tags:
      - Api Keys
      summary: Update an API key
      x-source: https://docs.clearbounce.net/api-reference/overview
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchApiKeysIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/api-keys:
    get:
      operationId: get_api_v1_api_keys
      tags:
      - Api
      summary: GET /api/v1/api-keys
      x-source: https://docs.clearbounce.net/api-reference/authentication
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.clearbounce.net/api/v1/api-keys \\ -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \n Delete a Key ​ "
    post:
      operationId: post_api_v1_api_keys
      tags:
      - Api
      summary: POST /api/v1/api-keys
      x-source: https://docs.clearbounce.net/api-reference/authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1ApiKeysRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.clearbounce.net/api/v1/api-keys \\ -H \"Content-Type: application/json\" \\ -H \"Authorization: Bearer\
          \ YOUR_JWT_TOKEN\" \\ -d '{\"name\": \"Production App\"}' \n List Your Keys ​ "
  /api/v1/api-keys/{keyid}:
    delete:
      operationId: delete_api_v1_api_keys_keyid
      tags:
      - Api
      summary: DELETE /api/v1/api-keys/{keyId}
      x-source: https://docs.clearbounce.net/api-reference/authentication
      parameters:
      - name: keyid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X DELETE https://api.clearbounce.net/api/v1/api-keys/KEY_ID \\ -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \n API Key\
          \ Management API key management endpoints require JWT authentication (login token), not API key authentication. This is for security\
          \ - you manage keys through the dashboard. \n Security Best Practices ​ \n 1. Keep Keys Secret ​ \n Never expose your API key in: \n\
          \ Client-side JavaScript"
  /api/v1/bulk/upload:
    post:
      operationId: post_api_v1_bulk_upload
      tags:
      - Api
      summary: POST /api/v1/bulk/upload
      x-source: https://docs.clearbounce.net/api-reference/batch-verification
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1BulkUploadResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: 'fetch ( ''https://api.clearbounce.net/api/v1/bulk/upload'' , { method : ''POST'' , headers : { ''Content-Type'' : ''application/json''
          , ''X-API-Key'' : process . env . CLEARBOUNCE_API_KEY } , body : JSON . stringify ( { emails : [ ''user1@example.com'' , ''user2@example.com''
          , ''user3@example.com'' ] } )'
  /api/v1/credits:
    get:
      operationId: get_api_v1_credits
      tags:
      - Api
      summary: GET /api/v1/credits
      x-source: https://docs.clearbounce.net/api-reference/credits
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1CreditsResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.clearbounce.net/api/v1/credits \\ -H \"X-API-Key: YOUR_API_KEY\" \n const response = await fetch ( 'https://api.clearbounce.net/api/v1/credits'\
          \ , { headers : { 'X-API-Key' : 'YOUR_API_KEY' } } ) ; const {credits} = await response . json ( ) ; console . log ( ` Credits left:\
          \ ${credits} ` ) ; Previous Batch Verification Next Email Finder Endpoint Request Headers Response Success Respons"
  /api/v1/finder/person:
    post:
      operationId: post_api_v1_finder_person
      tags:
      - Api
      summary: POST /api/v1/finder/person
      x-source: https://docs.clearbounce.net/api-reference/email-finder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1FinderPersonRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.clearbounce.net/api/v1/finder/person \\ -H \"Content-Type: application/json\" \\ -H \"X-API-Key: YOUR_API_KEY\"\
          \ \\ -d '{\"name\": \"Jane Porter\", \"domain\": \"northwindtraders.com\"}' \n Find, then verify ​ \n const headers = { 'Content-Type'\
          \ : 'application/json' , 'X-API-Key' : 'YOUR_API_KEY' } ; const found = await fetch ( 'https://api.clearbounce.net/api/v1/finder/person'\
          \ , { method :"
  /api/v1/verify:
    post:
      operationId: post_api_v1_verify
      tags:
      - Api
      summary: POST /api/v1/verify
      x-source: https://clearbounce.net/email-verification-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1VerifyRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1VerifyResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://clearbounce.net/api/v1/verify  -H \"X-API-Key: your_api_key\"  -H \"Content-Type: application/json\"  -d\
          \ '{\"email\": \"test@example.com\"}' \n Python \n import requests\nresponse = requests.post(\n 'https://clearbounce.net/api/v1/verify'\
          \ ,\n headers={ 'X-API-Key' : 'your_api_key' },\n json={ 'email' : 'test@example.com' }\n)\n print (response.json()) \n Start Building\
          \ Today \n Get your API key"
  /bulk/results/{jobid}:
    get:
      operationId: get_bulk_results_jobid
      tags:
      - Bulk
      summary: Download verification results
      x-source: https://docs.clearbounce.net/api-reference/overview
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkResultsJobidResponse'
      x-evidence:
        kind: documentation
  /bulk/status/{jobid}:
    get:
      operationId: get_bulk_status_jobid
      tags:
      - Bulk
      summary: Get job status and progress
      x-source: https://docs.clearbounce.net/api-reference/overview
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBulkStatusJobidResponse'
      x-evidence:
        kind: documentation
  /bulk/upload:
    post:
      operationId: post_bulk_upload
      tags:
      - Bulk
      summary: Upload emails for batch verification
      x-source: https://docs.clearbounce.net/api-reference/overview
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBulkUploadResponse'
      x-evidence:
        kind: documentation
  /verify:
    post:
      operationId: post_verify
      tags:
      - Verify
      summary: Verify a single email address
      x-source: https://docs.clearbounce.net/api-reference/overview
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostVerifyResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiKeysResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: List of API keys
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    PostApiKeysResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Details of the newly created API key
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    DeleteApiKeysIdResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Result of the delete operation
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    PatchApiKeysIdResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Updated API key information
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    PostApiV1ApiKeysRequest:
      type: object
      properties:
        name:
          type: string
    PostApiV1BulkUploadResponse:
      type: object
      properties:
        success:
          type: boolean
        job:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
            progress:
              type: integer
            totalEmails:
              type: integer
            processedEmails:
              type: integer
            deliverableCount:
              type: integer
            undeliverableCount:
              type: integer
            riskyCount:
              type: integer
            unknownCount:
              type: integer
            catchAllCount:
              type: integer
            createdAt:
              type: string
              format: date-time
            completedAt:
              type:
              - string
              - 'null'
            bounceEstimate:
              type:
              - string
              - 'null'
    GetApiV1CreditsResponse:
      type: object
      properties:
        headers:
          type: object
          properties:
            X-API-Key:
              type: string
    PostApiV1FinderPersonRequest:
      type: object
      properties:
        name:
          type: string
        domain:
          type: string
    PostApiV1VerifyRequest:
      type: object
      properties:
        email:
          type: string
    PostApiV1VerifyResponse:
      type: object
      properties:
        X-API-Key:
          type: string
    GetBulkResultsJobidResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Verification results for the job
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    GetBulkStatusJobidResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Status and progress details of the job
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    PostBulkUploadResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Information about the uploaded job
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
    PostVerifyResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        data:
          type: object
          description: Result data for the verification
        creditsRemaining:
          type: integer
          description: Remaining credits after the request
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
security:
- apiKey: []
tags:
- name: Api
- name: Api Keys
- name: Bulk
- name: Verify