Enrich firmographics

POST

firmographics

curl --request POST \
  --url https://api.kernel.ai/rest/v1/firmographics \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "kernel_id": "2532551796"
}
'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

{
  "error": "kernel_id is required"
}

{
  "message": "Forbidden"
}

{
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

{
  "error": "Internal processing error."
}

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 to enrich the entity with operational status, location, headcount, and revenue data.

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.

Examples

Enrich a resolved entity

curl

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"}'

Response (202)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

Response (202) — with webhook

{
  "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 with exponential backoff (start at 2 seconds, max 30 seconds). For the full firmographic result schema, see Firmographic result.

Get firmographic enrichment job — Poll for job status and results
Resolve entity — Resolve an entity first to get a kernel_id

Authorizations

x-api-key

string

header

required

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

Body

application/json

The entity to enrich with firmographic data.

kernel_id

string

required

The kernel_id of a resolved entity to enrich with firmographic data.

Example:

"2532551796"

webhook_url

string<uri>

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.

Pattern: ^https://

Example:

"https://example.com/webhooks/kernel"

Response

Job created

string

required

Unique identifier for the created job.

Example:

"550e8400-e29b-41d4-a716-446655440000"

status

enum<string>

required

Initial status of the job.

Available options:

processing

Get firmographic enrichment resultReturns the status and result of a firmographic enrichment job. When `status` is `completed`, the `record` field contains the enriched firmographic data.

curl --request POST \
  --url https://api.kernel.ai/rest/v1/firmographics \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "kernel_id": "2532551796"
}
'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

{
  "error": "kernel_id is required"
}

{
  "message": "Forbidden"
}

{
  "error": "Rate limit exceeded. Retry after 60 seconds."
}

{
  "error": "Internal processing error."
}

Getting started

API reference

API keys & Webhooks

Enrich firmographics

Examples

Enrich a resolved entity

Request body

Polling for results

Authorizations

Body

Response

​Examples

​Enrich a resolved entity

​Request body

​Polling for results

​Related endpoints

Authorizations

Body

Response

Examples

Enrich a resolved entity

Request body

Polling for results

Related endpoints