Get entity resolution result

GET

entity-resolution

{job_id}

curl --request GET \
  --url https://api.kernel.ai/rest/v1/entity-resolution/{job_id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.kernel.ai/rest/v1/entity-resolution/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kernel.ai/rest/v1/entity-resolution/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.kernel.ai/rest/v1/entity-resolution/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.kernel.ai/rest/v1/entity-resolution/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "record": {
    "kernel_id": "6347422643",
    "company_registration": {
      "number": "01234567",
      "country": "GB",
      "source": "Companies House"
    },
    "company_registration_number": "01234567",
    "identity_type": "legal_entity",
    "identity_resolution_confidence": "HIGH",
    "identity_resolution_reasoning": "Company identified as Stripe, Inc. via legal name, website, and country alignment.",
    "legal_info": {
      "country": "US",
      "reasoning": "Confirmed via Stripe terms of service page.",
      "trading_name": "Stripe",
      "confidence": "HIGH",
      "legal_name": "Stripe, Inc.",
      "website": "https://stripe.com"
    },
    "trading_info": {
      "country": "US",
      "website": "https://stripe.com",
      "reasoning": "Primary brand site confirmed via domain ownership.",
      "trading_name": "Stripe",
      "confidence": "HIGH"
    },
    "entity_classification": {
      "type": "Company",
      "subtype": "Operating",
      "reasoning": "Classified as an operating company based on commercial activity."
    }
  }
}

Poll this endpoint with the id returned by Resolve entity to check the status and retrieve the result.

Status lifecycle

Jobs progress linearly to a terminal state:

pending → processing → completed | failed

Once a job reaches completed or failed, the status does not change.

Result structure

When status is completed, the record field contains the resolved identity with confidence levels and structured legal and trading information. Prefer record.company_registration for the registration number, issuing country, and register when known. record.company_registration_number is a deprecated alias of company_registration.number. If you included an external_id in the original request, it is echoed back on record.external_id so you can correlate the result with the record you submitted. record.previous_kernel_ids lists the Kernel IDs that this external_id carried before the current one, oldest first. A Kernel ID changes when a merge retires it, or when the record links to a different entity. The list is empty when kernel_id is null, or when the request has no external_id. For pending or processing jobs, record is absent. For failed jobs, record is absent and error_message with error_type are present instead.

Example

curl

curl https://api.kernel.ai/rest/v1/entity-resolution/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: $KERNEL_API_KEY"

Response (200) — completed

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "record": {
    "kernel_id": "6347422643",
    "previous_kernel_ids": [],
    "company_registration": {
      "number": "01234567",
      "country": "GB",
      "source": "Companies House"
    },
    "company_registration_number": "01234567",
    "identity_type": "legal_entity",
    "identity_resolution_confidence": "HIGH",
    "identity_resolution_reasoning": "Company identified as Stripe, Inc. via legal name, website, and country alignment. Official Stripe entity confirmed via terms page.",
    "legal_info": {
      "country": "US",
      "reasoning": "Confirmed via Stripe terms of service page.",
      "trading_name": "Stripe",
      "confidence": "HIGH",
      "legal_name": "Stripe, Inc.",
      "website": "https://stripe.com"
    },
    "trading_info": {
      "country": "US",
      "website": "https://stripe.com",
      "reasoning": "Primary brand site confirmed via domain ownership.",
      "trading_name": "Stripe",
      "confidence": "HIGH"
    },
    "entity_classification": {
      "type": "Company",
      "subtype": "Operating",
      "reasoning": "Classified as an operating company based on commercial activity."
    },
    "external_id": "stripe-001"
  }
}

Response (200) — still processing

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "created_at": "2025-06-05T12:00:00Z"
}

Response (200) — failed

{
  "jobid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "error_message": "Entity not found",
  "error_type": "kernel_id_not_found"
}

Polling guidance

Use exponential backoff between polls (start at 2 seconds, cap at 30 seconds).
Jobs that do not exist yet (or whose ID is unknown) return { "status": "pending" }.

Polling example

TypeScript

const API_KEY = "your_api_key";
const BASE_URL = "https://api.kernel.ai/rest";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

async function resolveEntity(input: Record<string, string>): Promise<string> {
  const res = await fetch(`${BASE_URL}/v1/entity-resolution`, {
    method: "POST",
    headers,
    body: JSON.stringify(input),
  });
  if (!res.ok) throw new Error(`POST failed: ${res.status}`);
  const data = await res.json();
  return data.id;
}

async function pollResult(id: string, timeoutMs = 120_000): Promise<Record<string, unknown>> {
  const start = Date.now();
  let interval = 2000;
  while (Date.now() - start < timeoutMs) {
    const res = await fetch(`${BASE_URL}/v1/entity-resolution/${id}`, { headers });
    if (!res.ok) throw new Error(`GET failed: ${res.status}`);
    const data: Record<string, unknown> = await res.json();
    if (data.status === "completed") return data.record as Record<string, unknown>;
    if (data.status === "failed") throw new Error("Job failed — retry with more identifying fields");
    await new Promise((r) => setTimeout(r, interval));
    interval = Math.min(interval * 2, 30_000);
  }
  throw new Error(`Job ${id} did not complete within ${timeoutMs / 1000}s`);
}

const id = await resolveEntity({ legal_name: "Stripe, Inc.", website: "https://stripe.com", country: "US" });
const result = await pollResult(id);
console.log(result.identity_type); // "legal_entity"

For the full IdentityResult schema, see Completed result.

Authorizations

x-api-key

string

header

required

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

Path Parameters

job_id

string

required

Job ID returned by the POST endpoint

Example:

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

Response

Job status response

status

enum<string>

required

Current status of the job. Terminal states are completed and failed.

Available options:

pending,

processing,

completed,

failed

string

Unique identifier for the job. Present when status is pending, processing, or completed.

Example:

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

jobid

string

Unique identifier for the job. Present only when status is failed.

Example:

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

created_at

string<date-time>

ISO 8601 timestamp when the job was created.

Example:

"2025-06-05T12:00:00Z"

completed_at

string<date-time>

ISO 8601 timestamp when the job reached a terminal state.

Example:

"2025-06-05T12:00:05Z"

record

object

Result payload. Present when status is completed.

Show child attributes

error_message

string

Error message. Present when status is failed.

error_type

string

Machine-readable error type. Present when status is failed. One of: kernel_id_not_found, unknown.

Get entity resolution result

curl --request GET \
  --url https://api.kernel.ai/rest/v1/entity-resolution/{job_id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.kernel.ai/rest/v1/entity-resolution/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kernel.ai/rest/v1/entity-resolution/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.kernel.ai/rest/v1/entity-resolution/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.kernel.ai/rest/v1/entity-resolution/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "record": {
    "kernel_id": "6347422643",
    "company_registration": {
      "number": "01234567",
      "country": "GB",
      "source": "Companies House"
    },
    "company_registration_number": "01234567",
    "identity_type": "legal_entity",
    "identity_resolution_confidence": "HIGH",
    "identity_resolution_reasoning": "Company identified as Stripe, Inc. via legal name, website, and country alignment.",
    "legal_info": {
      "country": "US",
      "reasoning": "Confirmed via Stripe terms of service page.",
      "trading_name": "Stripe",
      "confidence": "HIGH",
      "legal_name": "Stripe, Inc.",
      "website": "https://stripe.com"
    },
    "trading_info": {
      "country": "US",
      "website": "https://stripe.com",
      "reasoning": "Primary brand site confirmed via domain ownership.",
      "trading_name": "Stripe",
      "confidence": "HIGH"
    },
    "entity_classification": {
      "type": "Company",
      "subtype": "Operating",
      "reasoning": "Classified as an operating company based on commercial activity."
    }
  }
}

Getting started

API reference

API keys & Webhooks

Get entity resolution result

Status lifecycle

Result structure

Example

Polling guidance

Polling example

Authorizations

Path Parameters

Response

​Status lifecycle

​Result structure

​Example

​Polling guidance

​Polling example

Authorizations

Path Parameters

Response

Status lifecycle

Result structure

Example

Polling guidance

Polling example