Combined

POST

combined

curl --request POST \
  --url https://api.kernel.ai/rest/v1/combined \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "jobs": [
    "resolve-parent"
  ],
  "website": "stripe.com"
}
'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

{
  "error": "jobs is required and must contain one or more of 'firmographics' or 'resolve-parent'"
}

{
  "message": "Forbidden"
}

{
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

{
  "error": "Internal processing error."
}

Starts an entity resolution job and then runs one or more follow-up enrichments in one request. Use jobs: ["firmographics"] to resolve an entity and then enrich it with operational status, location, headcount, and revenue data. Use jobs: ["resolve-parent"] to resolve an entity and then look up its parent and top-parent hierarchy. Use jobs: ["resolve-parent", "firmographics"] to run the full bundle — the two follow-ups run in parallel after entity resolution completes. The endpoint accepts the same entity-resolution inputs as POST /v1/entity-resolution, plus a required jobs array that selects the follow-up enrichment(s).

This is an async operation. Poll GET /v1/combined/{job_id} until status is completed, or provide a webhook_url to receive a callback.

Credit usage

Credits are charged for entity resolution plus each follow-up that runs:

Bundle	Cost
Entity resolution + resolve parent	3 credits
Entity resolution + firmographics	3 credits
Entity resolution + resolve parent + firmographics	5 credits

If entity resolution does not find a match, the follow-up cost(s) are refunded automatically and the job completes with kernel_id: null, the requested follow-up fields set to null, and identity_resolution_reasoning explaining the resolution attempt.

Examples

Resolve then resolve parent

curl

curl -X POST https://api.kernel.ai/rest/v1/combined \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobs": ["resolve-parent"], "website": "stripe.com"}'

Resolve then enrich firmographics

curl

curl -X POST https://api.kernel.ai/rest/v1/combined \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobs": ["firmographics"], "website": "stripe.com"}'

Resolve, resolve parent, then enrich firmographics

curl

curl -X POST https://api.kernel.ai/rest/v1/combined \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobs": ["resolve-parent", "firmographics"], "website": "stripe.com"}'

All three requests return the same immediate response:

Response (202)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

Request body

Field	Type	Required	Description
`jobs`	`string[]`	Yes	Follow-up job(s): `["firmographics"]`, `["resolve-parent"]`, or `["resolve-parent", "firmographics"]`
`legal_name`	`string`	No*	Registered legal name
`trading_name`	`string`	No*	Brand or trading name
`website`	`string`	No*	Company website URL
`country`	`string`	No*	Country name or ISO code
`city`	`string`	No*	City
`state`	`string`	No*	State or province
`postal_code`	`string`	No*	ZIP or postal code
`address`	`string`	No*	Street address
`email`	`string`	No*	Contact email
`phone`	`string`	No*	Contact phone
`external_id`	`string`	No*	Your internal identifier. Echoed back on `record.external_id` in the completed result.
`match_to_linkedin`	`boolean`	No	Also match the company’s LinkedIn profile
`identity_bias`	`string`	No	`"NAME_BIAS"` or `"URL_BIAS"`
`webhook_url`	`string`	No	HTTPS URL for completion/failure callbacks

*At least one identifying field is required.

Polling for results

After receiving an id, poll GET /v1/combined/{job_id} with exponential backoff.

GET /v1/combined/{job_id} — Poll for results
POST /v1/entity-resolution — Resolve an entity only
POST /v1/firmographics — Enrich an already-resolved entity
POST /v1/resolve-parent — Resolve parentage for an already-resolved entity

Authorizations

x-api-key

string

header

required

Include your API key in the x-api-key header.

Body

application/json

Company to resolve and the follow-up job(s) to run.

jobs

enum<string>[]

required

Follow-up enrichment jobs to run after entity resolution.

Minimum array length: 1

Available options:

firmographics,

resolve-parent

Example:

["resolve-parent", "firmographics"]

legal_name

string

Registered legal name of the company (e.g. "Stripe, Inc.")

Minimum string length: 1

Example:

"Stripe, Inc."

trading_name

string

Primary brand or trading name (e.g. "Stripe")

Minimum string length: 1

Example:

"Stripe"

website

string

Company website URL.

Minimum string length: 1

Example:

"https://stripe.com"

country

string

Country name or ISO 3166-1 alpha-2 code.

Minimum string length: 1

Example:

"US"

city

string

City.

Minimum string length: 1

Example:

"South San Francisco"

state

string

State or province.

Minimum string length: 1

Example:

"CA"

postal_code

string

ZIP or postal code.

Minimum string length: 1

Example:

"94070"

address

string

Street address.

Minimum string length: 1

Example:

"354 Oyster Point Blvd"

string

Email address. Only the domain portion is used for matching.

Minimum string length: 1

Example:

"info@stripe.com"

phone

string

Phone number. Used as an additional signal for entity resolution.

Minimum string length: 1

Example:

"+1 555-555-5555"

external_id

string

Your own identifier for this record.

Minimum string length: 1

Example:

"stripe-001"

kernel_id

string

An existing Kernel ID. When provided, the resolver skips matching and returns the canonical record for this entity.

Minimum string length: 1

Example:

"6347422643"

linkedin_url

string

LinkedIn URL for the company (e.g. "https://linkedin.com/company/stripe"). Used as an additional signal for entity resolution.

Minimum string length: 1

Example:

"https://linkedin.com/company/stripe"

match_to_linkedin

boolean

default:false

When true, Kernel will attempt to match the resolved entity to a LinkedIn company profile. The result is returned in the linkedin field of the completed record. Defaults to false.

Example:

true

identity_bias

enum<string>

Bias the resolver toward name or URL matching when they conflict. One of: NAME_BIAS, URL_BIAS. Defaults to URL_BIAS.

Available options:

NAME_BIAS,

URL_BIAS

webhook_url

string<uri>

HTTPS URL to receive webhook callbacks when the job completes or fails. Kernel will POST the job result to this URL with an X-Kernel-Signature header for verification.

Pattern: ^https://

Example:

"https://example.com/webhooks/kernel"

Response

Job created

string

required

Unique identifier for the created job.

Example:

"550e8400-e29b-41d4-a716-446655440000"

status

enum<string>

required

Initial status of the job.

Available options:

processing

Get combined resultReturns the status and result of a combined job. When `status` is `completed`, the `record` object contains the entity resolution result and the requested enrichment.

curl --request POST \
  --url https://api.kernel.ai/rest/v1/combined \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "jobs": [
    "resolve-parent"
  ],
  "website": "stripe.com"
}
'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

{
  "error": "jobs is required and must contain one or more of 'firmographics' or 'resolve-parent'"
}

{
  "message": "Forbidden"
}

{
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

{
  "error": "Internal processing error."
}

Getting started

API reference

API keys & Webhooks

Credit usage

Examples

Resolve then resolve parent

Resolve then enrich firmographics

Resolve, resolve parent, then enrich firmographics

Request body

Polling for results

Authorizations

Body

Response

​Credit usage

​Examples

​Resolve then resolve parent

​Resolve then enrich firmographics

​Resolve, resolve parent, then enrich firmographics

​Request body

​Polling for results

​Related endpoints

Authorizations

Body

Response

Credit usage

Examples

Resolve then resolve parent

Resolve then enrich firmographics

Resolve, resolve parent, then enrich firmographics

Request body

Polling for results

Related endpoints