# Agentic KYB — EU Company Verification (VAT + LEI + Sanctions) (`gilgames/agentic-kyb`) Actor

Can your agent safely transact with this company? One call: EU VAT validity (VIES) + legal entity (GLEIF LEI) + EU & OFAC sanctions screening from official sources, with a composite trust flag. Built for AI agents, invoicing automation, and B2B onboarding.

- **URL**: https://apify.com/gilgames/agentic-kyb.md
- **Developed by:** [Istvan Kabai](https://apify.com/gilgames) (community)
- **Categories:** AI, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Agentic KYB — EU Company Verification (VAT + LEI + Sanctions)

**One call answers: can my agent (or my business) safely transact with this company?**

Give it a VAT number, an LEI, or a company name — get back a single structured record combining:

- ✅ **EU VAT validation** via **VIES** (the European Commission's official system) — validity plus the registered name and address where the member state discloses them
- 🏛️ **Legal entity verification** via **GLEIF** — the global LEI record: legal name, jurisdiction, entity and registration status
- 🚫 **Sanctions screening** against the **EU consolidated financial sanctions list** and the **US OFAC SDN list** — refreshed daily, with transparent match confidence
- 🚦 A composite **trust flag**: `CLEAR` / `CAUTION` / `REVIEW` / `HIT` / `INSUFFICIENT_DATA`, with human-readable reasons

Built for **AI agents** (callable as an MCP tool, flat JSON output, deterministic behavior) and equally useful for invoicing automation, B2B onboarding, and e-commerce checkout checks.

### Pricing

**$0.05 per company check** (pay-per-event). A check that fails entirely — every source unavailable — is not charged. Typical commercial KYB checks run $0.20–$3.00; enterprise platforms start at $500/month. Scheduled re-checks in **monitoring mode** bill on a separate, cheaper `monitoring-check` event — see below.

### Why this instead of a plain VAT validator?

A VAT check tells you a number is valid. It does not tell you the counterparty is safe. This actor answers both in one call, for a fraction of the cost of traditional KYB platforms — typical commercial checks run $0.20–$3.00 per screen; enterprise platforms start at $500/month.

### Input

```json
{
  "companies": [
    { "vatNumber": "IE6388047V" },
    { "name": "Sberbank of Russia" },
    { "lei": "HWUPKR0MPOU8FGXBT394" }
  ]
}
```

Each item may combine `vatNumber` (with country prefix), `lei`, and `name` (+ `country`). More identifiers = stronger verification. Single-check convenience fields (`vatNumber`, `companyName`, `lei`, `country`) also work.

### Output (one record per company)

```json
{
  "trustFlag": "CLEAR",
  "trustReasons": ["VAT number valid in VIES", "No sanctions matches (OFAC_SDN, EU_FSF)"],
  "vat": { "status": "ok", "valid": true, "name": "GOOGLE IRELAND LIMITED", "address": "…" },
  "lei": { "status": "found", "lei": "…", "legalName": "…", "registrationStatus": "ISSUED" },
  "sanctions": { "listsChecked": ["OFAC_SDN", "EU_FSF"], "matches": [] },
  "checkedAt": "2026-07-29T21:04:00.000Z"
}
```

Sanctions matches always include the list entry, the name matched against, and a `confidence` of `high` (exact normalized match) or `medium` (token-based — review advised).

### EU sanctions list token (free, optional)

OFAC screening works out of the box. To include the EU consolidated list, supply a free EU FSF download token (create an EU Login, request file access at the Commission's Financial Sanctions Files site) via the `euFsfToken` input field. Without it, screening transparently reports OFAC-only coverage.

### Honest limitations

- **Name matching is name matching.** It produces false positives (common names) and false negatives. `medium` matches are flags for review, not verdicts. Cyrillic and Greek names are transliterated (BGN/PCGN-style) so they screen against Latin queries and vice versa; Arabic and CJK scripts are **not** transliterated — no deterministic letter map exists, and a wrong guess is worse than an honest gap. Transliteration maps script, not language: "Россия" matches "Rossiya", not "Russia".
- VIES member-state backends throttle and occasionally go down; the actor retries and reports `unavailable` honestly per country rather than guessing. Germany and Spain do not disclose names/addresses via VIES.
- Query-time screening only by default — see **Monitoring mode** below for scheduled re-checks.

### Monitoring mode

Set `monitoringMode: true` and re-run the same `companies` on a schedule (e.g. Apify Scheduler, daily or weekly) to get change alerts instead of re-reading full records yourself. Each result gets a `monitoring` field:

```json
"monitoring": {
  "key": "vat-IE6388047V",
  "changed": true,
  "isFirstCheck": false,
  "changes": ["trust flag changed: CLEAR → HIT", "new sanctions match(es): EU_FSF:12345"]
}
```

The first run for a given company is `isFirstCheck: true` (nothing to compare against yet — it establishes the baseline). Subsequent runs compare trust flag, VAT validity, and sanctions matches against the last check. Billed on a separate, cheaper **`monitoring-check`** event rather than `company-check`.

### Disclaimers

Unofficial service. Not affiliated with or endorsed by the European Commission, GLEIF, or the U.S. Treasury/OFAC. Results are a screening aid from official public sources — **not legal advice and not a substitute for regulated AML/KYB obligations**. Data minimization: results are returned to you and not retained beyond the run's dataset; sanctions lists are cached for 24 h. Registry data on sole traders may constitute personal data — process it under your own lawful basis.

# Actor input Schema

## `companies` (type: `array`):

Array of companies. Each item may contain any combination of: `vatNumber` (with country prefix, e.g. "IE6388047V"), `lei` (20-char Legal Entity Identifier), `name` + `country` (ISO 2-letter). More identifiers = stronger verification.

## `vatNumber` (type: `string`):

Convenience field for a single check, e.g. "DE811128135". Ignored if `companies` is set.

## `companyName` (type: `string`):

Convenience field for a single check by name.

## `lei` (type: `string`):

Convenience field: 20-character Legal Entity Identifier.

## `country` (type: `string`):

ISO 2-letter country code accompanying `companyName`.

## `includeEuSanctions` (type: `boolean`):

Requires an EU FSF token (free): set it as the EU\_FSF\_TOKEN environment variable or in the `euFsfToken` field. OFAC SDN screening always runs.

## `euFsfToken` (type: `string`):

Your free EU Financial Sanctions Files download token. Only needed if the actor's EU\_FSF\_TOKEN environment variable is not set.

## `monitoringMode` (type: `boolean`):

For scheduled re-runs of the same `companies` (e.g. via Apify Scheduler): compares each result against the last stored check and reports what changed (trust flag, VAT validity, sanctions matches) in a `monitoring` field on the output. Billed on the cheaper 'monitoring-check' event instead of 'company-check'.

## Actor input object example

```json
{
  "companies": [
    {
      "vatNumber": "IE6388047V"
    },
    {
      "name": "Sberbank of Russia"
    }
  ],
  "includeEuSanctions": true,
  "monitoringMode": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "companies": [
        {
            "vatNumber": "IE6388047V"
        },
        {
            "name": "Sberbank of Russia"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gilgames/agentic-kyb").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "companies": [
        { "vatNumber": "IE6388047V" },
        { "name": "Sberbank of Russia" },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("gilgames/agentic-kyb").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "companies": [
    {
      "vatNumber": "IE6388047V"
    },
    {
      "name": "Sberbank of Russia"
    }
  ]
}' |
apify call gilgames/agentic-kyb --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=gilgames/agentic-kyb",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/aZg43yvRNysij1ahz/builds/sV84eh6qHpbIAzzN1/openapi.json