> ## Documentation Index
> Fetch the complete documentation index at: https://dev.kernel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

```bash curl theme={null}
curl https://api.kernel.ai/rest/v1/firmographics/test-firmo-001 \
  -H "x-api-key: $KERNEL_API_KEY"
```

```json Response (200) — completed theme={null}
{
  "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"
    }
  }
}
```

```json Response (200) — pending theme={null}
{
  "status": "pending"
}
```

```json Response (200) — failed theme={null}
{
  "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](/api-reference/schemas/firmographic-result).


## OpenAPI

````yaml GET /v1/firmographics/{job_id}
openapi: 3.1.0
info:
  title: Kernel API
  description: Resolve company identities to canonical entities with a simple async API
  version: 1.0.0
  contact:
    email: support@kernel.ai
  license:
    name: MIT
servers:
  - url: https://api.kernel.ai/rest
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Entity Resolution
    description: Resolve a company to a canonical entity
  - name: Firmographics
    description: Retrieve and enrich firmographic data for resolved entities
  - name: Parentage
    description: Look up parent and top-parent entities in a corporate hierarchy
  - name: Combined
    description: Resolve an entity and run a follow-up enrichment in one call
  - name: LinkedIn Lookup
    description: Provisional LinkedIn company match jobs (not Kernel-verified)
paths:
  /v1/firmographics/{job_id}:
    get:
      tags:
        - Firmographics
      summary: Get firmographic enrichment result
      description: >-
        Returns the status and result of a firmographic enrichment job. When
        `status` is `completed`, the `record` field contains the enriched
        firmographic data.
      operationId: getFirmographicsJob
      parameters:
        - name: job_id
          in: path
          description: ID of the firmographic enrichment job
          required: true
          schema:
            type: string
            example: test-firmo-001
      responses:
        '200':
          description: Job status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmographicJobStatus'
              examples:
                completed:
                  summary: Completed — enrichment done
                  value:
                    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
                pending:
                  summary: Pending — job not yet started
                  value:
                    status: pending
                failed:
                  summary: Failed
                  value:
                    jobid: test-firmo-001
                    status: failed
                    created_at: '2026-06-08T14:00:32.411Z'
                    completed_at: '2026-06-08T14:00:50.456Z'
        '403':
          description: Forbidden — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              example:
                message: Forbidden
        '503':
          description: Service unavailable — database error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Service unavailable
components:
  schemas:
    FirmographicJobStatus:
      type: object
      required:
        - status
      properties:
        id:
          description: >-
            Unique identifier for the job. Present when `status` is `pending`,
            `processing`, or `completed`.
          type: string
          example: test-firmo-001
        jobid:
          description: >-
            Unique identifier for the job. Present only when `status` is
            `failed`.
          type: string
          example: test-firmo-001
        status:
          description: >-
            Current status of the job. Terminal states are `completed` and
            `failed`.
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        created_at:
          description: ISO 8601 timestamp when the job was created.
          type: string
          format: date-time
          example: '2026-06-08T14:00:32.411Z'
        completed_at:
          description: ISO 8601 timestamp when the job reached a terminal state.
          type: string
          format: date-time
          example: '2026-06-08T14:53:53.151Z'
        record:
          $ref: '#/components/schemas/FirmographicResult'
          description: Firmographic data. Present when `status` is `completed`.
        error_message:
          description: Error message. Present when `status` is `failed`.
          type: string
        error_type:
          description: >-
            Machine-readable error type. Present when `status` is `failed`. One
            of: `kernel_id_not_found`, `unknown`.
          type: string
    ForbiddenError:
      required:
        - message
      type: object
      properties:
        message:
          description: Error message from API Gateway.
          type: string
          example: Forbidden
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: Error description.
          type: string
          example: Entity not found
    FirmographicResult:
      required:
        - kernel_id
        - op_status
        - location
        - headcount
        - revenue
      type: object
      properties:
        kernel_id:
          description: The unique identifier for the entity in Kernel's database.
          type: string
          example: '2532551796'
        op_status:
          description: Operational status of the entity. `null` when not yet determined.
          oneOf:
            - type: 'null'
            - type: object
              properties:
                operational_status:
                  description: Current operational status.
                  type:
                    - string
                    - 'null'
                  enum:
                    - Active
                    - Out of business
                    - Absorbed
                    - Undetermined
                    - null
                  example: Active
                reasoning:
                  description: Explanation of how the operational status was determined.
                  type:
                    - string
                    - 'null'
                  example: Entity is actively operating with no signs of cessation.
        location:
          description: Operating and registered addresses. `null` when not yet determined.
          oneOf:
            - type: 'null'
            - type: object
              properties:
                operating:
                  description: Operating address.
                  oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/Address'
                registered:
                  description: Registered/legal address.
                  oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/Address'
        headcount:
          description: Headcount data. `null` when not yet determined.
          oneOf:
            - type: 'null'
            - type: object
              properties:
                count:
                  description: >-
                    Recommended (headline) headcount. Kernel automatically picks
                    the entity-direct or consolidated figure based on entity
                    type; equals `count_entity` or `count_consolidated`.
                  type:
                    - number
                    - 'null'
                  example: 5300
                count_entity:
                  description: Entity-direct headcount, excluding subsidiaries.
                  type:
                    - number
                    - 'null'
                  example: 5300
                count_consolidated:
                  description: Consolidated headcount including subsidiaries.
                  type:
                    - number
                    - 'null'
                  example: 8150
                confidence:
                  description: Confidence in the headcount figure.
                  type:
                    - string
                    - 'null'
                  enum:
                    - HIGH
                    - MEDIUM
                    - LOW
                    - null
                reasoning:
                  description: Explanation of how the headcount was determined.
                  type:
                    - string
                    - 'null'
                  example: Headcount derived from annual report figures.
        revenue:
          description: Revenue data. `null` when not yet determined.
          oneOf:
            - type: 'null'
            - type: object
              properties:
                usd:
                  description: >-
                    Recommended (headline) annual revenue in USD. Kernel
                    automatically picks the entity-direct or consolidated figure
                    based on entity type; equals `usd_entity` or
                    `consolidated_usd`.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                usd_entity:
                  description: Entity-direct annual revenue in USD, excluding subsidiaries.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                consolidated_usd:
                  description: Consolidated annual revenue in USD including subsidiaries.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                confidence:
                  description: Confidence in the revenue figure.
                  type:
                    - string
                    - 'null'
                  enum:
                    - HIGH
                    - MEDIUM
                    - LOW
                    - null
                local_currency:
                  description: >-
                    The local currency of the recommended source figure, before
                    USD conversion.
                  type:
                    - string
                    - 'null'
                  example: USD
                local_currency_entity:
                  description: >-
                    The local currency of the entity-direct source figure,
                    before USD conversion.
                  type:
                    - string
                    - 'null'
                  example: USD
                local:
                  description: >-
                    Recommended annual revenue in local currency, matching
                    `usd`.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                local_entity:
                  description: Entity-direct annual revenue in local currency.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                consolidated_local:
                  description: Consolidated revenue in local currency.
                  type:
                    - number
                    - 'null'
                  example: 16000000000
                consolidated_currency:
                  description: >-
                    The currency of the consolidated source figure, before USD
                    conversion.
                  type:
                    - string
                    - 'null'
                  example: USD
                reasoning:
                  description: Explanation of how the revenue figure was determined.
                  type:
                    - string
                    - 'null'
                  example: Revenue sourced from audited annual financial statements.
                source:
                  description: >-
                    Source of the revenue data. One of: `identified`,
                    `estimated`.
                  type:
                    - string
                    - 'null'
                  enum:
                    - identified
                    - estimated
                    - null
                  example: identified
    Address:
      type: object
      properties:
        street:
          description: Street address.
          type:
            - string
            - 'null'
          example: 354 Oyster Point Blvd
        city:
          description: City.
          type:
            - string
            - 'null'
          example: South San Francisco
        state:
          description: State or province.
          type:
            - string
            - 'null'
          example: California
        country:
          description: Country.
          type:
            - string
            - 'null'
          example: United States
        postcode:
          description: ZIP or postal code.
          type:
            - string
            - 'null'
          example: '94080'
        reasoning:
          description: Explanation of how the address was determined.
          type:
            - string
            - 'null'
          example: Address derived from company registration records.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Include your API key in the x-api-key header.

````