wsystem-dev KYB API

openapi: 3.2.0
info:
  title: W System KYB API
  description: 'EU e-invoicing and business-data API: VAT/VIES and EORI validation, KYB, sanctions screening, EN 16931 e-invoice validation, Peppol lookup. Pay per call via x402 or use an API key; MCP server available.


    **Endpoints:** **EU VAT number validation (VIES)**, **EORI validation (EC EOS)**, **official company-registry lookup**, **sanctions screening (EU, UN, OFAC SDN, UK)**, **one-call KYB**, a **due-diligence report**, and **EU e-invoicing**: validate (EN 16931, XRechnung; UBL, CII, ZUGFeRD/Factur-X PDF), create (JSON -> UBL), ''can I e-invoice this company?'' (VIES + Peppol + mandates), and **SANDBOX send** (verify -> create -> route -> transport -> signed evidence; transport = mock, or a real submission through partner Peppol access-point sandboxes: Recommand playground or e-invoice.be sandbox). Live Peppol sending is not generally available; it opens per company once our access-point partner has activated it.


    * **No API key, no signup:** every client IP gets 20 free calls/day across all endpoints (header `X-Free-Remaining`).

    * **Beyond the free tier:** pay per call with **x402** (USDC on Base, HTTP 402 flow): $0.01 per single check, $0.10 per batch request, $0.045 per KYB check; e-invoice validate $0.03, parse $0.01, create $0.08, route $0.02; due-diligence report $0.49. Or use an API key.

    * **Live Peppol onboarding (API key):** `GET /einvoice/mandate-terms` returns the W System Peppol mandate terms (https://wsystem.dev/legal/peppol-mandate-terms, DPA: https://wsystem.dev/legal/dpa); `POST /einvoice/mandates` records the company''s click-through mandate with a signed receipt.

    * **MCP:** the same tools are available to AI agents at `https://api.wsystem.dev/mcp/` (streamable HTTP).

    * VIES/EOS are official European Commission services; this API adds retries when a member state is unavailable, caching,

    batch endpoints, audit consultation numbers and a stable JSON shape. Docs: https://wsystem.dev/llms.txt'
  contact:
    name: W System
    url: https://wsystem.dev/
  license:
    name: Proprietary API; MCP server code MIT
    url: https://github.com/wsystemdev/eu-business-data-mcp
  version: 0.3.61
  x-guidance: 'EU business verification for agents. GET /verify?vat=IE6388047V validates an EU VAT number via official VIES (name, address, consultation number as audit proof). GET /eori?eori=SE5560360793 validates an EU EORI number. GET /company?q=552032534&country=FR looks up official business registers. GET /sanctions/screen?name=... screens EU/UN/OFAC/UK lists. POST /kyb/check {"company":"FR40303265045"} returns a pass/review/fail KYB verdict. POST /einvoice/validate (raw UBL/CII XML or ZUGFeRD PDF body) checks EN 16931 + XRechnung rules; POST /einvoice/parse (same body) reads an incoming invoice into JSON (parties, totals, VAT, IBAN, lines; no validation); POST /einvoice/create turns JSON into a validated UBL invoice (example body: GET /einvoice/sample); GET /einvoice/route?id=BE0403170701 says whether/how to e-invoice a company; POST /ddreport returns a full due-diligence report. Batch POST variants take up to 100 items. First 20 calls/day per IP are free; after that pay per call with x402 (USDC on Base), or send an X-API-Key.'
servers:
- url: https://api.wsystem.dev
  description: Production
tags:
- name: KYB
  description: VAT + registry + sanctions in one call with a pass/review/fail verdict
paths:
  /kyb/check:
    post:
      tags:
      - KYB
      summary: 'One-call KYB: VAT + registry + sanctions -> verdict'
      description: 'Know-your-business check of an EU company in one request: VIES VAT validation, official business-register lookup and EU/UN/OFAC/UK sanctions screening, combined into a pass / review / fail verdict with reasons. x402 $0.045.'
      operationId: kybCheck
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KybCheck'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: 'Payment Required: x402 v2 challenge (PAYMENT-REQUIRED header). Returned when the free tier is used up, or for a bare call without input.'
        '429':
          description: Free tier used up and x402 disabled
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.045000'
        protocols:
        - x402:
            network: eip155:8453
            asset: USDC
            scheme: exact
        freeTier: 20 calls/day per IP, no key
  /ddreport:
    post:
      tags:
      - KYB
      summary: Counterparty due-diligence report (VAT, register, sanctions, EORI, LEI, Peppol)…
      description: One call bundles VIES VAT validation, official business-register lookup, EU/UN/OFAC/UK sanctions screening, EC EORI check, GLEIF LEI record and the Peppol / e-invoice route into a JSON report with deterministic risk flags, a 0-100 risk score, a pass/review/fail verdict, sources and a UTC timestamp for your audit file. Public company data only; not a regulated AML/KYC decision. x402 $0.49.
      operationId: ddReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DDReport'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '402':
          description: 'Payment Required: x402 v2 challenge (PAYMENT-REQUIRED header). Returned when the free tier is used up, or for a bare call without input.'
        '429':
          description: Free tier used up and x402 disabled
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.490000'
        protocols:
        - x402:
            network: eip155:8453
            asset: USDC
            scheme: exact
        freeTier: 20 calls/day per IP, no key
components:
  schemas:
    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
    KybCheck:
      properties:
        company:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          title: Company
          description: VAT ID ('FR40303265045'), 'CC:name or registry id' ('NO:equinor'), or {name, vatNumber, country, registryId}
          examples:
          - FR40303265045
          - country: 'NO'
            name: Equinor ASA
        requester:
          anyOf:
          - type: string
          - type: 'null'
          title: Requester
          default: HU33119856
        threshold:
          type: number
          maximum: 100.0
          minimum: 50.0
          title: Threshold
          default: 85
      type: object
      required:
      - company
      title: KybCheck
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DDReport:
      properties:
        company:
          type: string
          title: Company
          description: EU VAT ID (best), registry number or company name
          examples:
          - FR40303265045
        country:
          type: string
          title: Country
          description: ISO country code, needed when company is a name or registry number
          default: ''
        threshold:
          type: number
          maximum: 100.0
          minimum: 50.0
          title: Threshold
          default: 85
      type: object
      required:
      - company
      title: DDReport
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Optional monthly-plan key. Without it: free tier, then x402 pay-per-call.'
externalDocs:
  description: Guides, prices and MCP setup
  url: https://wsystem.dev/llms-full.txt
x-discovery:
  mcp: https://api.wsystem.dev/mcp/
  serverCard: https://api.wsystem.dev/server-card
  x402: https://api.wsystem.dev/.well-known/x402