Skip to main content
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>'
{
  "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_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"
    }
  }
}
Response (200) — pending
{
  "status": "pending"
}
Response (200) — failed
{
  "id": "test-firmo-001",
  "status": "failed",
  "created_at": "2026-06-08T14:00:32.411Z",
  "completed_at": "2026-06-08T14:00:50.456Z"
}

​
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

​
id
string

Unique identifier for the job.

Example:

"test-firmo-001"

​
status
enum<string>

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

Available options:
pending,
processing,
completed,
failed
​
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.