Skip to main content
POST
/
v1
/
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"
}
'
{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}
Starts a firmographic enrichment job for a resolved entity. Returns immediately with a job 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 jobId 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)
{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}
Response (202) — with webhook
{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

​
Request body

FieldTypeRequiredDescription
kernel_idstringYesThe kernel_id of a resolved entity to enrich
webhook_urlstringNoHTTPS URL to receive a callback when the job completes or fails

​
Polling for results

After receiving a jobId, poll Get firmographic enrichment job with exponential backoff (start at 2 seconds, max 30 seconds). For the full firmographic result schema, see Firmographic result.

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

​
jobId
string
required

Unique identifier for the created job.

Example:

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

​
status
enum<string>

Initial status of the job.

Available options:
processing