{"openapi":"3.1.0","info":{"title":"ListBouncer API","version":"1.0.0","description":"Check email addresses and clean email lists. Same checks, results and credits as the ListBouncer dashboard. Docs: https://listbouncer.com/docs/api"},"servers":[{"url":"https://listbouncer.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from the dashboard (lb_live_…)"}}},"paths":{"/api/v1/account":{"get":{"summary":"Credit balance","operationId":"getAccount","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"credits_remaining":{"type":"integer"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}}}}},"/api/v1/verify":{"post":{"summary":"Check one email address","description":"Uses 1 credit, only when the check reaches a definite answer. Limit: 60 per minute per key.","operationId":"verifyEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"email":{"type":"string"},"result":{"type":"string","enum":["safe","major_provider","risky","will_bounce","unknown"],"nullable":true},"reason":{"type":["string","null"],"description":"Machine-readable reason code, e.g. domain_typo, no_mx, catch_all_domain."},"explanation":{"type":"string","description":"A short sentence explaining the result."},"suggested_fix":{"type":["string","null"],"description":"Corrected address when the domain looks like a typo."}}},{"type":"object","properties":{"charged":{"type":"boolean"},"credits_remaining":{"type":"integer"}}}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}}}}},"/api/v1/lists":{"post":{"summary":"Start cleaning a list","description":"1 credit per unique address; duplicates and broken rows are free; Unknown results are refunded when the clean finishes. Up to 50,000 addresses and 4MB. Limit: 10 per hour per key.","operationId":"createList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"name":{"type":"string"},"notify":{"type":"boolean","description":"Also send the 'your list is clean' email. Default false."}},"required":["emails"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"name":{"type":"string"},"notify":{"type":"string","enum":["true","false"]}},"required":["file"]}}}},"responses":{"201":{"description":"Clean started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing"]},"total":{"type":"integer"},"duplicates":{"type":"integer"},"malformed":{"type":"integer"},"credits_remaining":{"type":"integer"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"402":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"413":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"415":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}}}}},"/api/v1/lists/{id}":{"get":{"summary":"Progress and counts for a clean","operationId":"getList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"status":{"type":"string","enum":["processing","done","failed"]},"total":{"type":"integer"},"processed":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}}}}},"/api/v1/lists/{id}/results":{"get":{"summary":"Results for a finished clean","operationId":"getListResults","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"group","in":"query","schema":{"type":"string","enum":["safe","major_provider","risky","will_bounce","unknown"]}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":1000}},{"name":"cursor","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Results (JSON pages, or the whole set as CSV)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"result":{"type":"string","enum":["safe","major_provider","risky","will_bounce","unknown"],"nullable":true},"reason":{"type":["string","null"],"description":"Machine-readable reason code, e.g. domain_typo, no_mx, catch_all_domain."},"explanation":{"type":"string","description":"A short sentence explaining the result."},"suggested_fix":{"type":["string","null"],"description":"Corrected address when the domain looks like a typo."}}}},"next_cursor":{"type":["integer","null"]}}}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true}}}}}}}}}}}