Firmographics
Get firmographic enrichment result
Returns the status and result of a firmographic enrichment job. When status is completed, the record field contains the enriched firmographic data.
GET
/
v1
/
firmographics
/
{job_id}
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"
},
"industry": {
"naics": {
"version": "NAICS 2022",
"sector": {
"value": "21 - Mining, Quarrying, and Oil and Gas Extraction",
"code": "21",
"label": "Mining, Quarrying, and Oil and Gas Extraction"
},
"subsector": {
"value": "212 - Mining (except Oil and Gas)",
"code": "212",
"label": "Mining (except Oil and Gas)"
},
"industry_group": {
"value": "2121 - Coal Mining",
"code": "2121",
"label": "Coal Mining"
},
"industry": {
"value": "21211 - Coal Mining",
"code": "21211",
"label": "Coal Mining"
},
"national_industry": null,
"reasoning": "- Coal production and marketing are identified as the target’s activities, and non-coking coal, washed coal, and beneficiation rejects are listed as products.\n- The activity is classified under 21211: Coal Mining because coal is extracted and produced for sale.\n- A surface or underground mining method is not established, so a more specific national industry code is not supported."
},
"sic": {
"version": "SIC 1987",
"division": {
"value": "B - Mining",
"code": "B",
"label": "Mining"
},
"major_group": {
"value": "12 - Coal Mining",
"code": "12",
"label": "Coal Mining"
},
"industry_group": null,
"industry": null,
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operating activities, and multiple coal products are described.\n- 12: Coal Mining is supported because coal is produced through mining rather than merely traded or marketed.\n- A surface or underground mining method is not specified, so neither more specific coal-mining industry is supported."
},
"nace": {
"version": "NACE Rev. 2.1",
"section": {
"value": "B - Mining and quarrying",
"code": "B",
"label": "Mining and quarrying"
},
"division": {
"value": "05 - Mining of coal and lignite",
"code": "05",
"label": "Mining of coal and lignite"
},
"group": {
"value": "05.1 - Mining of hard coal",
"code": "05.1",
"label": "Mining of hard coal"
},
"class": {
"value": "05.10 - Mining of hard coal",
"code": "05.10",
"label": "Mining of hard coal"
},
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operations, and its annual report describes a mine-to-market mission.\n- The target is classified under hard coal mining because coal is produced through its own mining operations.\n- A wholesale classification is not preferred because coal production, rather than resale alone, is documented as the target’s activity."
}
}
}
}Poll this endpoint to check the status and retrieve the result of a firmographic enrichment job.
Once a job reaches
Status lifecycle
Jobs progress linearly to a terminal state:pending → processing → completed | failed
completed or failed, the status does not change.
Result structure
Whenstatus is completed, the record field contains the firmographic data with operational status, location, headcount, revenue, and industry — each group including a reasoning field.
If the kernel_id in the request was retired by a merge, the job runs on the surviving entity. Then record.kernel_id is the Kernel ID of that entity, record.remapped is true, record.requested_kernel_id is the kernel_id that you sent, and record.retired_at is when the merge retired it. Store the new kernel_id in place of the old one.
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",
"requested_kernel_id": "7944166432",
"remapped": false,
"retired_at": null,
"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"
},
"industry": {
"naics": {
"version": "NAICS 2022",
"sector": {
"value": "21 - Mining, Quarrying, and Oil and Gas Extraction",
"code": "21",
"label": "Mining, Quarrying, and Oil and Gas Extraction"
},
"subsector": {
"value": "212 - Mining (except Oil and Gas)",
"code": "212",
"label": "Mining (except Oil and Gas)"
},
"industry_group": {
"value": "2121 - Coal Mining",
"code": "2121",
"label": "Coal Mining"
},
"industry": {
"value": "21211 - Coal Mining",
"code": "21211",
"label": "Coal Mining"
},
"national_industry": null,
"reasoning": "- Coal production and marketing are identified as the target’s activities, and non-coking coal, washed coal, and beneficiation rejects are listed as products.\n- The activity is classified under 21211: Coal Mining because coal is extracted and produced for sale.\n- A surface or underground mining method is not established, so a more specific national industry code is not supported."
},
"sic": {
"version": "SIC 1987",
"division": {
"value": "B - Mining",
"code": "B",
"label": "Mining"
},
"major_group": {
"value": "12 - Coal Mining",
"code": "12",
"label": "Coal Mining"
},
"industry_group": null,
"industry": null,
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operating activities, and multiple coal products are described.\n- 12: Coal Mining is supported because coal is produced through mining rather than merely traded or marketed.\n- A surface or underground mining method is not specified, so neither more specific coal-mining industry is supported."
},
"nace": {
"version": "NACE Rev. 2.1",
"section": {
"value": "B - Mining and quarrying",
"code": "B",
"label": "Mining and quarrying"
},
"division": {
"value": "05 - Mining of coal and lignite",
"code": "05",
"label": "Mining of coal and lignite"
},
"group": {
"value": "05.1 - Mining of hard coal",
"code": "05.1",
"label": "Mining of hard coal"
},
"class": {
"value": "05.10 - Mining of hard coal",
"code": "05.10",
"label": "Mining of hard coal"
},
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operations, and its annual report describes a mine-to-market mission.\n- The target is classified under hard coal mining because coal is produced through its own mining operations.\n- A wholesale classification is not preferred because coal production, rather than resale alone, is documented as the target’s activity."
}
}
}
}
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.
FirmographicResult schema, see Firmographic result.Authorizations
Include your API key in the x-api-key header.
Path Parameters
ID of the firmographic enrichment job
Example:
"test-firmo-001"
Response
Job status response
Current status of the job. Terminal states are completed and failed.
Available options:
pending, processing, completed, failed Unique identifier for the job. Present when status is pending, processing, or completed.
Example:
"test-firmo-001"
Unique identifier for the job. Present only when status is failed.
Example:
"test-firmo-001"
ISO 8601 timestamp when the job was created.
Example:
"2026-06-08T14:00:32.411Z"
ISO 8601 timestamp when the job reached a terminal state.
Example:
"2026-06-08T14:53:53.151Z"
Firmographic data. Present when status is completed.
Show child attributes
Show child attributes
Error message. Present when status is failed.
Machine-readable error type. Present when status is failed. One of: kernel_id_not_found, unknown.
⌘I
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"
},
"industry": {
"naics": {
"version": "NAICS 2022",
"sector": {
"value": "21 - Mining, Quarrying, and Oil and Gas Extraction",
"code": "21",
"label": "Mining, Quarrying, and Oil and Gas Extraction"
},
"subsector": {
"value": "212 - Mining (except Oil and Gas)",
"code": "212",
"label": "Mining (except Oil and Gas)"
},
"industry_group": {
"value": "2121 - Coal Mining",
"code": "2121",
"label": "Coal Mining"
},
"industry": {
"value": "21211 - Coal Mining",
"code": "21211",
"label": "Coal Mining"
},
"national_industry": null,
"reasoning": "- Coal production and marketing are identified as the target’s activities, and non-coking coal, washed coal, and beneficiation rejects are listed as products.\n- The activity is classified under 21211: Coal Mining because coal is extracted and produced for sale.\n- A surface or underground mining method is not established, so a more specific national industry code is not supported."
},
"sic": {
"version": "SIC 1987",
"division": {
"value": "B - Mining",
"code": "B",
"label": "Mining"
},
"major_group": {
"value": "12 - Coal Mining",
"code": "12",
"label": "Coal Mining"
},
"industry_group": null,
"industry": null,
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operating activities, and multiple coal products are described.\n- 12: Coal Mining is supported because coal is produced through mining rather than merely traded or marketed.\n- A surface or underground mining method is not specified, so neither more specific coal-mining industry is supported."
},
"nace": {
"version": "NACE Rev. 2.1",
"section": {
"value": "B - Mining and quarrying",
"code": "B",
"label": "Mining and quarrying"
},
"division": {
"value": "05 - Mining of coal and lignite",
"code": "05",
"label": "Mining of coal and lignite"
},
"group": {
"value": "05.1 - Mining of hard coal",
"code": "05.1",
"label": "Mining of hard coal"
},
"class": {
"value": "05.10 - Mining of hard coal",
"code": "05.10",
"label": "Mining of hard coal"
},
"reasoning": "- Coal production and marketing are identified as Northern Coalfields Limited’s operations, and its annual report describes a mine-to-market mission.\n- The target is classified under hard coal mining because coal is produced through its own mining operations.\n- A wholesale classification is not preferred because coal production, rather than resale alone, is documented as the target’s activity."
}
}
}
}