> ## 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.

# Lead Verify

> Verify one NL/BE sales lead: register, VAT, mail server, IBAN, sanctions, lead score.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/leads/verify
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/leads/verify:
    post:
      tags:
        - leads
      summary: Lead Verify
      description: >-
        Verify one NL/BE sales lead: register, VAT, mail server, IBAN,
        sanctions, lead score.
      operationId: lead_verify_v1_leads_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadVerifyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadVerifyResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    LeadVerifyRequest:
      properties:
        country:
          type: string
          enum:
            - NL
            - BE
          title: Country
          description: 'Country of the company register: NL (KVK) or BE (KBO).'
          examples:
            - NL
        company_number:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: Company Number
          description: 8-digit KVK number (NL) or 10-digit KBO/CBE enterprise number (BE).
          examples:
            - '68750110'
        name:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Name
          description: >-
            Company name as the lead gave it. Required for NL without a
            company_number.
          examples:
            - Test BV Donald
        vat_number:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Vat Number
          description: EU VAT number, checked with VIES.
          examples:
            - NL123456789B01
        email:
          anyOf:
            - type: string
              maxLength: 254
            - type: 'null'
          title: Email
          description: Contact email; only its domain is checked (mail server, disposable).
          examples:
            - sales@example.nl
        domain:
          anyOf:
            - type: string
              maxLength: 253
            - type: 'null'
          title: Domain
          description: Company website domain.
          examples:
            - example.nl
        address:
          anyOf:
            - $ref: '#/components/schemas/LeadAddress'
            - type: 'null'
          description: Address the lead gave; compared with the registered address.
        iban:
          anyOf:
            - type: string
              maxLength: 42
            - type: 'null'
          title: Iban
          description: IBAN the lead gave; validated locally, never echoed (last 4 only).
          examples:
            - NL91ABNA0417164300
        phone:
          anyOf:
            - type: string
              maxLength: 40
            - type: 'null'
          title: Phone
          description: >-
            Phone number the lead gave; compared with the numbers the company
            publishes, never echoed. Not accepted yet: a phone is rejected with
            422 until website phone lookup is switched on.
          examples:
            - +31 20 123 4567
        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:
        - country
      title: LeadVerifyRequest
      description: >-
        One NL or BE lead: a company number or a name, plus whatever else is
        known.
    LeadVerifyResult:
      properties:
        schema_version:
          type: string
          const: lead-verify-v1
          title: Schema Version
          default: lead-verify-v1
        verdict:
          type: string
          enum:
            - real_active
            - real_inactive
            - not_found
            - ambiguous
            - unverifiable
            - sanctioned
          title: Verdict
        reason:
          anyOf:
            - type: string
              const: be_requires_number
            - type: 'null'
          title: Reason
          description: >-
            Why the verdict is what it is, when the verdict alone does not say.
            be_requires_number: a Belgian lead needs a company_number; Belgian
            companies cannot be looked up by name.
        lead_score:
          type: integer
          title: Lead Score
        company:
          $ref: '#/components/schemas/CompanyBlock'
        vat:
          $ref: '#/components/schemas/VatBlock'
        iban:
          $ref: '#/components/schemas/IbanBlock'
        sanctions:
          $ref: '#/components/schemas/SanctionsBlock'
        email:
          $ref: '#/components/schemas/EmailBlock'
        flags:
          items:
            type: string
            enum:
              - name_mismatch
              - address_mismatch
              - iban_invalid
              - iban_foreign
              - vat_invalid
              - vat_owner_mismatch
              - no_mail_server
              - disposable_email
              - recently_registered
              - inactive
              - business_stopped
              - dormant_shell_signals
          type: array
          title: Flags
        findings:
          items:
            $ref: '#/components/schemas/Finding'
          type: array
          title: Findings
        correlations:
          $ref: '#/components/schemas/LeadCorrelations'
          default: {}
        dormant_shell:
          anyOf:
            - $ref: '#/components/schemas/DormantShell'
            - type: 'null'
        icp_fit:
          anyOf:
            - $ref: '#/components/schemas/IcpFit'
            - type: 'null'
        website_phones:
          items:
            $ref: '#/components/schemas/WebsitePhone'
          type: array
          title: Website Phones
          default: []
        website_phones_reason:
          anyOf:
            - type: string
              enum:
                - website_phones_disabled
                - sole_trader_data_disabled
                - no_domain
                - free_mail_domain
                - refused
                - robots_disallowed
                - timeout
                - error
            - type: 'null'
          title: Website Phones Reason
          description: >-
            Why no website phone numbers were read. None when the website was
            read. website_phones_disabled: website phone lookup is off.
            sole_trader_data_disabled: the company is a sole trader or
            partnership, so its contact details are personal data and were not
            read for this business. no_domain: there is no company website to
            read. free_mail_domain: the only domain given is a free email
            provider. refused: the website does not allow it to be read.
            robots_disallowed: the website's robots.txt does not allow its
            contact pages to be read, so the phone was not checked. timeout: the
            website did not answer in time. error: the website could not be
            read.
        discovered_identifiers:
          items:
            $ref: '#/components/schemas/DiscoveredIdentifier'
          type: array
          title: Discovered Identifiers
          default: []
        identifier_discovery_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Identifier Discovery Reason
        sources_checked:
          type: integer
          title: Sources Checked
        checked_at:
          type: string
          title: Checked At
      additionalProperties: false
      type: object
      required:
        - verdict
        - lead_score
        - company
        - vat
        - iban
        - sanctions
        - email
        - flags
        - findings
        - sources_checked
        - checked_at
      title: LeadVerifyResult
      description: One verdict and a 0-100 lead score, with each check that went into it.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LeadAddress:
      properties:
        street:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Street
          examples:
            - Hizzaarderlaan
        house_number:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: House Number
          examples:
            - 3A
        postcode:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Postcode
          examples:
            - 8823 SJ
        city:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: City
          examples:
            - Lollum
      additionalProperties: false
      type: object
      title: LeadAddress
      description: The address the lead gave. Compared with the register, never returned.
    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.
    CompanyBlock:
      properties:
        registered:
          type: boolean
          title: Registered
        status:
          anyOf:
            - type: string
              enum:
                - active
                - inactive
            - type: 'null'
          title: Status
        legal_form:
          anyOf:
            - type: string
            - type: 'null'
          title: Legal Form
        registered_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered Name
        name_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Name Match
        registered_since:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered Since
        age_years:
          anyOf:
            - type: number
            - type: 'null'
          title: Age Years
        sbi_main:
          anyOf:
            - type: string
            - type: 'null'
          title: Sbi Main
        nace_main:
          anyOf:
            - type: string
            - type: 'null'
          title: Nace Main
        employees:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employees
        registered_address:
          anyOf:
            - $ref: '#/components/schemas/RegisteredAddress'
            - type: 'null'
        address_shielded:
          type: boolean
          title: Address Shielded
          default: false
        address_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Address Match
        profile:
          anyOf:
            - $ref: '#/components/schemas/CompanyProfile'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - registered
      title: CompanyBlock
    VatBlock:
      properties:
        checked:
          type: boolean
          title: Checked
        valid:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Valid
        name_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Name Match
        reason:
          anyOf:
            - type: string
              enum:
                - vies_unavailable
                - invalid_format
                - non_eu_country
            - type: 'null'
          title: Reason
          description: >-
            Why the VAT number was not checked or not valid. vies_unavailable:
            the EU VAT service did not answer, so it was not checked.
            invalid_format: the number is not in an EU VAT number format.
            non_eu_country: the number does not start with an EU country code.
      additionalProperties: false
      type: object
      required:
        - checked
      title: VatBlock
    IbanBlock:
      properties:
        checked:
          type: boolean
          title: Checked
        valid:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Valid
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        bank:
          anyOf:
            - type: string
            - type: 'null'
          title: Bank
        bic:
          anyOf:
            - type: string
            - type: 'null'
          title: Bic
        last4:
          anyOf:
            - type: string
            - type: 'null'
          title: Last4
        country_agreement:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Country Agreement
        holder_checked:
          type: boolean
          const: false
          title: Holder Checked
          default: false
      additionalProperties: false
      type: object
      required:
        - checked
      title: IbanBlock
    SanctionsBlock:
      properties:
        screened:
          type: boolean
          title: Screened
        hit:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Hit
        lists_as_of:
          additionalProperties:
            anyOf:
              - type: string
              - type: 'null'
          type: object
          title: Lists As Of
          default: {}
        reason:
          anyOf:
            - type: string
              enum:
                - company_not_resolved
                - legal_form_unknown
                - natural_person_legal_form
                - name_too_short
                - lists_unavailable
            - type: 'null'
          title: Reason
          description: >-
            Why the company name was not screened. company_not_resolved: the
            company was not found in the register. legal_form_unknown: the
            register did not give a legal form, and sole-trader data is off
            (SOLE_TRADER_DATA_ENABLED). natural_person_legal_form: the company
            is a sole trader or partnership, so its name is a person's name and
            was not screened for this business. name_too_short: the registered
            name is too short to screen reliably. lists_unavailable: the
            sanctions lists could not be loaded.
      additionalProperties: false
      type: object
      required:
        - screened
      title: SanctionsBlock
    EmailBlock:
      properties:
        checked:
          type: boolean
          title: Checked
        has_mx:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Has Mx
        disposable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Disposable
      additionalProperties: false
      type: object
      required:
        - checked
      title: EmailBlock
    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
    LeadCorrelations:
      properties:
        kvk_website_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Kvk Website Match
        phone_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Phone Match
        website_identifier_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Website Identifier Match
        kbo_contact_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Kbo Contact Match
        kbo_vat_address_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Kbo Vat Address Match
      additionalProperties: false
      type: object
      title: LeadCorrelations
      description: Cross-checks that inform, never change the lead score.
    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.
    WebsitePhone:
      properties:
        number:
          type: string
          title: Number
          description: E.164
          examples:
            - '+31201234567'
        type:
          type: string
          enum:
            - landline
            - mobile
            - freephone
          title: Type
        found_on_url:
          type: string
          title: Found On Url
        retrieved_at:
          type: string
          title: Retrieved At
        source:
          type: string
          const: website
          title: Source
          default: website
        source_label:
          type: string
          title: Source Label
          examples:
            - >-
              on bol.com, company details page, next to its Chamber of Commerce
              number
        page_kind:
          anyOf:
            - type: string
              enum:
                - home
                - company_details
                - contact
                - about
            - type: 'null'
          title: Page Kind
        register_number_on_page:
          type: boolean
          title: Register Number On Page
          description: The page also shows the company's own KVK/KBO or VAT number.
          default: false
      additionalProperties: false
      type: object
      required:
        - number
        - type
        - found_on_url
        - retrieved_at
        - source_label
      title: WebsitePhone
      description: A phone number the company publishes on its website.
    DiscoveredIdentifier:
      properties:
        kind:
          type: string
          enum:
            - kvk_number
            - kbo_number
            - vat_number
          title: Kind
        value:
          type: string
          title: Value
          examples:
            - '24330087'
            - 0809.309.701
            - NL810433941B01
        found_on_url:
          type: string
          title: Found On Url
        status:
          type: string
          enum:
            - confirmed
            - other_company
            - unverified
          title: Status
        registered_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered Name
        confirmed_by:
          anyOf:
            - type: string
              enum:
                - kvk
                - kbo
                - vies
            - type: 'null'
          title: Confirmed By
        name_match:
          anyOf:
            - type: number
            - type: 'null'
          title: Name Match
        used:
          type: boolean
          title: Used
          default: false
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      additionalProperties: false
      type: object
      required:
        - kind
        - value
        - found_on_url
        - status
      title: DiscoveredIdentifier
      description: One number found on the website, and what its register says about it.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    RegisteredAddress:
      properties:
        street:
          anyOf:
            - type: string
            - type: 'null'
          title: Street
        house_number:
          anyOf:
            - type: string
            - type: 'null'
          title: House Number
        postcode:
          anyOf:
            - type: string
            - type: 'null'
          title: Postcode
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
      additionalProperties: false
      type: object
      title: RegisteredAddress
      description: The address in the register. City only when the register shields it.
    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.
    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
    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
  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.