Crosscheck

POST

crosscheck

curl --request POST \
  --url https://api.kernel.ai/rest/v1/crosscheck \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "external_id": "0014x00001LMZCDAA5",
  "legal_name": "Stripe, Inc.",
  "website": "stripe.com"
}
'

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

{
  "error": "At least one of legal_name, trading_name, website, or kernel_id is required"
}

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

{
  "error": "Internal server error"
}

Resolves a company to a canonical entity — creating it if it is new to your dataset — then runs the full CRM crosscheck pass on it in one request. The result is split into two blocks: crosscheck carries the recommended action, duplicate grouping, and operational status; parentage carries the corporate hierarchy (immediate, ultimate, and top operating parent, plus regional-subsidiary classification) in the same shape as GET /v1/combined/{job_id}. The endpoint accepts the same inputs as POST /v1/entity-resolution, except that external_id is required. It identifies the record in your CRM, which the pass needs because duplicates and hierarchy are evaluated relative to the rest of your dataset.

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

Crosscheck results are never cached. Each call re-runs the pass, because duplicates, hierarchy, and the recommended action change as your dataset changes.

Credit usage

Outcome	Cost
Entity resolved and crosschecked	5 credits
Entity resolved, crosscheck pass did not run	1 credit

The pass does not run when no entity is resolved, or when the external_id does not match an account in your Kernel dataset. In those cases the job still completes, crosscheck and parentage are both returned as null, and the crosscheck portion of the cost is refunded automatically.

Examples

Crosscheck a CRM record

curl

curl -X POST https://api.kernel.ai/rest/v1/crosscheck \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "0014x00001LMZCDAA5", "legal_name": "Stripe, Inc.", "website": "stripe.com"}'

Crosscheck and match LinkedIn

curl

curl -X POST https://api.kernel.ai/rest/v1/crosscheck \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "0014x00001LMZCDAA5", "website": "stripe.com", "match_to_linkedin": true}'

Both requests return the same immediate response:

Response (202)

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

Request body

external_id is required — it selects which account in your dataset the crosscheck pass runs on. You must also provide at least one of legal_name, trading_name, website, or kernel_id so the entity can be resolved. Requests missing either are rejected with a 400.

Field	Type	Required	Description
`external_id`	`string`	Yes	Your CRM identifier for the record to clean. Echoed back on `record.external_id`.
`legal_name`	`string`	No*	Registered legal name
`trading_name`	`string`	No*	Brand or trading name
`website`	`string`	No*	Company website URL
`kernel_id`	`string`	No*	Resolve against a known Kernel entity
`country`	`string`	No	Country name or ISO 3166-1 alpha-2 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	Email address. Only the domain portion is used for matching.
`phone`	`string`	No	Contact phone
`company_registration_number`	`string`	No	Company registration number
`match_to_linkedin`	`boolean`	No	When `true`, also match the resolved entity to a LinkedIn company profile. Result appears in `record.linkedin`. Defaults to `false`
`identity_bias`	`string`	No	Bias the resolver toward name or URL matching when they conflict. One of `NAME_BIAS`, `URL_BIAS`. Defaults to `URL_BIAS`
`webhook_url`	`string`	No	HTTPS URL to receive callbacks when the job completes or fails

*At least one of legal_name, trading_name, website, or kernel_id is required.

Polling for results

After receiving an id, poll GET /v1/crosscheck/{job_id} with exponential backoff. A full crosscheck runs identity resolution and the complete crosscheck pass, so it typically takes longer than the single-purpose endpoints.

GET /v1/crosscheck/{job_id} — Poll for results
POST /v1/entity-resolution — Resolve an entity only
POST /v1/combined — Resolve an entity and enrich firmographics or parentage
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 crosscheck. external_id identifies the record in your CRM and is required.

external_id

string

required

Your CRM identifier for the record to crosscheck. Required — it selects which account in your dataset the crosscheck pass runs on.

Minimum string length: 1

Example:

"0014x00001LMZCDAA5"

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"

company_registration_number

string

Primary incorporation/registration number. The same number can exist in more than one country — pair it with company_registration_country when known.

Minimum string length: 1

Example:

"01234567"

company_registration_country

string

Registry jurisdiction for company_registration_number (ISO 3166-1 alpha-2 preferred). England, Scotland, Wales, and Northern Ireland map to GB. Falls back to country when omitted.

Minimum string length: 1

Example:

"GB"

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

curl --request POST \
  --url https://api.kernel.ai/rest/v1/crosscheck \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "external_id": "0014x00001LMZCDAA5",
  "legal_name": "Stripe, Inc.",
  "website": "stripe.com"
}
'

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

{
  "error": "At least one of legal_name, trading_name, website, or kernel_id is required"
}

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

{
  "error": "Internal server error"
}

Getting started

API reference

API keys & Webhooks

Credit usage

Examples

Crosscheck a CRM record

Crosscheck and match LinkedIn

Request body

Polling for results

Authorizations

Body

Response

​Credit usage

​Examples

​Crosscheck a CRM record

​Crosscheck and match LinkedIn

​Request body

​Polling for results

​Related endpoints

Authorizations

Body

Response

Credit usage

Examples

Crosscheck a CRM record

Crosscheck and match LinkedIn

Request body

Polling for results

Related endpoints