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>'

import requests

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

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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))

}

HttpResponse<String> response = Unirest.get("https://api.kernel.ai/rest/v1/entity-resolution/{job_id}")
  .header("x-api-key", "<api-key>")
  .asString();

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",
    "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. 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. 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",
    "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.

Completed result

Get entity resolution result

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

import requests

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

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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))

}

HttpResponse<String> response = Unirest.get("https://api.kernel.ai/rest/v1/entity-resolution/{job_id}")
  .header("x-api-key", "<api-key>")
  .asString();

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",
    "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