What can I do with the ENTIA API?

The ENTIA API lets you look up business entities worldwide, run risk assessments on domains, retrieve verified identity pages with Schema.org JSON-LD, search the knowledge graph, and access real-time platform metrics.

What authentication does the ENTIA API require?

Some endpoints like entity lookup and platform stats are publicly accessible with rate limits. Others like risk audits and knowledge graph search require an API key sent via the X-ENTIA-API-KEY header.

What response format does the API use?

The API returns JSON by default. Entity identity pages support content negotiation: request text/html for the full page or application/ld+json for structured Schema.org data.

How many entities does ENTIA cover?

ENTIA covers over 5 million verified business entities across 34 countries, sourced from public registries and cross-referenced for accuracy. Exact count available via the /api/v1/stats/live endpoint.

Is there a sandbox or free tier?

Yes. The entity lookup endpoint is publicly accessible and rate-limited to 60 requests per minute. You can try it directly from the API Reference page sandbox.

API Reference | ENTIA - Entity Verification & Trust Infrastructure

Authentication

Some endpoints are publicly accessible with rate limits. Authenticated endpoints require an API key passed in the X-ENTIA-API-KEY header.

                        Request Header
                    
X-ENTIA-API-KEY: your_api_key_here

ⓘ

Getting an API key

Contact api@entia.systems to request API access. Pro and Enterprise plans include authenticated API access with higher rate limits.

Rate Limits

Rate limits are applied per IP address. Exceeding the limit returns 429 Too Many Requests.

Tier	Limit	Applies To
Public	60 req/min	Entity lookup, stats, general endpoints
Audit	5 req/min	Risk score assessments
Dashboard	120 req/min	Authenticated dashboard endpoints

Error Codes

The API uses standard HTTP response codes.

Code	Meaning
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
404	Entity or resource not found
429	Rate limit exceeded
500	Internal server error

Error Response
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 60 seconds.",
  "retry_after": 60
}

GET /api/v1/demo/lookup

Entity Lookup

Look up any business entity worldwide. Accepts company name, CIF/NIF, EU VAT ID, or LEI code. Returns entity details with a computed Trust Score.

Authentication

Public Rate limited: 60/min

Parameters

Parameter	Type	Description
q required	string	Company name, CIF/NIF (e.g. B82846825), EU VAT ID (e.g. ESB82846825), or LEI code. The API auto-detects the input type.

curl "https://entia.systems/api/v1/demo/lookup?q=ESB83967513"

const res = await fetch(
  "https://entia.systems/api/v1/demo/lookup?q=ESB83967513"
);
const data = await res.json();
console.log(data.entity.name, data.trust_score.badge);

import requests

resp = requests.get(
    "https://entia.systems/api/v1/demo/lookup",
    params={"q": "ESB83967513"}
)
data = resp.json()
print(data["entity"]["name"], data["trust_score"]["badge"])

Response

200 OK — real production response (April 2026)
{
  "found": true,
  "query": "ESA28015865",
  "entity": {
    "name": "TELEFONICA SA",
    "id": "ESA28015865",
    "lei": "549300N33JQ7EG2VD447",
    "country_code": "ES",
    "city": "MADRID",
    "address": "GRAN VIA, NUMERO 28, MADRID, 28013, ES",
    "company_status": "ACTIVE"
  },
  "trust_score": {
    "score": 83,
    "badge": "PARTIAL",
    "dimensions": [100, 100, 55, 65, "PENDING", "ACTIVE"]
  },
  "verification": {
    "borme": "VERIFIED (A28015865)",
    "vies": "VERIFIED",
    "gleif": "ACTIVE",
    "ofac": "PENDING",
    "eidas": "PENDING"
  },
  "_live": true
}

Trust Score Badges

VERIFIED Score >= 85

PARTIAL Score >= 60

UNVERIFIED Score < 60

GET /v1/identity/{country}/{sector}/{city}/{slug}

Entity Identity Page

Retrieve the verified identity page (Entia Home) for a specific entity. Each page contains embedded Schema.org JSON-LD with a multi-node @graph structure that AI systems can parse directly.

Authentication

Public

Path Parameters

Parameter	Type	Description
country required	string	ISO 3166-1 alpha-2 country code (e.g. `es`, `gb`, `fr`)
sector required	string	Industry slug (e.g. `dental`, `legal`, `automotive`)
city required	string	City slug, lowercase with hyphens
slug required	string	URL-safe business name slug

# Get full HTML page
curl "https://entia.systems/v1/identity/es/dental/madrid/clinica-dental-sonrisa"

# Get only the structured JSON-LD data
curl -H "Accept: application/ld+json" \
  "https://entia.systems/v1/identity/es/dental/madrid/clinica-dental-sonrisa"

JSON-LD @graph Structure

Each identity page contains a 4-node Schema.org @graph:

application/ld+json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebPage",
      // Canonical URL, dateModified, publisher
    },
    {
      "@type": "Dentist",
      // Entity identity: name, address, contact,
      // identifier (VAT), geo, aggregateRating,
      // areaServed, additionalProperty
    },
    {
      "@type": "CreativeWork",
      // Verification report with trust dimensions
    },
    {
      "@type": "CreativeWork",
      // Territorial economic profile for the area
    }
  ]
}

Entity @type mapping

The entity node uses the correct Schema.org type for each sector: Dentist, LegalService, BeautySalon, AutoRepair, RealEstateAgent, and more.

The 4-Node @graph — Anatomy

Every Entia Home contains a Schema.org @graph with exactly 4 nodes. This is what AI systems parse when they evaluate an entity. Real production data from a verified Spanish dental clinic:

NODE 1 WebPage

Canonical page metadata. Links the entity to the ENTIA platform, establishes the breadcrumb hierarchy (ENTIA > Sector > Entity), and declares the mainEntity reference.

{
  "@type": "WebPage",
  "@id": "https://entia.systems/v1/identity/es/dental/segovia/clinica-dental-rico#webpage",
  "url": "https://entia.systems/v1/identity/es/dental/segovia/clinica-dental-rico",
  "mainEntity": { "@id": "...#entity" },
  "isPartOf": { "@id": "https://entia.systems/#website" },
  "breadcrumb": {
    "@type": "BreadcrumbList",
    "itemListElement": [
      { "position": 1, "name": "ENTIA" },
      { "position": 2, "name": "Dental" },
      { "position": 3, "name": "Clinica Dental Rico" }
    ]
  }
}

NODE 2 Entity (sector-specific @type)

Core identity — legal name, verified address with geocoordinates, contact data, official identifiers (ENTIA ID + CNAE), cross-references to public sources (BORME, AEAT, INE, SEPE, Domain Probe), and areaServed.

{
  "@type": "Dentist",
  "@id": "...#entity",
  "name": "Clinica Dental Rico",
  "url": "https://entia.systems/v1/identity/es/dental/segovia/clinica-dental-rico",
  "telephone": "+34921XXXXXX",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "...",
    "addressLocality": "Segovia",
    "postalCode": "40001",
    "addressRegion": "Castilla y Leon",
    "addressCountry": "ES"
  },
  "geo": { "@type": "GeoCoordinates", "latitude": 40.95, "longitude": -4.12 },
  "areaServed": "Castilla y Leon",
  "identifier": [
    { "propertyID": "ENTIA_ID", "value": "E-ES-DNT-00002C66" },
    { "propertyID": "CNAE", "value": "8623" }
  ],
  "isBasedOn": [
    "https://entia.systems/methodology",
    "BORME — Registro Mercantil",
    "AEAT — Agencia Tributaria",
    "INE — Instituto Nacional de Estadistica",
    "SEPE — Servicio Publico de Empleo",
    "Domain Probe — SSL/DNS/HTTP"
  ],
  "sdDatePublished": "2026-04-03",
  "dateModified": "2026-04-03T..."
}

NODE 3 Verification Report

Machine-readable trust assessment. Includes confidence level, data gap score, HMAC signature (SHA-256), certificate ID, per-source verification status, and reconciliation metrics across sources.

{
  "@type": "CreativeWork",
  "name": "Verification Report",
  "additionalProperty": [
    { "name": "verificationStatus", "value": "verified" },
    { "name": "confidenceLevel", "value": 0.75 },
    { "name": "dataGapScore", "value": 30 },
    { "name": "certificateId", "value": "CERT-D44A54DF" },
    { "name": "signatureHMAC", "value": "SHA-256:a7f3c..." },
    { "name": "sourceVerification_BORME", "value": "confirmed" },
    { "name": "sourceVerification_AEAT", "value": "confirmed" },
    { "name": "sourceVerification_INE", "value": "confirmed" },
    { "name": "sourceVerification_SEPE", "value": "confirmed" },
    { "name": "reconciliationScore", "value": 0.1667 },
    { "name": "unanimousAgreement", "value": 1 }
  ]
}

NODE 4 Territorial Profile

Socioeconomic context for the entity's operating area. Spain includes data from INE (population), SEPE (employment), Hacienda (income), and Catastro (economic index). Other countries include geographic territorial data.

Sources: INE Padron Municipal, SEPE Estadisticas, AEAT Renta Bruta, Catastro ICE Index.

{
  "@type": "CreativeWork",
  "name": "Perfil Socioeconomico — CP 40001",
  "spatialCoverage": {
    "@type": "Place",
    "name": "Segovia",
    "address": {
      "postalCode": "40001",
      "addressRegion": "Castilla y Leon",
      "addressCountry": "ES"
    }
  },
  "additionalProperty": [
    {
      "name": "economicIndex",
      "value": "A",
      // Source: Catastro ICE — Indice Capacidad Economica
    },
    {
      "name": "economicSegment",
      "value": "ELITE",
      // Derived metric by ENTIA from ICE + renta + paro
    },
    {
      "name": "unemploymentCount",
      "value": 1930,
      // Source: SEPE — Servicio Publico de Empleo Estatal
    }
  ]
}

Node availability by country

All 34 countries: Node 1 (WebPage) + Node 2 (Entity) + Node 3 (Verification) + Node 4 (Territorial)
Spain (ES): Node 4 includes full socioeconomic data — ICE index, economic segment, unemployment, salary, income (INE/SEPE/Hacienda/Catastro)
Other countries: Node 4 includes geographic territorial data — municipality, region, postal code

POST /api/v1/audit

Risk Score

Run a comprehensive risk assessment on any domain. Analyzes SSL configuration, DNS health, structured data presence, and AI-readiness signals. Returns a score from 0 (lowest risk) to 100 (highest risk).

Authentication

API key required Rate limited: 5/min

Request Body

Field	Type	Description
domain required	string	The domain to audit (e.g. `example.com`)
sector_id	string	Optional sector hint for more accurate scoring
name	string	Optional business name

curl -X POST "https://entia.systems/api/v1/audit" \
  -H "Content-Type: application/json" \
  -H "X-ENTIA-API-KEY: your_api_key_here" \
  -d '{"domain": "example.com"}'

const res = await fetch("https://entia.systems/api/v1/audit", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-ENTIA-API-KEY": "your_api_key_here"
  },
  body: JSON.stringify({ domain: "example.com" })
});
const data = await res.json();

import requests

resp = requests.post(
    "https://entia.systems/api/v1/audit",
    headers={"X-ENTIA-API-KEY": "your_api_key_here"},
    json={"domain": "example.com"}
)
data = resp.json()
print(f"Risk: {data['risk_score']} ({data['risk_level']})")

Response

200 OK
{
  "status": "SUCCESS",
  "job_id": "entia_a1b2c3d4",
  "domain": "example.com",
  "risk_score": 57.0,
  "risk_level": "HIGH RISK",
  "audit": {
    "current_status": {
      "risk_score": 57.0,
      "risk_level": "HIGH RISK",
      "gaps": ["missing_ssl", "no_structured_data"]
    },
    "predictive_oracle": { /* 30/90 day projections */ },
    "autonomic_intervention": { /* recommended actions */ }
  }
}

⚠

Risk score interpretation: 0-30 = Low Risk, 31-60 = Medium Risk, 61-80 = High Risk, 81-100 = Critical. Lower scores indicate better AI-readiness.

GET /api/v1/stats/live

Platform Stats

Real-time platform metrics. Returns current entity counts, country coverage, and infrastructure stats. Cached for 1 hour.

Authentication

Public

cURL
curl "https://entia.systems/api/v1/stats/live"

Response

200 OK
{
  "entities_total": 5557415,
  "countries": 34,
  "sources": 16,
  "homes_published": 498000,
  "last_updated": "2026-04-03T08:00:00Z"
}

GET /v1/search

Entity Search

Search the ENTIA knowledge graph for entities matching your criteria. Filter by country, sector, and free-text query.

Authentication

API key required

Query Parameters

Parameter	Type	Description
q required	string	Search query (company name or keywords)
country	string	ISO 3166-1 alpha-2 country code filter
sector	string	Sector slug filter
limit	integer	Max results to return (default: 10, max: 100)

cURL
curl -H "X-ENTIA-API-KEY: your_api_key_here" \
  "https://entia.systems/v1/search?q=dental&country=ES&sector=dental&limit=5"

Response

200 OK
{
  "results": [
    {
      "name": "Clinica Dental Sonrisa",
      "country_code": "ES",
      "city": "Madrid",
      "sector": "dental",
      "identity_url": "/v1/identity/es/dental/madrid/clinica-dental-sonrisa",
      "trust_badge": "VERIFIED"
    }
  ],
  "total": 18198,
  "returned": 5
}

Also available

                            GET
                            /v1/entity?domain={domain}
                        
Look up an entity by its domain. Returns the same entity object or 404 if not found.

POST Your webhook URL

Webhook Events

Receive real-time notifications when entity data changes. Configure a webhook URL in your ENTIA dashboard to receive POST requests for the events you subscribe to.

Authentication

Webhook signature verification (HMAC-SHA256)

Event Types

Event	Description
entity.verified	An entity's verification status has been confirmed or upgraded
entity.risk_updated	An entity's risk score has changed
audit.completed	A risk audit has finished processing
subscription.updated	A subscription plan has been created, changed, or cancelled

Webhook Payload

POST to your endpoint
{
  "event": "audit.completed",
  "timestamp": "2026-04-03T14:30:00Z",
  "data": {
    "job_id": "entia_a1b2c3d4",
    "domain": "example.com",
    "risk_score": 42.0,
    "risk_level": "MEDIUM RISK"
  },
  "signature": "sha256=abc123..."
}

JSON-LD Content Negotiation

All Entia Home identity pages support content negotiation. Set the Accept header to control the response format.

Accept Header	Response
text/html	Full rendered HTML page with embedded JSON-LD (default)
application/ld+json	Pure Schema.org JSON-LD @graph with all entity data

Extracting JSON-LD programmatically
import requests

# Get structured data only
resp = requests.get(
    "https://entia.systems/v1/identity/es/dental/madrid/clinica-dental-sonrisa",
    headers={"Accept": "application/ld+json"}
)
jsonld = resp.json()

# Access the entity node
entity = [n for n in jsonld["@graph"] if n["@type"] != "WebPage"][0]
print(entity["name"], entity["address"])

SDKs & Libraries

Official client libraries are in development. In the meantime, the REST API works with any HTTP client.

Python

pip install entia

Coming Soon

JavaScript

npm install @entia/sdk

Coming Soon

Go

go get entia.systems/sdk

Coming Soon

Sandbox

Try the Entity Lookup endpoint live. Enter a company name, CIF, VAT ID, or LEI code.

Query

                        GET https://entia.systems/api/v1/demo/lookup?q=ESB83967513
                    

Try: ES (3 nodos): | | AI Companies:

Comercio	258,160
Reformas	210,227
Inmobiliarias	165,234
Hosteleria	139,513
Asesorias	102,480
Consultoria	47,511
Transporte	39,694
Tecnologia	37,830
Talleres	37,288
Estetica	37,112
Dental	19,722
Legal	28,147

API Reference

Geographic Coverage

Authentication

Rate Limits

Error Codes

Entity Lookup

Parameters

Response

Trust Score Badges

Entity Identity Page

Path Parameters

JSON-LD @graph Structure

The 4-Node @graph — Anatomy

Risk Score

Request Body

Response

Platform Stats

Response

Entity Search

Query Parameters

Response

Webhook Events

Event Types

Webhook Payload

JSON-LD Content Negotiation

SDKs & Libraries

Sandbox

Live Verification — Real Entities

Benbunan Clínica Dental

ALARCÓN ODONTÓLOGOS

Clínica Dental Gallardo

AI Companies — What ENTIA knows about them

OPENAI OPCO, LLC

ANTHROPIC, PBC

GOOGLE LLC