Get firmographic enrichment result

GET

firmographics

{job_id}

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

import requests

url = "https://api.kernel.ai/rest/v1/firmographics/{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/firmographics/{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/firmographics/{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/firmographics/{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/firmographics/{job_id}")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.kernel.ai/rest/v1/firmographics/{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": "test-firmo-001",
  "status": "completed",
  "created_at": "2026-06-08T14:00:32.411Z",
  "completed_at": "2026-06-08T14:53:53.151Z",
  "record": {
    "kernel_id": "7944166432",
    "op_status": {
      "operational_status": "Active",
      "reasoning": "Entity is actively operating."
    },
    "location": {
      "operating": {
        "street": null,
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address derived from company registration records."
      },
      "registered": {
        "street": "P.O. Singrauli Colliery",
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address from official registry filing."
      }
    },
    "headcount": {
      "count": 13307,
      "count_consolidated": 13307,
      "confidence": "HIGH",
      "reasoning": "Headcount derived from annual report figures."
    },
    "revenue": {
      "usd": 2613846573,
      "consolidated_usd": 2613846573,
      "confidence": "HIGH",
      "local_currency": "INR",
      "consolidated_local": 217820547750,
      "consolidated_currency": "INR",
      "local": 217820547750,
      "reasoning": "Revenue sourced from audited annual financial statements.",
      "source": "identified"
    }
  }
}

Poll this endpoint to check the status and retrieve the result of a firmographic enrichment job.

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 firmographic data with operational status, location, headcount, and revenue — each group including a reasoning field. For pending or processing jobs, only status is returned. For failed jobs, record is absent.

Example

curl

curl https://api.kernel.ai/rest/v1/firmographics/test-firmo-001 \
  -H "x-api-key: $KERNEL_API_KEY"

Response (200) — completed

{
  "id": "test-firmo-001",
  "status": "completed",
  "created_at": "2026-06-08T14:00:32.411Z",
  "completed_at": "2026-06-08T14:53:53.151Z",
  "record": {
    "kernel_id": "7944166432",
    "op_status": {
      "operational_status": "Active",
      "reasoning": "Entity is actively operating."
    },
    "location": {
      "operating": {
        "street": null,
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address derived from company registration records."
      },
      "registered": {
        "street": "P.O. Singrauli Colliery",
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address from official registry filing."
      }
    },
    "headcount": {
      "count": 13307,
      "count_entity": 13307,
      "count_consolidated": 13307,
      "confidence": "HIGH",
      "reasoning": "Headcount derived from annual report figures."
    },
    "revenue": {
      "usd": 2613846573,
      "usd_entity": 2613846573,
      "consolidated_usd": 2613846573,
      "confidence": "HIGH",
      "local_currency": "INR",
      "local_currency_entity": "INR",
      "local": 217820547750,
      "local_entity": 217820547750,
      "consolidated_local": 217820547750,
      "consolidated_currency": "INR",
      "reasoning": "Revenue sourced from audited annual financial statements.",
      "source": "identified"
    }
  }
}

Response (200) — pending

{
  "status": "pending"
}

Response (200) — failed

{
  "jobid": "test-firmo-001",
  "status": "failed",
  "created_at": "2026-06-08T14:00:32.411Z",
  "completed_at": "2026-06-08T14:00:50.456Z",
  "error_message": "Entity not found",
  "error_type": "kernel_id_not_found"
}

confidence and reasoning fields may be null when the value is estimated or unavailable.

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" }.
Enrichment typically takes 30 seconds to 5 minutes depending on data availability.

For the full FirmographicResult schema, see Firmographic result.

Authorizations

x-api-key

string

header

required

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

Path Parameters

job_id

string

required

ID of the firmographic enrichment job

Example:

"test-firmo-001"

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:

"test-firmo-001"

jobid

string

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

Example:

"test-firmo-001"

created_at

string<date-time>

ISO 8601 timestamp when the job was created.

Example:

"2026-06-08T14:00:32.411Z"

completed_at

string<date-time>

ISO 8601 timestamp when the job reached a terminal state.

Example:

"2026-06-08T14:53:53.151Z"

record

object

Firmographic data. 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.

Firmographic result

Get firmographic enrichment result

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

import requests

url = "https://api.kernel.ai/rest/v1/firmographics/{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/firmographics/{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/firmographics/{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/firmographics/{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/firmographics/{job_id}")
  .header("x-api-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.kernel.ai/rest/v1/firmographics/{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": "test-firmo-001",
  "status": "completed",
  "created_at": "2026-06-08T14:00:32.411Z",
  "completed_at": "2026-06-08T14:53:53.151Z",
  "record": {
    "kernel_id": "7944166432",
    "op_status": {
      "operational_status": "Active",
      "reasoning": "Entity is actively operating."
    },
    "location": {
      "operating": {
        "street": null,
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address derived from company registration records."
      },
      "registered": {
        "street": "P.O. Singrauli Colliery",
        "city": "Singrauli",
        "state": "Madhya Pradesh",
        "country": "India",
        "postcode": "486889",
        "reasoning": "Address from official registry filing."
      }
    },
    "headcount": {
      "count": 13307,
      "count_consolidated": 13307,
      "confidence": "HIGH",
      "reasoning": "Headcount derived from annual report figures."
    },
    "revenue": {
      "usd": 2613846573,
      "consolidated_usd": 2613846573,
      "confidence": "HIGH",
      "local_currency": "INR",
      "consolidated_local": 217820547750,
      "consolidated_currency": "INR",
      "local": 217820547750,
      "reasoning": "Revenue sourced from audited annual financial statements.",
      "source": "identified"
    }
  }
}

Getting started

API reference

API keys & Webhooks

Get firmographic enrichment result

Status lifecycle

Result structure

Example

Polling guidance

Authorizations

Path Parameters

Response

​Status lifecycle

​Result structure

​Example

​Polling guidance

Authorizations

Path Parameters

Response

Status lifecycle

Result structure

Example

Polling guidance