Base URL
What is entity resolution?
Entity resolution is the reasoning-based process Kernel uses to decide what real-world entity a company record represents. It uses names, websites, addresses, email domains, and other signals — not just a simple name lookup — to match records to a canonical entity in Kernel’s database. Each resolved entity returns a structured identity result with confidence levels, legal and trading information, and entity classification. The process is asynchronous — you submit a company, get back a job ID, and poll for the result.What is firmographic enrichment?
Firmographic enrichment adds operational status, location, headcount, and revenue data to a resolved entity. You submit akernel_id from entity resolution and receive structured firmographic data. Like entity resolution, it runs asynchronously.
For the full firmographic result schema, see Firmographic result.
Authentication
All endpoints are authenticated using an API key in thex-api-key header:
Async workflow
All operations run asynchronously. Each one returns ajobId you poll until the result is ready.
- Start — call Resolve entity with the company details.
- Poll — call Get entity resolution result with the
jobId. Use exponential backoff between requests (start at 2 seconds, max 30 seconds). - Read result — when
statusiscompleted, therecordobject is included with the resolved identity. Whenstatusisfailed,recordisnull.
pending → processing → completed | failed. Terminal states do not change.
Job types
The API uses a job-based architecture. Each endpoint corresponds to a specific job type that determines how the request is processed. The job type is determined by the endpoint path — you do not specify it explicitly.| Endpoint | Description |
|---|---|
POST /v1/entity-resolution | Async entity resolution |
GET /v1/entity-resolution/{job_id} | Poll entity resolution result |
GET /v1/lookup-entity/{kernel_id} | Synchronous entity lookup |
POST /v1/resolve-parent | Async parent hierarchy resolution |
GET /v1/resolve-parent/{job_id} | Poll resolve parent result |
POST /v1/firmographics | Async firmographic enrichment |
GET /v1/firmographics/{job_id} | Poll firmographic enrichment result |
Data formats
The API uses the following standards for structured fields:| Data type | Standard | Example |
|---|---|---|
| Country | ISO 3166-1 alpha-2 preferred, any format accepted | US, United States, United States of America |
| Date and time | ISO 8601 | 2025-05-28T14:30:00Z |
| Confidence | Enum | HIGH, MEDIUM, LOW |
Errors
The API uses standard HTTP status codes:| Status | Meaning | Action |
|---|---|---|
401 | Unauthorized — missing or invalid API key | Check your API key |
429 | Rate limit exceeded | Wait for Retry-After seconds, then retry |
500 | Internal server error | Retry with exponential backoff |
Rate limits
Rate limiting is not currently enforced but will be added in a future update. We recommend building retry logic with exponential backoff and respecting429 responses and Retry-After headers when they are introduced.
Versioning
The current API version is v1. We will give at least 6 months notice before deprecating a version. Breaking changes will always be introduced under a new path prefix (e.g./v2/).
Related topics
API keys
Create and manage API keys for authentication.
Webhooks
Receive HTTP callbacks when jobs complete or fail.