> ## 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. # Combined > Starts an entity resolution job and then runs one or more follow-up enrichments. Returns immediately with an `id` — poll `GET /v1/combined/{job_id}` until the status is `completed`. When both follow-ups are requested, they run in parallel after entity resolution completes. Starts an entity resolution job and then runs one or more follow-up enrichments in one request. Use `jobs: ["firmographics"]` to resolve an entity and then enrich it with operational status, location, headcount, and revenue data. Use `jobs: ["resolve-parent"]` to resolve an entity and then look up its parent and top-parent hierarchy. Use `jobs: ["resolve-parent", "firmographics"]` to run the full bundle — the two follow-ups run in parallel after entity resolution completes. The endpoint accepts the same entity-resolution inputs as [`POST /v1/entity-resolution`](/api-reference/endpoint/create-entity-resolution), plus a required `jobs` array that selects the follow-up enrichment(s). This is an async operation. Poll [`GET /v1/combined/{job_id}`](/api-reference/endpoint/get-combined) until `status` is `completed`, or provide a `webhook_url` to receive a callback. ## Credit usage Credits are charged for entity resolution plus each follow-up that runs: | Bundle | Cost | | -------------------------------------------------- | --------- | | Entity resolution + resolve parent | 3 credits | | Entity resolution + firmographics | 3 credits | | Entity resolution + resolve parent + firmographics | 5 credits | If entity resolution does not find a match, the follow-up cost(s) are refunded automatically and the job completes with `kernel_id: null`, the requested follow-up fields set to `null`, and `identity_resolution_reasoning` explaining the resolution attempt. ## Examples ### Resolve then resolve parent ```bash curl theme={null} curl -X POST https://api.kernel.ai/rest/v1/combined \ -H "x-api-key: $KERNEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jobs": ["resolve-parent"], "website": "stripe.com"}' ``` ### Resolve then enrich firmographics ```bash curl theme={null} curl -X POST https://api.kernel.ai/rest/v1/combined \ -H "x-api-key: $KERNEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jobs": ["firmographics"], "website": "stripe.com"}' ``` ### Resolve, resolve parent, then enrich firmographics ```bash curl theme={null} curl -X POST https://api.kernel.ai/rest/v1/combined \ -H "x-api-key: $KERNEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"jobs": ["resolve-parent", "firmographics"], "website": "stripe.com"}' ``` All three requests return the same immediate response: ```json Response (202) theme={null} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "processing" } ``` ## Request body | Field | Type | Required | Description | | ------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------- | | `jobs` | `string[]` | Yes | Follow-up job(s): `["firmographics"]`, `["resolve-parent"]`, or `["resolve-parent", "firmographics"]` | | `legal_name` | `string` | No\* | Registered legal name | | `trading_name` | `string` | No\* | Brand or trading name | | `website` | `string` | No\* | Company website URL | | `country` | `string` | No\* | Country name or ISO code | | `city` | `string` | No\* | City | | `state` | `string` | No\* | State or province | | `postal_code` | `string` | No\* | ZIP or postal code | | `address` | `string` | No\* | Street address | | `email` | `string` | No\* | Contact email | | `phone` | `string` | No\* | Contact phone | | `external_id` | `string` | No\* | Your internal identifier. Echoed back on `record.external_id` in the completed result. | | `match_to_linkedin` | `boolean` | No | Also match the company's LinkedIn profile | | `identity_bias` | `string` | No | `"NAME_BIAS"` or `"URL_BIAS"` | | `webhook_url` | `string` | No | HTTPS URL for completion/failure callbacks | \*At least one identifying field is required. ## Polling for results After receiving an `id`, poll [`GET /v1/combined/{job_id}`](/api-reference/endpoint/get-combined) with exponential backoff. ## Related endpoints * [`GET /v1/combined/{job_id}`](/api-reference/endpoint/get-combined) — Poll for results * [`POST /v1/entity-resolution`](/api-reference/endpoint/create-entity-resolution) — Resolve an entity only * [`POST /v1/firmographics`](/api-reference/endpoint/get-firmographics) — Enrich an already-resolved entity * [`POST /v1/resolve-parent`](/api-reference/endpoint/resolve-parent) — Resolve parentage for an already-resolved entity ## OpenAPI ````yaml POST /v1/combined 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/combined: post: tags: - Combined summary: Combined description: >- Starts an entity resolution job and then runs one or more follow-up enrichments. Returns immediately with an `id` — poll `GET /v1/combined/{job_id}` until the status is `completed`. When both follow-ups are requested, they run in parallel after entity resolution completes. operationId: combined requestBody: description: Company to resolve and the follow-up job(s) to run. content: application/json: schema: $ref: '#/components/schemas/CombinedRequest' examples: resolve_parent: summary: Resolve then resolve parent value: jobs: - resolve-parent website: stripe.com firmographics: summary: Resolve then enrich firmographics value: jobs: - firmographics website: stripe.com full_bundle: summary: Resolve, resolve parent, then enrich firmographics value: jobs: - resolve-parent - firmographics website: stripe.com 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/invalid jobs content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- jobs is required and must contain one or more of 'firmographics' or 'resolve-parent' '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: CombinedRequest: allOf: - $ref: '#/components/schemas/EntityResolutionRequest' - type: object required: - jobs properties: jobs: description: Follow-up enrichment jobs to run after entity resolution. type: array minItems: 1 uniqueItems: true items: type: string enum: - firmographics - resolve-parent example: - resolve-parent - firmographics 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 EntityResolutionRequest: type: object properties: legal_name: description: Registered legal name of the company (e.g. "Stripe, Inc.") type: string minLength: 1 example: Stripe, Inc. trading_name: description: Primary brand or trading name (e.g. "Stripe") type: string minLength: 1 example: Stripe website: description: Company website URL. type: string minLength: 1 example: https://stripe.com country: description: Country name or ISO 3166-1 alpha-2 code. type: string minLength: 1 example: US city: description: City. type: string minLength: 1 example: South San Francisco state: description: State or province. type: string minLength: 1 example: CA postal_code: description: ZIP or postal code. type: string minLength: 1 example: '94070' address: description: Street address. type: string minLength: 1 example: 354 Oyster Point Blvd email: description: Email address. Only the domain portion is used for matching. type: string minLength: 1 example: info@stripe.com phone: description: Phone number. Used as an additional signal for entity resolution. type: string minLength: 1 example: +1 555-555-5555 external_id: description: Your own identifier for this record. type: string minLength: 1 example: stripe-001 kernel_id: description: >- An existing Kernel ID. When provided, the resolver skips matching and returns the canonical record for this entity. type: string minLength: 1 example: '6347422643' linkedin_url: description: >- LinkedIn URL for the company (e.g. "https://linkedin.com/company/stripe"). Used as an additional signal for entity resolution. type: string minLength: 1 example: https://linkedin.com/company/stripe match_to_linkedin: description: >- When `true`, Kernel will attempt to match the resolved entity to a LinkedIn company profile. The result is returned in the `linkedin` field of the completed record. Defaults to `false`. type: boolean default: false example: true identity_bias: description: >- Bias the resolver toward name or URL matching when they conflict. One of: `NAME_BIAS`, `URL_BIAS`. Defaults to `URL_BIAS`. type: string enum: - NAME_BIAS - URL_BIAS 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 securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Include your API key in the x-api-key header. ````