# VerifFR

> French company, EU VAT, and address data for AI agents. Pay per call with USDC on Base via x402. No account. No API key. No subscription.

Base URL: https://veriffr.vercel.app
Network: Base mainnet (eip155:8453)
Asset: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), 6 decimals
Facilitator: https://facilitator.payai.network
Protocol: x402 v2, scheme "exact"

## How payment works

1. Send a normal GET request to a paid endpoint.
2. If you have not paid, the server returns HTTP 402 with a base64-encoded PAYMENT-REQUIRED header. It contains the price, asset, network, and payTo address.
3. Sign an EIP-3009 USDC transfer authorization with your wallet and retry the same request with the PAYMENT-SIGNATURE header.
4. The facilitator verifies and settles the payment. The server returns the data.
5. You are only settled when the response status is 2xx. A 400, 404, or 502 is not charged.

Use an x402 client so you do not have to build the payment header by hand:
- TypeScript: @x402/axios or @x402/fetch
- Python: x402 with httpx
- Docs: https://docs.x402.org

## Paid endpoints

### GET /api/v1/company — $0.01
Search French companies or fetch one exact company by SIRET.

Query parameters:
- q (string, optional): company name, SIREN (9 digits), SIRET (14 digits), or address fragment. Minimum 2 characters.
- siret (string, optional): exact 14-digit SIRET. Overrides q. Returns the full record.
- limit (integer, optional, 1-25, default 10): number of search results.

Examples:
- https://veriffr.vercel.app/api/v1/company?q=TotalEnergies
- https://veriffr.vercel.app/api/v1/company?q=531680445
- https://veriffr.vercel.app/api/v1/company?siret=53168044500024

Search response shape:
{
  "query": "TotalEnergies",
  "total": 641,
  "page": 1,
  "per_page": 10,
  "results": [
    {
      "siren": "531680445",
      "siret": "53168044500024",
      "name": "TOTALENERGIES MARKETING FRANCE",
      "legal_name": "TOTALENERGIES MARKETING FRANCE",
      "acronym": null,
      "naf": "46.71Z",
      "vat": "FR22531680445",
      "address": "562 AVENUE DU PARC DE L'ILE 92000 NANTERRE",
      "postcode": "92000",
      "city": "NANTERRE",
      "created": "2011-03-25",
      "active": true,
      "employees": "1000-1999 employees",
      "category": "GE",
      "establishments": 287
    }
  ],
  "sources": ["INSEE SIRENE via recherche-entreprises.api.gouv.fr"],
  "retrieved_at": "2026-10-23T00:00:00.000Z"
}

Exact SIRET response adds: legal_form_code, matched_siret, is_headquarters, establishment (address, NAF, coordinates, trade names), directors (name, role, type, birth_year, siren), finances (year, revenue_eur, net_income_eur), and flags (association, mission, training organisation, etc.).

### GET /api/v1/vat — $0.01
Validate an EU VAT number against the European Commission VIES registry.

Query parameters:
- vat (string, required): full VAT number with country prefix, e.g. FR40303265045 or DE123456789.

Response shape:
{
  "vat": "FR40303265045",
  "valid": true,
  "confidence": "high",
  "country": "FR",
  "name": "SA SODIMAS",
  "address": "11 RUE AMPERE 26600 PONT DE L ISERE",
  "checked_at": "2026-10-22T23:23:11.163Z",
  "source": "European Commission VIES",
  "vies": { "status": "ok", "code": "VALID" },
  "note": "VAT number is registered and active in VIES."
}

An invalid VAT number is still a successful lookup: valid=false and HTTP 200. You pay for the check, not for a positive result.

If the French VIES service is saturated, the endpoint falls back to the French VAT checksum plus a SIREN existence check. In that case confidence is "medium", vies.status is "unavailable", and the note explains the difference. This is not a VIES confirmation. For non-French VAT numbers, a VIES outage returns 503 and you are not charged.

### GET /api/v1/address — $0.005
Normalize a French address with the official Base Adresse Nationale.

Query parameters:
- q (string, required): address fragment, minimum 3 characters.
- limit (integer, optional, 1-10, default 5).

Response shape:
{
  "query": "10 rue de Rivoli Paris",
  "results": [
    {
      "label": "10 Rue de Rivoli 75004 Paris",
      "housenumber": "10",
      "street": "Rue de Rivoli",
      "postcode": "75004",
      "city": "Paris",
      "citycode": "75104",
      "department": "75",
      "region": "Île-de-France",
      "context": "75, Paris, Île-de-France",
      "latitude": 48.8555,
      "longitude": 2.36041,
      "score": 0.97,
      "type": "housenumber",
      "id": "75104_8249_00010"
    }
  ],
  "source": "Base Adresse Nationale (data.gouv.fr)",
  "retrieved_at": "2026-10-23T00:00:00.000Z"
}

## Free endpoints

- GET /api/v1/demo — one sample company record, same shape as a paid exact lookup.
- GET /api/v1/discovery — machine-readable service catalog with prices.
- GET /api/v1/health — status and payment configuration.
- GET /openapi.json — OpenAPI 3.1 specification.
- GET /llms.txt — this file.

## Data sources and limits

- Company data: INSEE SIRENE, served through recherche-entreprises.api.gouv.fr (Licence Ouverte 2.0).
- VAT: European Commission VIES. Availability depends on member-state systems.
- Addresses: Base Adresse Nationale (data.gouv.fr, Licence Ouverte 2.0).
- Company data is cached for up to 24 hours. Address data is cached for up to 7 days. VAT checks are cached for up to 1 hour.
- The API returns at most 25 company results and 10 address results per call.
- This is a data lookup service, not legal, tax, or financial advice. Verify important decisions against the official registry.

## Errors

- 400 invalid_input: bad or missing parameters. Not charged.
- 402 payment_required: payment header missing or invalid. Follow the PAYMENT-REQUIRED header.
- 404 not_found: no company matches the SIRET. Not charged.
- 502 upstream_error: an official registry is unavailable. Not charged. Retry later.
- 503 vies_unavailable: VIES could not give a definitive answer for a non-French VAT number. Not charged. Respect the Retry-After header.

## Contact

Issues or data corrections: open an issue or contact the operator through the website.