> ## 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: KYB and Sanctions Screening API - Entity verification and risk scoring
  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
      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
            - type: 'null'
          title: Reason
        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: {}
        website_phones:
          items:
            $ref: '#/components/schemas/WebsitePhone'
          type: array
          title: Website Phones
          default: []
        website_phones_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Website Phones 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.
    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
        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
            - type: 'null'
          title: Reason
      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
            - type: 'null'
          title: Reason
      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
      additionalProperties: false
      type: object
      title: LeadCorrelations
      description: Cross-checks that inform, never change the lead score.
    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:
            - published on https://example.nl/contact
      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.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      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.
    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.