> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signupbear.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check signup risk

> Evaluate an email and receive an explicit policy decision.

Use this endpoint immediately before creating an account. During private beta,
send `email` as the primary signal; IP input is accepted but not yet evaluated.

<Note>
  `/api/v1/check` remains available as a compatibility route. New integrations
  should use the canonical `/v1/check` path.
</Note>


## OpenAPI

````yaml openapi.json POST /v1/check
openapi: 3.1.0
info:
  title: SignupBear API
  version: 2026-07-beta-1
  description: >-
    Evaluate signup email risk and receive an explicit allow, review, or block
    decision.
servers:
  - url: https://signupbear.com
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/check:
    post:
      tags:
        - Risk checks
      summary: Check signup risk
      description: >-
        Evaluates an email address using the policy attached to the
        authenticated SignupBear account. IP input is accepted during private
        beta but is not yet evaluated.
      operationId: checkSignupRisk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRequest'
            examples:
              email:
                summary: Email check
                value:
                  email: new-user@example.com
              emailAndIp:
                summary: Email with beta IP signal
                value:
                  email: new-user@example.com
                  ip: 203.0.113.4
      responses:
        '200':
          description: >-
            The check completed, partially completed, or returned no currently
            available coverage.
          headers:
            X-SignupBear-Usage:
              description: >-
                Checks consumed in the current monthly usage bucket for this key
                environment.
              schema:
                type: integer
                minimum: 1
            X-SignupBear-Limit:
              description: Monthly check limit for the account's current plan.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResponse'
              examples:
                allow:
                  summary: Allow
                  value:
                    success: true
                    request_id: a2f24aad-23bb-4d45-ae2b-b410ad5b9cb9
                    status: complete
                    risk_level: low
                    recommended_action: allow
                    decision_source: signupbear_policy
                    policy_version: 2026-07-beta-1
                    checked_at: '2026-07-28T08:30:00.000Z'
                    processing_ms: 18
                    coverage:
                      email: complete
                      ip: not_requested
                    email:
                      address: new-user@example.com
                      domain: example.com
                      disposable: false
                      subaddressed: false
                    ip: null
                    reasons: []
                block:
                  summary: Block
                  value:
                    success: true
                    request_id: 6708d574-1600-4483-9cf7-450e26b41c93
                    status: complete
                    risk_level: high
                    recommended_action: block
                    decision_source: signupbear_policy
                    policy_version: 2026-07-beta-1
                    checked_at: '2026-07-28T08:31:00.000Z'
                    processing_ms: 21
                    coverage:
                      email: complete
                      ip: not_requested
                    email:
                      address: high@signupbear.test
                      domain: signupbear.test
                      disposable: false
                      subaddressed: false
                    ip: null
                    reasons:
                      - code: TEST_HIGH_RISK
                        message: Deterministic high-risk test fixture
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/MonthlyLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CheckRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
          maxLength: 254
          description: The signup email address to evaluate.
        ip:
          type: string
          format: ip
          description: >-
            Optional IPv4 or IPv6 address. Accepted but not evaluated during
            private beta.
      anyOf:
        - required:
            - email
        - required:
            - ip
    CheckResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - request_id
        - status
        - risk_level
        - recommended_action
        - decision_source
        - policy_version
        - checked_at
        - processing_ms
        - coverage
        - email
        - ip
        - reasons
      properties:
        success:
          type: boolean
          const: true
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - complete
            - partial
            - failed
        risk_level:
          type: string
          enum:
            - low
            - medium
            - high
            - unknown
        recommended_action:
          type: string
          enum:
            - allow
            - flag
            - review
            - block
        decision_source:
          type: string
          const: signupbear_policy
        policy_version:
          type: string
        checked_at:
          type: string
          format: date-time
        processing_ms:
          type: integer
          minimum: 0
        coverage:
          $ref: '#/components/schemas/Coverage'
        email:
          oneOf:
            - $ref: '#/components/schemas/EmailResult'
            - type: 'null'
        ip:
          oneOf:
            - $ref: '#/components/schemas/IpResult'
            - type: 'null'
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
    Coverage:
      type: object
      additionalProperties: false
      required:
        - email
        - ip
      properties:
        email:
          $ref: '#/components/schemas/CoverageState'
        ip:
          $ref: '#/components/schemas/CoverageState'
    EmailResult:
      type: object
      additionalProperties: false
      required:
        - domain
        - disposable
        - subaddressed
      properties:
        address:
          type: string
          format: email
        domain:
          type: string
        disposable:
          type: boolean
        subaddressed:
          type: boolean
    IpResult:
      type: object
      additionalProperties: false
      required:
        - provided
        - evaluated
      properties:
        provided:
          type: boolean
          const: true
        evaluated:
          type: boolean
          const: false
    Reason:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - EMAIL_SUBADDRESSING
            - DISPOSABLE_EMAIL_DOMAIN
            - CUSTOM_BLOCKLIST_EMAIL
            - CUSTOM_BLOCKLIST_DOMAIN
            - IP_CHECK_NOT_AVAILABLE_BETA
            - TEST_HIGH_RISK
        message:
          type: string
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - request_id
        - status
        - risk_level
        - recommended_action
        - decision_source
        - policy_version
        - checked_at
        - processing_ms
        - error
      properties:
        success:
          type: boolean
          const: false
        request_id:
          type: string
          format: uuid
        status:
          type: string
          const: failed
        risk_level:
          type: string
          const: unknown
        recommended_action:
          type: string
          const: flag
        decision_source:
          type: string
          const: signupbear_policy
        policy_version:
          type: string
        checked_at:
          type: string
          format: date-time
        processing_ms:
          type: integer
          minimum: 0
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - UNAUTHORIZED
                - INVALID_API_KEY
                - INVALID_JSON
                - INVALID_INPUT
                - MONTHLY_LIMIT_EXCEEDED
                - INTERNAL_ERROR
            message:
              type: string
    CoverageState:
      type: string
      enum:
        - complete
        - unavailable
        - not_requested
  responses:
    BadRequest:
      description: The JSON body or one of its fields is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: The Authorization header or API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    MonthlyLimitExceeded:
      description: >-
        The account has consumed all checks available in the current monthly
        usage bucket.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: SignupBear could not complete the check.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SignupBear API key
      description: Use an `sg_test_...` or `sg_live_...` key from the SignupBear dashboard.

````