Every API here is available over the APIs.io API and to AI agents over MCP.
{
"openapi": "3.1.0",
"info": {
"title": "EntityReach API",
"version": "1.1.0",
"description": "Four company-data endpoints available to workspaces with activated API access. Owner-created companies:read Bearer keys. Each successful request, including an empty search, consumes one agreed monthly unit. 60 valid requests/minute per workspace; monthly allowance resets at 00:00 UTC on the first day. Failed provider requests refund the monthly unit but count toward the minute limit. Contacts support page and role parameters. Contact discovery never spends email or mobile reveal credits. No batch or idempotency parameters are provided for these company endpoints. Advanced provider REST APIs use separate credentials; EntityReach MCP uses a scoped workspace key with separate activation. Data examples are fictional and abbreviated."
},
"servers": [
{
"url": "https://entityreach.com/api/v1"
}
],
"security": [
{
"EntityReachKey": []
}
],
"components": {
"securitySchemes": {
"EntityReachKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "er_live_<64 hex characters>",
"description": "Create a companies:read key in Dashboard \u2192 API keys as workspace owner. Requires active EntityReach API access. Never use a provider API key here."
}
},
"schemas": {
"Usage": {
"type": "object",
"required": [
"used",
"limit",
"period"
],
"properties": {
"used": {
"type": "integer",
"minimum": 0,
"description": "Reserved workspace monthly usage when this request was admitted; concurrent requests may finish out of order."
},
"limit": {
"type": "integer",
"minimum": 1
},
"period": {
"type": "string",
"pattern": "^[0-9]{4}-[0-9]{2}$",
"description": "UTC calendar month"
}
}
},
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"Source": {
"type": "object",
"additionalProperties": true,
"properties": {
"id": {
"oneOf": [
{
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
{
"type": "integer"
}
]
},
"name": {
"type": "string"
},
"category": {
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
},
"comment": {
"type": "string"
}
}
},
"SearchMatch": {
"type": "object",
"additionalProperties": true,
"properties": {
"id": {
"oneOf": [
{
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
{
"type": "integer"
}
]
},
"name": {
"type": "string"
},
"registration_number": {
"type": "string"
},
"country_code": {
"type": "string"
},
"vat_number": {
"type": [
"string",
"null"
]
},
"state": {
"type": [
"string",
"null"
]
},
"jurisdiction": {
"type": [
"string",
"null"
]
},
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
"ProfileSection": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"properties": {
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
"Profile": {
"type": "object",
"additionalProperties": true,
"description": "Provenance-enabled profile. Sections and individual fields may be missing or null.",
"properties": {
"id": {
"oneOf": [
{
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
{
"type": "integer"
}
]
},
"basic": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"properties": {
"name": {
"type": "string"
},
"registration_number": {
"type": "string"
},
"status": {
"type": [
"string",
"null"
]
},
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
"address": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"properties": {
"country_code": {
"type": "string"
},
"country_name": {
"type": "string"
},
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
"contact": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"properties": {
"website": {
"type": [
"string",
"null"
]
},
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
"market": {
"$ref": "#/components/schemas/ProfileSection"
},
"lei": {
"$ref": "#/components/schemas/ProfileSection"
}
}
},
"GroupNode": {
"type": "object",
"additionalProperties": true,
"properties": {
"id": {
"oneOf": [
{
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
{
"type": "integer"
}
]
},
"name": {
"type": "string"
},
"country": {
"type": "string"
},
"registration_number": {
"type": "string"
},
"selected": {
"type": "boolean"
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GroupNode"
}
}
}
},
"Group": {
"oneOf": [
{
"type": "object",
"additionalProperties": true,
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GroupNode"
}
},
"source": {
"$ref": "#/components/schemas/Source"
}
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/GroupNode"
}
}
]
},
"ContactDiscovery": {
"type": "object",
"additionalProperties": true,
"description": "Available contacts matched to the selected entity. Search previews do not consume monthly reveal credits. Only previously revealed email/mobile values are returned. Use the website\u2019s explicit Reveal actions to spend contact credits.",
"properties": {
"contacts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": [
"string",
"null"
]
},
"email": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"linkedin": {
"type": [
"string",
"null"
]
},
"emailAvailable": {
"type": "boolean"
},
"mobileAvailable": {
"type": "boolean"
}
}
}
},
"page": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"pages": {
"type": "integer",
"minimum": 1
},
"usage": {
"type": "object",
"additionalProperties": true,
"properties": {
"period": {
"type": "string"
},
"email": {
"type": "object",
"additionalProperties": true,
"properties": {
"limit": {
"type": "integer"
},
"used": {
"type": "integer"
}
}
},
"mobile": {
"type": "object",
"additionalProperties": true,
"properties": {
"limit": {
"type": "integer"
},
"used": {
"type": "integer"
}
}
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"message": {
"type": "string"
}
}
}
}
},
"paths": {
"/companies": {
"get": {
"operationId": "searchCompanies",
"summary": "Find companies by name and country",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "Company legal name, website or registration number. Preserve leading zeros.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 200
},
"example": "Tesco"
},
{
"name": "country",
"in": "query",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Z]{2}$"
},
"example": "GB"
},
{
"name": "kind",
"in": "query",
"required": false,
"description": "Identifier type. Auto detects websites and registration numbers. Use vat explicitly for a tax identifier.",
"schema": {
"type": "string",
"enum": [
"auto",
"name",
"website",
"registration",
"vat"
],
"default": "auto"
}
}
],
"responses": {
"200": {
"description": "Company result and monthly usage. Missing company fields are not inferred.",
"headers": {
"X-RateLimit-Remaining": {
"description": "Remaining monthly requests at admission time, not per-minute capacity.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"usage"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchMatch"
}
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"data": [
{
"id": "12345",
"name": "EXAMPLE COMPANY LIMITED",
"registration_number": "00123456",
"country_code": "GB",
"vat_number": null
}
],
"usage": {
"used": 1,
"limit": 1000,
"period": "2026-09"
}
}
}
}
},
"400": {
"description": "Invalid query or company ID. Correct the parameters before retrying.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, expired or revoked key. Create or rotate your EntityReach key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Workspace API access or scope unavailable. Ask your workspace owner to confirm API access and the key\u2019s scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Unknown endpoint or unavailable company. Check the path and the ID returned by search.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Minute limit, monthly allowance or provider capacity reached. Read the error message. Wait for Retry-After when supplied; monthly exhaustion requires a reset or allowance change.",
"headers": {
"Retry-After": {
"description": "60 seconds for the workspace minute limit. Omitted for monthly exhaustion and some provider limits.",
"schema": {
"type": "string",
"example": "60"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Upstream failure or invalid response. Retry with bounded exponential backoff and jitter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Workspace service or provider dataset unavailable. Retry briefly; contact support if access remains unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "Provider timeout. Retry with bounded backoff. The upstream timeout is 45 seconds.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"description": " Results use the same identity checks as the application. The response includes resolution.status (matched, needs_confirmation, not_found), optional selectedId, and partial. Never treat an ambiguous or partial list as a unique legal-entity match."
}
},
"/companies/{id}": {
"get": {
"operationId": "getCompany",
"summary": "Get a company profile with provenance",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Company ID from search, not a registration number.",
"schema": {
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
"example": "12345"
},
{
"name": "include",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"full"
]
},
"description": "Use full for a normalized company profile with financials, officers, shareholders and per-section retrieval states. Omit to retain the existing registry-detail response."
},
{
"name": "section",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"financials",
"directors",
"ownership"
]
},
"description": "Retrieve only this section; no full-profile request. Response data is the source section; retrieval includes companyId, section, status and list pagination."
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"default": 1
},
"description": "For directors/ownership sections, request retrieval.nextPage to continue. Financials permits page 1 only."
}
],
"responses": {
"200": {
"description": "Company result and monthly usage. Missing company fields are not inferred.",
"headers": {
"X-RateLimit-Remaining": {
"description": "Remaining monthly requests at admission time, not per-minute capacity.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"usage"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Profile"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"data": {
"id": "12345",
"basic": {
"name": "EXAMPLE COMPANY LIMITED",
"registration_number": "00123456",
"status": "Active",
"source": {
"category": "Government Registry",
"name": "Example registry"
}
},
"address": {
"country_code": "GB"
},
"contact": {
"website": "https://example.com"
}
},
"usage": {
"used": 1,
"limit": 1000,
"period": "2026-09"
}
}
}
}
},
"400": {
"description": "Invalid query or company ID. Correct the parameters before retrying.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, expired or revoked key. Create or rotate your EntityReach key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Workspace API access or scope unavailable. Ask your workspace owner to confirm API access and the key\u2019s scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Unknown endpoint or unavailable company. Check the path and the ID returned by search.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Minute limit, monthly allowance or provider capacity reached. Read the error message. Wait for Retry-After when supplied; monthly exhaustion requires a reset or allowance change.",
"headers": {
"Retry-After": {
"description": "60 seconds for the workspace minute limit. Omitted for monthly exhaustion and some provider limits.",
"schema": {
"type": "string",
"example": "60"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Upstream failure or invalid response. Retry with bounded exponential backoff and jitter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Workspace service or provider dataset unavailable. Retry briefly; contact support if access remains unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "Provider timeout. Retry with bounded backoff. The upstream timeout is 45 seconds.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"description": " With include=full, data is a normalized CompanyProfile: company, financials, years, officers, shareholders, sources, warnings, retrievedAt and retrieval. Each retrieval section reports status, retryable and retrievedAt. Partial or failed sections do not erase successful sections. Shareholder data alone is not verified UBO. The section parameter takes precedence over include=full. Shareholder types, verification dates and source evidence inform ownership completeness checks; direct holdings are not a verified UBO determination."
}
},
"/companies/{id}/group": {
"get": {
"operationId": "getCompanyGroup",
"summary": "Get the available corporate hierarchy with provenance",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Company ID from search, not a registration number.",
"schema": {
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
"example": "12345"
}
],
"responses": {
"200": {
"description": "Company result and monthly usage. Missing company fields are not inferred.",
"headers": {
"X-RateLimit-Remaining": {
"description": "Remaining monthly requests at admission time, not per-minute capacity.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"usage"
],
"properties": {
"data": {
"$ref": "#/components/schemas/Group"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"example": {
"data": {
"data": [
{
"id": 12345,
"name": "EXAMPLE COMPANY LIMITED",
"country": "GB",
"selected": true,
"children": [
{
"id": 12346,
"name": "EXAMPLE SUBSIDIARY LIMITED",
"country": "GB",
"selected": false,
"children": []
}
]
}
],
"source": {
"category": "Modelled",
"name": "Example source"
}
},
"usage": {
"used": 1,
"limit": 1000,
"period": "2026-09"
}
}
}
}
},
"400": {
"description": "Invalid query or company ID. Correct the parameters before retrying.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, expired or revoked key. Create or rotate your EntityReach key.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Workspace API access or scope unavailable. Ask your workspace owner to confirm API access and the key\u2019s scope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Unknown endpoint or unavailable company. Check the path and the ID returned by search.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Minute limit, monthly allowance or provider capacity reached. Read the error message. Wait for Retry-After when supplied; monthly exhaustion requires a reset or allowance change.",
"headers": {
"Retry-After": {
"description": "60 seconds for the workspace minute limit. Omitted for monthly exhaustion and some provider limits.",
"schema": {
"type": "string",
"example": "60"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "Upstream failure or invalid response. Retry with bounded exponential backoff and jitter.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Workspace service or provider dataset unavailable. Retry briefly; contact support if access remains unavailable.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "Provider timeout. Retry with bounded backoff. The upstream timeout is 45 seconds.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/companies/{id}/contacts": {
"get": {
"operationId": "getCompanyContacts",
"summary": "Find contact previews without spending email or mobile credits",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"description": "Company ID from search, not a registration number.",
"schema": {
"type": "string",
"pattern": "^[0-9]{1,20}$"
},
"example": "12345"
},
{
"name": "page",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 1
}
},
{
"name": "role",
"in": "query",
"description": "Optional job-title filter; not a guarantee of complete role coverage.",
"schema": {
"type": "string",
"maxLength": 100
}
}
],
"responses": {
"200": {
"description": "Company result and monthly usage. Missing company fields are not inferred.",
"headers": {
"X-RateLimit-Remaining": {
"description": "Remaining monthly requests at admission time, not per-minute capacity.",
"schema": {
"type": "integer",
"minimum": 0
}
},
"Cache-Control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"co
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://artifacts.apis.io/entityreach-com/openapi/_original/entityreach-com-api-openapi.json