{"openapi":"3.1.0","info":{"title":"isBusinessEmail API","version":"1.0.0","description":"Is this a work email? Business vs personal vs disposable, plus Google Workspace / Microsoft 365 detection. Free. Docs: https://isbusinessemail.com/docs","contact":{"name":"isBusinessEmail","email":"hello@isbusinessemail.com","url":"https://isbusinessemail.com"},"termsOfService":"https://isbusinessemail.com/terms"},"servers":[{"url":"https://api.isbusinessemail.com"}],"security":[{"bearer":[]},{"apiKey":[]}],"paths":{"/v1/check":{"get":{"summary":"Check an email address, domain or website URL","description":"Pass exactly one of email, domain or url. Prefer POST so addresses do not end up in URLs and logs. Test addresses under test.isbusinessemail.com need no key.","parameters":[{"name":"email","in":"query","schema":{"type":"string"}},{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"url","in":"query","schema":{"type":"string"},"description":"A website address such as https://www.acme.io/pricing; its host is checked."},{"name":"policy","in":"query","schema":{"type":"string","enum":["b2b","strict","lenient"],"default":"b2b"}},{"name":"deep","in":"query","schema":{"type":"boolean","default":false},"description":"Domain age (RDAP) + homepage check. Counts as 5."},{"name":"workspace","in":"query","schema":{"type":"boolean","default":true},"description":"false skips the Microsoft tenant lookup (faster; microsoft_365 tenant fields stay null)."}],"responses":{"200":{"description":"Verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"summary":"Check an email address, domain or website URL (recommended)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Exactly one of email, domain or url.","properties":{"email":{"type":"string"},"domain":{"type":"string"},"url":{"type":"string","maxLength":2048,"description":"A website address; its host (without www.) is checked."},"policy":{"type":"string","enum":["b2b","strict","lenient"]},"deep":{"type":"boolean"},"workspace":{"type":"boolean","default":true,"description":"false skips the Microsoft tenant lookup."}}},"examples":{"email":{"value":{"email":"jane@acme.io"}},"url":{"value":{"url":"https://www.acme.io/pricing"}}}}}},"responses":{"200":{"description":"Verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckResult"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"413":{"$ref":"#/components/responses/E413"},"429":{"$ref":"#/components/responses/E429"}}}},"/v1/check/batch":{"post":{"summary":"Check up to 100 emails, domains or website URLs","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":100,"items":{"type":"string","maxLength":2048,"description":"An email (has @), a URL (has a scheme or a path) or a domain."}},"policy":{"type":"string","enum":["b2b","strict","lenient"]}}}}}},"responses":{"200":{"description":"Results in input order","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"took_ms":{"type":"integer"},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"413":{"$ref":"#/components/responses/E413"},"429":{"$ref":"#/components/responses/E429"}}}},"/v1/feedback":{"post":{"summary":"Report a wrong verdict","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expected_category"],"properties":{"email":{"type":"string"},"domain":{"type":"string"},"expected_category":{"type":"string","enum":["business","personal","disposable","relay","education","government","invalid"]},"comment":{"type":"string","maxLength":1000}}}}}},"responses":{"202":{"description":"Received","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"domain":{"type":"string"},"current_category":{"type":"string"},"reported_category":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/v1/usage":{"get":{"summary":"Your quota and recent usage","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"integer"},"limits":{"type":"object"},"today":{"type":"object"},"daily":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"}}}},"/v1/health":{"get":{"summary":"Health","security":[],"responses":{"200":{"description":"OK"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer ibe_live_..."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"CheckResult":{"type":"object","required":["domain","is_business","category","confidence","recommendation","reasons"],"properties":{"email":{"type":["string","null"],"description":"The address as sent (null for domain and URL checks)."},"url":{"type":"string","description":"Only for URL checks: the website address as sent. Its host (without www.) is the checked domain."},"normalized_email":{"type":["string","null"],"description":"Lowercased, IDN-normalised, +tag removed."},"domain":{"type":["string","null"]},"is_business":{"type":"boolean","description":"True for business, education and government."},"category":{"type":"string","enum":["business","personal","disposable","relay","education","government","invalid","unknown"]},"confidence":{"type":"number","minimum":0,"maximum":1},"recommendation":{"type":"string","enum":["allow","review","block"]},"policy":{"type":"string","enum":["b2b","strict","lenient"]},"is_free_provider":{"type":"boolean"},"is_disposable":{"type":"boolean"},"is_relay":{"type":"boolean"},"is_role_account":{"type":"boolean"},"shared_inbox":{"type":"object","description":"Hint that the address is a shared inbox: one mailbox several people answer from (a Microsoft 365 shared mailbox, a Google collaborative inbox, a helpdesk address) such as support@ or billing@. Only the name is evidence: 0.3 (low) on a match, 0 otherwise. Never changes the recommendation.","properties":{"confidence":{"type":"number","enum":[0,0.3,1]},"match":{"type":["string","null"],"description":"The word that matched, or googlegroups.com.","examples":["support","billing","sales"]}}},"group":{"type":"object","description":"Hint that the address is a group that forwards to many members (a Google Group, a Microsoft 365 group or distribution list) such as team@ or all@. 0.3 (low) on a name match, 1 for @googlegroups.com, 0 otherwise. Never changes the recommendation.","properties":{"confidence":{"type":"number","enum":[0,0.3,1]},"match":{"type":["string","null"],"description":"The word that matched, or googlegroups.com.","examples":["team","all","googlegroups.com"]}}},"is_blocked":{"type":"boolean"},"is_new_domain":{"type":"boolean"},"is_lookalike":{"type":"boolean"},"has_subaddress":{"type":"boolean"},"did_you_mean":{"type":["string","null"],"description":"Suggested domain for a likely typo."},"mail":{"type":"object","properties":{"has_mx":{"type":["boolean","null"]},"provider":{"type":["string","null"],"examples":["google_workspace","microsoft_365","proofpoint"]},"mx":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"host":{"type":"string"},"provider":{"type":["string","null"]}}}},"spf":{"type":["string","null"]},"dmarc_policy":{"type":["string","null"],"enum":["none","quarantine","reject",null]}}},"workspace":{"type":"object","properties":{"google_workspace":{"type":"object","properties":{"detected":{"type":"boolean"},"evidence":{"type":"array","items":{"type":"string"}}}},"microsoft_365":{"type":"object","properties":{"detected":{"type":"boolean"},"tenant_id":{"type":["string","null"],"format":"uuid"},"tenant_region":{"type":["string","null"]},"auth":{"type":["string","null"],"enum":["managed","federated",null]},"identity_provider":{"type":["string","null"],"examples":["okta","adfs","ping"]},"evidence":{"type":"array","items":{"type":"string"}}}},"other_suite":{"type":["string","null"]},"pending":{"type":"boolean"}}},"integrations":{"type":"object","properties":{"google_workspace_ready":{"type":"boolean"},"microsoft_365_ready":{"type":"boolean"}}},"domain_age_days":{"type":["integer","null"]},"reasons":{"type":"array","items":{"type":"string"},"description":"See https://isbusinessemail.com/docs/reason-codes"},"degraded":{"type":"boolean","description":"DNS was unavailable; the verdict is from lists only."},"cached":{"type":"boolean"},"took_ms":{"type":"integer"},"request_id":{"type":"string"}}},"Problem":{"type":"object","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","examples":["rate_limited"]},"detail":{"type":"string"},"docs_url":{"type":"string","format":"uri"}}}},"responses":{"E400":{"description":"Problem details (RFC 9457)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E401":{"description":"Problem details (RFC 9457)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E403":{"description":"Problem details (RFC 9457)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E413":{"description":"Problem details (RFC 9457)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"E429":{"description":"Problem details (RFC 9457)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}