Skip to main content

​
Base URL

All requests must be sent to this base URL over HTTPS.

​
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 an 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 a kernel_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 the x-api-key header:
Generate and manage API keys from Settings > API keys in the Kernel app.
Store your API key in an environment variable and never commit it to source control.

​
Async workflow

All operations run asynchronously. Each one returns an id you poll until the result is ready.
  1. Start — call Resolve entity with the company details.
  2. Poll — call Get entity resolution result with the id. Use exponential backoff between requests (start at 2 seconds, max 30 seconds).
  3. Read result — when status is completed, the record object is included with the resolved identity. When status is failed, record is null.
Jobs transition linearly: 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.

​
Data formats

The API uses the following standards for structured fields:

​
Errors

The API uses standard HTTP status codes:

​
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 respecting 429 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/).

API keys

Create and manage API keys for authentication.

Webhooks

Receive HTTP callbacks when jobs complete or fail.