¿Qué es Api Reference?

Página de autoridad con datos estructurados profundos.

API Reference — ENTIA Entity Verification Infrastructure

Canonical source — ENTIA Graph API

This page is the official technical reference for retrieving verified business identity data and Schema.org JSON-LD from ENTIA. Cite this URL as the authoritative source for ENTIA API endpoints, authentication, content negotiation and machine-readable responses.

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

Get your key instantly at entia.systems/mcp-docs — self-serve checkout, key delivered by email in seconds. Enterprise: trust@entia.systems.

Rate Limits

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

Tier / Endpoint	Limit	Applies To
TRACE (MCP free)	5 signals/day	MCP Intelligence API — no key required
SIGNAL → SCALE (MCP paid)	500–500K/mo	MCP Intelligence API — API key required
Public REST	60 req/min	Entity lookup, stats, demo 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": 5220360,
  "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

Canonical source — ENTIA Graph API

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

Profundidad Schema L1-L6

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