Resolve entity

POST

entity-resolution

curl --request POST \
  --url https://api.kernel.ai/rest/v1/entity-resolution \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "legal_name": "Stripe"
}
'

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

{
  "error": "Unexpected token"
}

{
  "message": "Forbidden"
}

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

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

Submit a company to resolve its identity. The endpoint returns 202 with an id — use it to poll the Get entity resolution result endpoint until the status is completed.

No fields are required, but providing at least one identifying field improves resolution accuracy.

Examples

Minimal — legal name only

curl

curl -X POST https://api.kernel.ai/rest/v1/entity-resolution \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_name": "Stripe"}'

Response (202)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Full — all fields

curl

curl -X POST https://api.kernel.ai/rest/v1/entity-resolution \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Stripe, Inc.",
    "trading_name": "Stripe",
    "website": "https://stripe.com",
    "match_to_linkedin": true,
    "identity_bias": "NAME_BIAS",
    "country": "US",
    "city": "South San Francisco",
    "state": "CA",
    "postal_code": "94070",
    "email": "info@stripe.com",
    "external_id": "stripe-001",
    "webhook_url": "https://example.com/webhooks/kernel"
  }'

Response (202)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Input fields

All fields are optional. Provide as many as available to improve resolution accuracy.

Field	Type	Description
`legal_name`	string	Registered legal name of the company (e.g. `"Stripe, Inc."`)
`trading_name`	string	Primary brand or trading name (e.g. `"Stripe"`)
`website`	string	Company website URL
`country`	string	Country name or ISO 3166-1 alpha-2 code
`city`	string	City
`state`	string	State or province
`postal_code`	string	ZIP or postal code
`address`	string	Street address
`email`	string	Email address
`external_id`	string	Your own identifier for this record. Echoed back on `record.external_id` in the completed result.
`match_to_linkedin`	boolean	When `true`, Kernel matches the resolved entity to a LinkedIn company profile. Result appears in the `linkedin` field. Defaults to `false`
`identity_bias`	string	Bias the resolver toward name or URL matching when they conflict. One of: `NAME_BIAS`, `URL_BIAS`. Defaults to `URL_BIAS`
`webhook_url`	string	HTTPS URL to receive webhook callbacks when the job completes or fails

Input normalization

You do not need to clean or normalize inputs before sending them:

Company names are case-insensitive — "ACME CORP", "Acme Corp", and "acme corp" are equivalent
Common suffixes like Inc., LLC, Ltd., GmbH are handled automatically
Website URLs are normalized — "acme.com" and "https://www.acme.com/" resolve the same way
Country accepts both codes ("US") and full names ("United States")

Authorizations

x-api-key

string

header

required

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

Body

application/json

Company to resolve. All fields are optional — provide as many as available for better accuracy.

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 entity resolution resultReturns the status and result of an entity resolution job. When `status` is `completed`, the `record` object contains the resolved entity data.

curl --request POST \
  --url https://api.kernel.ai/rest/v1/entity-resolution \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "legal_name": "Stripe"
}
'

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

{
  "error": "Unexpected token"
}

{
  "message": "Forbidden"
}

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

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

Getting started

API reference

API keys & Webhooks

Resolve entity

Examples

Minimal — legal name only

Full — all fields

Input fields

Input normalization

Authorizations

Body

Response

​Examples

​Minimal — legal name only

​Full — all fields

​Input fields

​Input normalization

Authorizations

Body

Response

Examples

Minimal — legal name only

Full — all fields

Input fields

Input normalization