Alignment

POST

alignment

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

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

{
  "error": "external_id is required"
}

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

{
  "error": "Internal server error"
}

Links one CRM record to a Kernel entity, runs the full cleaning pass against the rest of your dataset, and returns entity resolution, firmographics, parentage and the alignment outcome: a recommended action and the duplicate group. Built for repeat calls. A record that already has a Kernel ID keeps it unless you set settings.rematch_entity, so duplicate groups and recommended actions stay stable across refreshes.

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

Available to tracked-usage customers at no credit cost. A new external_id consumes tracked-account capacity. Accounts without an active contract fail with error_type: "not_enabled".

Examples

Align a CRM record for the first time

curl

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

Re-align a known record, keeping its Kernel ID

curl

curl -X POST https://api.kernel.ai/rest/v1/alignment \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "stripe-001"}'

Rematch the entity because the source data changed

curl

curl -X POST https://api.kernel.ai/rest/v1/alignment \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "stripe-001", "legal_name": "Stripe Payments Europe, Limited", "country": "IE", "settings": {"rematch_entity": true}}'

All requests return the same immediate response:

Response (202)

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

Request body

external_id is required. The first time Kernel sees an external_id it also needs legal_name, trading_name or website; otherwise the job fails with error_type: "identity_inputs_missing". Later calls may send external_id alone.

Field	Type	Required	Description
`external_id`	`string`	Yes	Your CRM identifier. 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
`linkedin_url`	`string`	No	LinkedIn URL for the company
`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
`company_registration_number`	`string`	No	Company registration number. Used to resolve the entity; the response returns the stored registration, not this value.
`company_registration_country`	`string`	No	Registry jurisdiction for `company_registration_number`
`settings.rematch_entity`	`boolean`	No	Re-run identity resolution and move the link if it picks a different entity. Can change the Kernel ID, duplicate group, parent chain and recommended action. Defaults to `false`
`settings.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`
`settings.match_to_linkedin`	`boolean`	No	Also match the company’s LinkedIn profile. Defaults to `false`
`settings.force_refresh`	`boolean`	No	Re-research firmographics and parentage instead of using Kernel’s cache. Defaults to `false`
`webhook_url`	`string`	No	HTTPS URL for completion/failure callbacks

Sending the same record again

Fields you send are merged into the stored record: present fields overwrite, absent fields are kept.

Different input, default settings. The Kernel ID is kept. The record is re-cleaned on the merged data, so its duplicate group or recommended action can change. alignment.drifted_identity_inputs lists the identity fields that have moved since the Kernel ID was resolved.
Identical payload. Nothing is written. The record is still re-cleaned against your current dataset, reusing cached research unless force_refresh is set.
Two jobs for the same external_id at once. The second fails with error_type: "alignment_in_progress".

GET /v1/alignment/{job_id} — Poll for results
POST /v1/combined — Resolve an entity and enrich firmographics or parentage, without cleaning

Authorizations

x-api-key

string

header

required

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

Body

application/json

Record to align. external_id identifies it in your CRM and is required.

The record to align. external_id is required; the first time Kernel sees it, at least one of legal_name, trading_name or website is required too. Identity options live under settings.

external_id

string

required

Your CRM identifier for the record to align. Echoed back on record.external_id.

Minimum string length: 1

Example:

"stripe-001"

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. Used to resolve the entity; the response returns the stored registration, not this value.

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"

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"

settings

object

Show child attributes

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/alignment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "external_id": "stripe-001",
  "legal_name": "Stripe, Inc.",
  "website": "stripe.com",
  "country": "US"
}
'

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

{
  "error": "external_id is required"
}

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

{
  "error": "Internal server error"
}

Getting started

API reference

API keys & Webhooks

Examples

Align a CRM record for the first time

Re-align a known record, keeping its Kernel ID

Rematch the entity because the source data changed

Request body

Sending the same record again

Authorizations

Body

Response

​Examples

​Align a CRM record for the first time

​Re-align a known record, keeping its Kernel ID

​Rematch the entity because the source data changed

​Request body

​Sending the same record again

​Related endpoints

Authorizations

Body

Response

Examples

Align a CRM record for the first time

Re-align a known record, keeping its Kernel ID

Rematch the entity because the source data changed

Request body

Sending the same record again

Related endpoints