{
  "info": {
    "name": "ByeBouncer API · independent validation services",
    "description": "API v1 and SDK 0.4.0. Email, IP and three independent phone validation levels. Use your own API key. Requests can consume credits; examples are illustrative. Keep importId stable when retrying the same batch.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.byebouncer.com",
      "type": "string"
    },
    {
      "key": "apiKey",
      "value": "bb_live_replace_me",
      "type": "secret"
    },
    {
      "key": "domain",
      "value": "example.com",
      "type": "string"
    },
    {
      "key": "ip",
      "value": "8.8.8.8",
      "type": "string"
    },
    {
      "key": "selector",
      "value": "replace-with-dkim-selector",
      "type": "string"
    },
    {
      "key": "jobId",
      "value": "replace-with-job-id",
      "type": "string"
    },
    {
      "key": "importId",
      "value": "replace-with-unique-import-id",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "System",
      "item": [
        {
          "name": "GET /api/v1/health",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/health",
            "description": "Public, 300 requests/minute per IP. Checks PostgreSQL, Redis, active bulk processing, IP dataset freshness and the phone provider circuit when configured.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/status",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/status",
            "description": "Public. Reports service status and dependencies.",
            "auth": {
              "type": "noauth"
            }
          }
        }
      ]
    },
    {
      "name": "Free tools",
      "item": [
        {
          "name": "POST /api/v1/suggest",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/suggest",
            "description": "Public, 20 requests/minute per IP. Uses local typo detection without DNS or SMTP. Invalid syntax returns has_suggestion false.",
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "GET /api/v1/domain/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/domain/{{domain}}",
            "description": "Public, 30 requests/minute per IP. With metadata_only=1 returns cached/background SPF, DMARC and registration-age observations without MX/SMTP or credits. Pending observations do not imply an invalid mailbox. Otherwise DNS transient errors return 503 dns_temporarily_unavailable.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "POST /api/v1/demo/verify",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/demo/verify",
            "description": "Public, 5 requests/hour and 20 requests/24 hours per IP. Does not debit credits.",
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/tools/syntax",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/tools/syntax",
            "description": "Public. Shares a 20 requests/hour budget per IP with the domain tools.",
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/tools/disposable",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/tools/disposable",
            "description": "Public. Shares a 20 requests/hour budget per IP with the syntax and domain tools.",
            "auth": {
              "type": "noauth"
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "GET /api/v1/tools/mx/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/mx/{{domain}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/spf/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/spf/{{domain}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/dmarc/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/dmarc/{{domain}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/dkim/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/dkim/{{domain}}?selector={{selector}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/blacklist/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/blacklist/{{domain}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/whois/{domain}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/whois/{{domain}}",
            "description": "Public. Shares the 20 requests/hour budget per IP for domain tools.",
            "auth": {
              "type": "noauth"
            }
          }
        },
        {
          "name": "GET /api/v1/tools/ip/{ip}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/tools/ip/{{ip}}",
            "description": "Public, unauthenticated, rate-limited by visitor IP (20/hour). Returns a\nreduced view (no per-signal breakdown or listed_on detail).\n",
            "auth": {
              "type": "noauth"
            }
          }
        }
      ]
    },
    {
      "name": "Account",
      "item": [
        {
          "name": "POST /api/v1/credits/checkout",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/credits/checkout",
            "description": "Live keys only, 10 requests/minute per key. Requires acceptance of the\ncurrent terms in the purchase page. Redirect to the returned Polar checkout_url.\ntransaction_id is retained as an alias of checkout_id for compatibility.\nCredits reach the shared wallet only after the verified\npayment completion webhook; existing key allocations do not increase automatically.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"pack\": \"S\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "GET /api/v1/credits",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/credits",
            "description": "Returns the spendable balance of the authenticated API key (remaining allocation when assigned), and the total shared account balance as wallet_balance when available."
          }
        }
      ]
    },
    {
      "name": "Verification",
      "item": [
        {
          "name": "POST /api/v1/verify",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify?result_format=validation-v1",
            "description": "Runs the full verification pipeline (syntax → DNS/MX → domain intel → SMTP)\nand returns a verdict. Consumes 1 credit per verification, including cache hits.\nA refusal by our local SMTP domain budget returns 429\n`smtp_domain_rate_limited` with `Retry-After: 60` and consumes no credit.\nThis compatibility error also covers local hosting-family limits,\npauses and unavailable controls; optional `reason` gives the specific\ncause. A local refusal never proves mailbox invalidity.\nA completed inconclusive verification (for example a catch-all) still\nfollows the normal billing policy. Retry 429 responses with backoff;\nprefer bulk for lists containing many addresses at the same domain.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-email",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-email?result_format=validation-v1",
            "description": "Dedicated email endpoint, so each service can be requested on its own.\nBehaves exactly like `/verify`: it runs the full email pipeline\n(syntax → DNS/MX → domain intel → SMTP) and consumes 1 credit per\nverification, including cache hits. `/verify` stays as a\nbackward-compatible alias with identical behavior.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-ip",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-ip?result_format=validation-v1",
            "description": "Classifies an IPv4/IPv6 address (RFC 6890), enriches it with ASN, org and\ncountry, checks DNSBLs + FCrDNS + Tor, and returns an explainable risk\nscore. Consumes 1 credit for public IPs; non-routable IPs (status\n`invalid_scope`) are not charged.\nThis route is registered only when the IP datasets are loaded; otherwise 404.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"ip\": \"8.8.8.8\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-phone",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-phone?result_format=validation-v1",
            "description": "Performs numbering-plan validation and, when carrier enrichment\nis configured, carrier enrichment and lead-quality scoring.\nLocal valid results consume 1 credit; conclusive carrier-enriched\nresults consume 3 credits, including cache hits. Invalid, possible,\nunknown, provider-unavailable, and customer-blacklisted numbers\ndo not consume credits. A blacklisted L1 result includes `verdict: no`\nand the `blacklisted` flag; numbering-plan validity is unchanged.\n\nSend `live: true` to also get the last network status of the line\n(see `PhoneLiveAddOn`); that part is billed separately.\nThe route is registered only when phone validation is enabled; otherwise 404.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-phone/local",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-phone/local?result_format=validation-v1",
            "description": "Local-only numbering-plan validation: format, country and estimated line\ntype, with no carrier or network lookup. It always uses the local engine,\neven when carrier enrichment is configured, so it never silently upgrades\nto the 3-credit product. A valid result consumes 1 credit, including cache\nhits; invalid, possible, unknown and blacklisted numbers are free.\n`live: true` is rejected with 400 — use `/verify-phone/live` for the\nnetwork status. The route is registered only when phone validation is\nenabled; otherwise 404.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-phone/carrier",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-phone/carrier?result_format=validation-v1",
            "description": "Carrier data lookup, including the local numbering-plan validation: it\nreturns the operator information when available. Conclusive results\nconsume 3 credits in total (not 1 + 3), including cache hits; invalid,\npossible, unknown, provider-unavailable and blacklisted numbers are free.\nUnlike `/verify-phone`, this route never falls back to the local-only\nproduct: when carrier enrichment is not configured it returns 503\n`phone_carrier_unavailable`. Send `live: true` to also add the last\nnetwork status, billed separately (see `/verify-phone/live`).\nThe route is registered only when phone validation is enabled; otherwise 404.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/verify-phone/live",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/verify-phone/live?result_format=validation-v1",
            "description": "Asks the mobile network (HLR) whether the line is registered and\nreachable at lookup time, so you can decide whether to call a lead right\naway. Available only when the server enables it (`PHONE_HLR_ENABLED`) and\nonly for **live** API keys. Public keys receive `403 live_key_required`.\nWhen disabled, the dedicated route is not registered (404); a composite\nrequest instead returns `live_error: phone_live_unavailable`.\n\n`contactability` is the plain-language answer:\n`yes` (connected at checked_at), `retry_later` (device off or out of coverage, a\nreal line), `unverifiable` (fixed line or VoIP, HLR does not apply) and\n`no` (invalid, unknown to the network, or on your blacklist).\n\"Connected\" means registered on the network at checked_at; it does not guarantee\nthe person will answer.\n\n**Latency:** it queries the operator network, so expect a few seconds.\nDo not put it in the path of a form while the user types; call it from\nyour backend once you have the lead.\n\n**Billing:** it costs 6 credits for\nevery conclusive answer from the network (`connected`, `absent`,\n`unknown`), cache hits included. Invalid numbers, fixed lines, VoIP,\nblacklisted numbers and provider failures are free. Results are cached\nfor 30 seconds by default (`cached: true`, see `checked_at`) to serve retries\nfaster, but the cache does not discount the lookup. The\noriginal provider fields, including subscriber identifiers when supplied, are archived privately and returned to the authorized caller in `provider_data`.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/lead/verify",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/lead/verify?result_format=validation-v1",
            "description": "Composite endpoint: runs the email, IP and phone checks in parallel and\nreturns a combined `verdict` (`accept` / `review` / `reject` / `unknown`)\nplus the per-channel results. Supply any subset of `email`, `ip` and\n`phone`; at least one is required. Each channel bills independently with\nthe same policy as its dedicated endpoint (email bills on every completed\nverification; local `smtp_domain_rate_limited` errors do not charge that channel; IP\nbills when publicly routable, phone bills per the service policy), so a\nfull three-channel call can consume up to 5 credits with carrier enrichment or\n3 with local phone validation; optional HLR adds up to 6 more credits.\n`credits_remaining`\nreflects the balance after every channel settled.\nHTTP 200 can include per-channel `error` values; inspect each supplied\nchannel even when other channels succeeded and were charged.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"person@example.com\",\n  \"phone\": \"+12025550123\",\n  \"phone_mode\": \"local\",\n  \"live\": false\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "POST /api/v1/phone/blacklist",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/phone/blacklist",
            "description": "Add or update a number in the API key blacklist",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "DELETE /api/v1/phone/blacklist",
          "request": {
            "method": "DELETE",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/phone/blacklist",
            "description": "Remove a number from the API key blacklist",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"+12025550123\",\n  \"default_country\": \"US\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    },
    {
      "name": "Bulk",
      "item": [
        {
          "name": "POST /api/v1/bulk",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "Idempotency-Key",
                "value": "{{importId}}"
              }
            ],
            "url": "{{baseUrl}}/api/v1/bulk?result_format=validation-v1",
            "description": "Enqueues up to 5.000 unique emails for verification. Debits `credits_debited`\non creation; refunds the difference on cancel or failure.\n\nAccepts either JSON (recommended) or multipart form-data (with a CSV/TXT/XLSX\nfile field). The optional `webhook_url` receives a POST with HMAC signature\nwhen the job completes.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"emails\": [\n    \"person@example.com\"\n  ],\n  \"filename\": \"contacts.csv\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        },
        {
          "name": "GET /api/v1/bulk/{id}",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/bulk/{{jobId}}",
            "description": "Returns job status, progress, and counters. Poll every 3-5 seconds."
          }
        },
        {
          "name": "DELETE /api/v1/bulk/{id}",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": "{{baseUrl}}/api/v1/bulk/{{jobId}}",
            "description": "Cancels a pending or processing job. Refunds unprocessed credits."
          }
        },
        {
          "name": "GET /api/v1/bulk/{id}/download",
          "request": {
            "method": "GET",
            "header": [],
            "url": "{{baseUrl}}/api/v1/bulk/{{jobId}}/download",
            "description": "Only available when `job.status == \"completed\"`. Returns a signed URL\nvalid for 15 minutes (900 seconds). Request a fresh URL after expiry.\nThe CSV has 10 columns:\n`email, status, action, flagged, disposable, free_provider, has_mx,\ndid_you_mean, signals, response_time_ms`.\n"
          }
        },
        {
          "name": "POST /api/v1/bulk/{id}/webhook",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "url": "{{baseUrl}}/api/v1/bulk/{{jobId}}/webhook",
            "description": "Attaches a `webhook_url` and HMAC `webhook_secret` to a still-active job.\nIf you omit `webhook_secret`, one is generated (returned once in this\nresponse).\n\nOn completion, ByeBouncer POSTs to `webhook_url` with headers\n`X-ByeBouncer-Event: bulk.completed` and\n`X-ByeBouncer-Signature: <hex HMAC-SHA256(body, webhook_secret)>`.\n\nPayload:\n```json\n{\n  \"event\": \"bulk.completed\",\n  \"job_id\": \"...\",\n  \"processed\": 1234,\n  \"valid\": 800, \"invalid\": 300, \"unknown\": 134,\n  \"credits_refunded\": 0,\n  \"timestamp\": \"2026-09-05T14:30:00Z\"\n}\n```\n\nPrivate-network URLs (localhost, RFC1918, link-local, multicast) are rejected.\n",
            "body": {
              "mode": "raw",
              "raw": "{\n  \"webhook_url\": \"https://your-app.example/hooks/byebouncer\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            }
          }
        }
      ]
    }
  ]
}
