openapi: 3.2.0
info:
  title: isBusinessEmail Check 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: []
tags:
- name: Check
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.
      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'
      tags:
      - Check
      operationId: getV1Check
      x-operation-id-source: derived
    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
            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'
      tags:
      - Check
      operationId: postV1Check
      x-operation-id-source: derived
  /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'
      tags:
      - Check
      operationId: postV1CheckBatch
      x-operation-id-source: derived
components:
  responses:
    E400:
      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'
    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'
  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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer ibe_live_...'
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key