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

# Resolve parent

> Starts a parent hierarchy resolution job for a resolved entity. Returns immediately with an `id` — poll `GET /v1/resolve-parent/{job_id}` until the status is `completed`.

Starts a parent hierarchy resolution job for a resolved entity. Returns immediately with an `id` — poll `GET /v1/resolve-parent/{job_id}` until the status is `completed`.

Use the `kernel_id` from a previous [Resolve entity](/api-reference/endpoint/create-entity-resolution) call.

## Examples

### Resolve the parent hierarchy for an entity

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

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

### With webhook callback

```bash curl theme={null}
curl -X POST https://api.kernel.ai/rest/v1/resolve-parent \
  -H "x-api-key: $KERNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kernel_id": "6347422643",
    "webhook_url": "https://example.com/webhooks/kernel"
  }'
```

```json Response (202) 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                                   |
| `webhook_url` | `string` | No       | HTTPS URL to receive webhook callbacks when the job completes or fails |

## Polling for results

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

## Related endpoints

* [Get resolve parent result](/api-reference/endpoint/get-resolve-parent) — Poll for job status and results


## OpenAPI

````yaml POST /v1/resolve-parent
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/resolve-parent:
    post:
      tags:
        - Parentage
      summary: Resolve parent
      description: >-
        Starts a parent hierarchy resolution job for a resolved entity. Returns
        immediately with an `id` — poll `GET /v1/resolve-parent/{job_id}` until
        the status is `completed`.
      operationId: resolveParent
      requestBody:
        description: The entity to resolve parent hierarchy for.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveParentRequest'
            examples:
              minimal:
                summary: Minimal — kernel_id only
                value:
                  kernel_id: '6347422643'
              with_webhook:
                summary: With webhook callback
                value:
                  kernel_id: '6347422643'
                  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:
    ResolveParentRequest:
      type: object
      required:
        - kernel_id
      properties:
        kernel_id:
          description: The kernel_id of a resolved entity.
          type: string
          example: '6347422643'
        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.

````