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

# Enrich firmographics

> Starts a firmographic enrichment job for a resolved entity. Returns immediately with an `id` — poll `GET /v1/firmographics/{job_id}` until the status is `completed`.

Starts a firmographic enrichment job for a resolved entity. Returns immediately with an `id` — poll `GET /v1/firmographics/{job_id}` until the status is `completed`.

Use the `kernel_id` returned by [entity resolution](/api-reference/endpoint/create-entity-resolution) to enrich the entity with operational status, location, headcount, and revenue data.

<Note>
  This is an async operation. Use the returned `id` to poll for results, or provide a `webhook_url` to receive a callback when the job completes.
</Note>

## Examples

### Enrich a resolved entity

```bash curl theme={null}
curl -X POST https://api.kernel.ai/rest/v1/firmographics \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kernel_id": "2532551796"}'
```

```json Response (202) theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}
```

```json Response (202) — with webhook theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}
```

## Request body

| Field         | Type     | Required | Description                                                     |
| ------------- | -------- | -------- | --------------------------------------------------------------- |
| `kernel_id`   | `string` | Yes      | The `kernel_id` of a resolved entity to enrich                  |
| `webhook_url` | `string` | No       | HTTPS URL to receive a callback when the job completes or fails |

## Polling for results

After receiving an `id`, poll [Get firmographic enrichment job](/api-reference/endpoint/get-firmographics-job) with exponential backoff (start at 2 seconds, max 30 seconds).

For the full firmographic result schema, see [Firmographic result](/api-reference/schemas/firmographic-result).

## Related endpoints

* [Get firmographic enrichment job](/api-reference/endpoint/get-firmographics-job) — Poll for job status and results
* [Resolve entity](/api-reference/endpoint/create-entity-resolution) — Resolve an entity first to get a kernel\_id


## OpenAPI

````yaml POST /v1/firmographics
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:
    post:
      tags:
        - Firmographics
      summary: Enrich firmographics
      description: >-
        Starts a firmographic enrichment job for a resolved entity. Returns
        immediately with an `id` — poll `GET /v1/firmographics/{job_id}` until
        the status is `completed`.
      operationId: enrichFirmographics
      requestBody:
        description: The entity to enrich with firmographic data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FirmographicRequest'
            examples:
              minimal:
                summary: Minimal — kernel_id only
                value:
                  kernel_id: '2532551796'
              with_webhook:
                summary: With webhook callback
                value:
                  kernel_id: '2532551796'
                  webhook_url: https://example.com/webhooks/kernel
        required: true
      responses:
        '202':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCreatedResponse'
              example:
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                status: processing
        '400':
          description: Invalid request — malformed JSON or missing kernel_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: kernel_id is required
        '403':
          description: Forbidden — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              example:
                message: Forbidden
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Rate limit exceeded. Retry after 60 seconds.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Internal processing error.
components:
  schemas:
    FirmographicRequest:
      type: object
      required:
        - kernel_id
      properties:
        kernel_id:
          description: The kernel_id of a resolved entity to enrich with firmographic data.
          type: string
          example: '2532551796'
        webhook_url:
          description: >-
            HTTPS URL to receive webhook callbacks when the job completes or
            fails. Kernel will POST the job result to this URL with an
            X-Kernel-Signature header for verification.
          type: string
          format: uri
          pattern: ^https://
          example: https://example.com/webhooks/kernel
    JobCreatedResponse:
      required:
        - id
        - status
      type: object
      properties:
        id:
          description: Unique identifier for the created job.
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          description: Initial status of the job.
          type: string
          enum:
            - processing
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: Error description.
          type: string
          example: Entity not found
    ForbiddenError:
      required:
        - message
      type: object
      properties:
        message:
          description: Error message from API Gateway.
          type: string
          example: Forbidden
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Include your API key in the x-api-key header.

````