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

# Entity Check

> Full entity trust check.

Always runs country risk and sanctions; runs each other data source
whose identifier is provided (up to 8 total), computes a trust score,
assigns a cluster, and returns a recommendation.

`entity_name` and `country` are required; identifiers (kvk_number,
cbe_number, domain, iban, vat_number, wallet_address) are optional and
raise confidence. With none, only country risk and sanctions run (plus a
KVK name search for NL), at lower confidence.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/entity/check
openapi: 3.1.0
info:
  title: Limitguard.ai
  description: >-
    Lead validation API: the company behind each lead checked against the NL and
    BE business registers, EU VAT and sanctions lists, plus company, KYB and
    agent wallet checks for developers and AI agents
  version: 0.1.0
servers:
  - url: https://api.limitguard.ai
security: []
paths:
  /v1/entity/check:
    post:
      summary: Entity Check
      description: |-
        Full entity trust check.

        Always runs country risk and sanctions; runs each other data source
        whose identifier is provided (up to 8 total), computes a trust score,
        assigns a cluster, and returns a recommendation.

        `entity_name` and `country` are required; identifiers (kvk_number,
        cbe_number, domain, iban, vat_number, wallet_address) are optional and
        raise confidence. With none, only country risk and sanctions run (plus a
        KVK name search for NL), at lower confidence.
      operationId: entity_check_v1_entity_check_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCheckRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustResponse'
        '404':
          description: 'Not cached (X-Response-Quality: cached); no data source was called'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - APIKeyHeader: []
components:
  schemas:
    EntityCheckRequest:
      properties:
        entity_name:
          type: string
          maxLength: 500
          minLength: 1
          title: Entity Name
          description: Legal entity name
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO 3166-1 alpha-2 country code
        kvk_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Kvk Number
          description: Dutch KVK number (8 digits)
        cbe_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Cbe Number
          description: 'Belgian CBE number (format: 0XXX.XXX.XXX)'
        domain:
          anyOf:
            - type: string
              maxLength: 253
            - type: 'null'
          title: Domain
          description: Entity website domain
        iban:
          anyOf:
            - type: string
              maxLength: 34
            - type: 'null'
          title: Iban
          description: IBAN for financial validation
        vat_number:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Vat Number
          description: EU VAT number
        wallet_address:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Wallet Address
          description: Crypto wallet address (format check only; no on-chain lookup)
        wallet_chain:
          anyOf:
            - type: string
            - type: 'null'
          title: Wallet Chain
          description: >-
            Blockchain the address is checked against (eth, base, polygon,
            arbitrum, btc, sol). Defaults to eth when omitted, so send btc or
            sol with a Bitcoin or Solana address
        target_industries:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Target Industries
          description: >-
            Ideal-customer industries: SBI/NACE code prefixes ("62", "64.20") or
            plain words matched as whole words against the register's activity
            descriptions. Information only: never changes the score.
          examples:
            - - '62'
              - software
        target_size:
          anyOf:
            - $ref: '#/components/schemas/EmployeeRange'
            - type: 'null'
          description: >-
            Ideal-customer employee range, both ends inclusive. Information
            only.
      additionalProperties: false
      type: object
      required:
        - entity_name
        - country
      title: EntityCheckRequest
      description: >-
        Full entity check request - always runs country risk and sanctions; runs
        each other data source whose identifier is supplied (up to 8 total).


        `entity_name` and `country` are required; identifiers (kvk_number,
        cbe_number, domain, iban, vat_number, wallet_address) are optional and
        raise confidence.
    TrustResponse:
      properties:
        trust_score:
          type: integer
          maximum: 100
          minimum: 0
          title: Trust Score
          description: Overall trust score
        trust_level:
          $ref: '#/components/schemas/TrustLevel'
        cluster:
          $ref: '#/components/schemas/Cluster'
        recommendation:
          $ref: '#/components/schemas/Recommendation'
        confidence:
          type: number
          maximum: 1
          minimum: 0
          title: Confidence
          description: Score confidence (0-1)
        top_factors:
          items:
            $ref: '#/components/schemas/TopFactor'
          type: array
          maxItems: 5
          title: Top Factors
        correlations:
          additionalProperties:
            type: number
          type: object
          title: Correlations
          description: Key correlations between signals
        findings:
          items:
            $ref: '#/components/schemas/Finding'
          type: array
          title: Findings
          description: >-
            One action per mismatch the correlations show (same rules as the
            report)
        company_profile:
          anyOf:
            - $ref: '#/components/schemas/CompanyProfile'
            - type: 'null'
          description: >-
            NL: what the KVK register says about the company (industry, stopped
            date, size, non-mailing, names, websites)
        dormant_shell:
          anyOf:
            - $ref: '#/components/schemas/DormantShell'
            - type: 'null'
          description: >-
            Weighted dormant-shell score with the signals that fired, for a
            company found in the register. Information only: never changes
            trust_score
        icp_fit:
          anyOf:
            - $ref: '#/components/schemas/IcpFit'
            - type: 'null'
          description: >-
            The company against target_industries / target_size; null when
            neither was sent. Information only: never changes trust_score
        sources_checked:
          type: integer
          minimum: 0
          title: Sources Checked
        processing_time_ms:
          type: integer
          minimum: 0
          title: Processing Time Ms
        enhanced_check_hint:
          anyOf:
            - $ref: '#/components/schemas/EnhancedCheckHint'
            - type: 'null'
          description: Suggested deeper check when recommendation is review or edd
        response_quality:
          type: string
          title: Response Quality
          description: 'Quality tier used for this response: cached, fresh, or enhanced'
          default: fresh
        cache_hit:
          type: boolean
          title: Cache Hit
          description: True if result was served from cache (cached tier)
          default: false
        source_data_dates:
          additionalProperties:
            type: string
          type: object
          title: Source Data Dates
          description: ISO timestamps when each data source was last retrieved
        disclaimers:
          items:
            type: string
          type: array
          title: Disclaimers
          description: Legal disclaimers for data sources used in this response
        version:
          type: string
          title: Version
          default: '1.0'
      type: object
      required:
        - trust_score
        - trust_level
        - cluster
        - recommendation
        - confidence
        - top_factors
        - sources_checked
        - processing_time_ms
      title: TrustResponse
      description: Full trust intelligence response from /v1/entity/check.
    ErrorResponse:
      properties:
        type:
          type: string
          title: Type
          default: about:blank
        title:
          type: string
          title: Title
        status:
          type: integer
          title: Status
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        instance:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance
      type: object
      required:
        - title
        - status
      title: ErrorResponse
      description: RFC 7807 Problem Details response.
    EmployeeRange:
      properties:
        min:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min
          examples:
            - 10
        max:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max
          examples:
            - 50
      additionalProperties: false
      type: object
      title: EmployeeRange
      description: An inclusive employee range; at least one end.
    TrustLevel:
      type: string
      enum:
        - high
        - medium
        - low
        - critical
      title: TrustLevel
    Cluster:
      type: string
      enum:
        - established_eu_enterprise
        - established_eu_sme
        - verified_startup
        - unverified_new
        - high_risk_jurisdiction
        - sanctions_flagged
        - insufficient_data
        - mixed_signals
      title: Cluster
    Recommendation:
      type: string
      enum:
        - proceed
        - review
        - enhanced_due_diligence
        - block
      title: Recommendation
    TopFactor:
      properties:
        source:
          type: string
          title: Source
          description: Data source name
        signal:
          type: string
          title: Signal
          description: What was found
        impact:
          type: string
          title: Impact
          description: positive, negative, or neutral
        weight:
          type: number
          title: Weight
          description: Contribution to score (0-1)
      type: object
      required:
        - source
        - signal
        - impact
        - weight
      title: TopFactor
    Finding:
      properties:
        action:
          type: string
          minLength: 1
          title: Action
        why:
          type: string
          minLength: 1
          title: Why
        expected_result:
          type: string
          minLength: 1
          title: Expected Result
      type: object
      required:
        - action
        - why
        - expected_result
      title: Finding
    CompanyProfile:
      properties:
        status:
          type: string
          enum:
            - active
            - stopped
          title: Status
        stopped_on:
          anyOf:
            - type: string
            - type: 'null'
          title: Stopped On
          description: ISO date the business stopped, when it has
        headline:
          type: string
          title: Headline
        industry:
          anyOf:
            - $ref: '#/components/schemas/Industry'
            - type: 'null'
        other_activities:
          items:
            $ref: '#/components/schemas/Industry'
          type: array
          title: Other Activities
          default: []
        employees:
          anyOf:
            - $ref: '#/components/schemas/Employees'
            - type: 'null'
        branches:
          anyOf:
            - $ref: '#/components/schemas/Branches'
            - type: 'null'
          description: >-
            Always null: branch counts are not in the KVK basisprofiel and need
            a second paid request.
        kvk_non_mailing:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Kvk Non Mailing
          description: >-
            True when the company asked KVK not to receive unsolicited marketing
            mail
        statutory_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Statutory Name
        trade_names:
          items:
            type: string
          type: array
          title: Trade Names
          default: []
        extended_legal_form:
          anyOf:
            - type: string
            - type: 'null'
          title: Extended Legal Form
        websites:
          items:
            type: string
          type: array
          title: Websites
          default: []
        lines:
          items:
            type: string
          type: array
          title: Lines
          default: []
        personal_data_withheld:
          type: boolean
          title: Personal Data Withheld
          description: >-
            True for a sole trader or other natural-person form: its personal
            register data is not returned
          default: false
      additionalProperties: false
      type: object
      required:
        - status
        - headline
      title: CompanyProfile
      description: >-
        What the KVK register says about the company, in fields and in plain
        lines.
    DormantShell:
      properties:
        score:
          type: integer
          maximum: 100
          minimum: 0
          title: Score
        signals:
          items:
            $ref: '#/components/schemas/ShellSignal'
          type: array
          title: Signals
          description: The signals that fired, in plain words
        unknown:
          items:
            type: string
            enum:
              - no_staff
              - holding_activity
              - no_website
              - no_mail_server
              - recently_registered
              - no_annual_accounts
          type: array
          title: Unknown
          description: Signals with no data to decide on; they add nothing
        flag_at:
          type: integer
          title: Flag At
          description: >-
            The score at which the dormant-shell finding is raised (and Lead
            Verify's dormant_shell_signals flag)
          default: 50
      additionalProperties: false
      type: object
      required:
        - score
      title: DormantShell
      description: A weighted 0-100 dormant-shell score. Unknown data never adds to it.
    IcpFit:
      properties:
        industry:
          type: string
          enum:
            - match
            - no_match
            - unknown
          title: Industry
        size:
          type: string
          enum:
            - match
            - no_match
            - unknown
          title: Size
        industry_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Industry Source
        size_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Size Source
        confirmed_elsewhere:
          type: boolean
          title: Confirmed Elsewhere
          description: >-
            Always false: the register is the only layer that holds industry and
            size
          default: false
      additionalProperties: false
      type: object
      required:
        - industry
        - size
      title: IcpFit
      description: >-
        The company against the caller's ideal-customer profile. Information
        only.
    EnhancedCheckHint:
      properties:
        endpoint:
          type: string
          title: Endpoint
          description: API endpoint for enhanced check
        quality:
          type: string
          title: Quality
          description: deep or extended
        price_usdc:
          type: number
          minimum: 0
          title: Price Usdc
          description: Cost via x402 payment
        adds:
          items:
            type: string
          type: array
          title: Adds
          description: Additional data sources included
        tiers:
          items:
            $ref: '#/components/schemas/DeepCheckTierOffer'
          type: array
          title: Tiers
          description: >-
            Every tier the endpoint sells; the top-level fields are the
            recommended one
        trigger_reason:
          type: string
          title: Trigger Reason
          description: Why this check was suggested
      type: object
      required:
        - endpoint
        - quality
        - price_usdc
        - adds
        - trigger_reason
      title: EnhancedCheckHint
      description: 'Upsell hint: suggests a deeper check endpoint when trust is ambiguous.'
    Industry:
      properties:
        code:
          type: string
          title: Code
          description: SBI code
          examples:
            - '01241'
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: KVK's own (Dutch) SBI description
          examples:
            - Teelt van appels en peren
        is_main:
          type: boolean
          title: Is Main
      additionalProperties: false
      type: object
      required:
        - code
        - is_main
      title: Industry
    Employees:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        full_time:
          anyOf:
            - type: integer
            - type: 'null'
          title: Full Time
        part_time:
          anyOf:
            - type: integer
            - type: 'null'
          title: Part Time
      additionalProperties: false
      type: object
      title: Employees
    Branches:
      properties:
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
        commercial:
          anyOf:
            - type: integer
            - type: 'null'
          title: Commercial
      additionalProperties: false
      type: object
      title: Branches
    ShellSignal:
      properties:
        signal:
          type: string
          enum:
            - no_staff
            - holding_activity
            - no_website
            - no_mail_server
            - recently_registered
            - no_annual_accounts
          title: Signal
        words:
          type: string
          title: Words
          examples:
            - no staff
        source:
          type: string
          title: Source
          description: Where the fact comes from
          examples:
            - KVK register
      additionalProperties: false
      type: object
      required:
        - signal
        - words
        - source
      title: ShellSignal
    DeepCheckTierOffer:
      properties:
        quality:
          type: string
          title: Quality
          description: deep, extended or credit
        response_quality:
          type: string
          title: Response Quality
          description: >-
            X-Response-Quality value that buys this tier (fresh, enhanced or
            credit)
        price_usdc:
          type: number
          minimum: 0
          title: Price Usdc
          description: Cost via x402 payment
        adds:
          items:
            type: string
          type: array
          title: Adds
          description: Sources this tier actually returns
      type: object
      required:
        - quality
        - response_quality
        - price_usdc
        - adds
      title: DeepCheckTierOffer
      description: >-
        One purchasable /v1/entity/deep-check tier, as the upsell hint
        advertises it.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.