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

# Get resolve parent result

> Returns the status and result of a parent hierarchy resolution job. When `status` is `completed`, the `record` object contains the parent hierarchy data.

Poll this endpoint to check the status and retrieve the result of a parent hierarchy resolution job.

## Status lifecycle

Jobs progress linearly to a terminal state:

```
pending → processing → completed | failed
```

Once a job reaches `completed` or `failed`, the status does not change.

## Result structure

When `status` is `completed`, the `record` field contains the parent hierarchy data with `parent`, `top_parent`, `top_operating_parent` (conditionally present), and `regional_subsidiary`.

For pending or processing jobs, only `status` is returned. For failed jobs, `record` is absent and `error_message` with `error_type` are present instead.

## Example

```bash curl theme={null}
curl https://api.kernel.ai/rest/v1/resolve-parent/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "x-api-key: $KERNEL_API_KEY"
```

```json Response (200) — completed, parent found theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "record": {
    "kernel_id": "6347422643",
    "parent": {
      "kernel_id": "7944166432",
      "trading_name": "Alphabet Inc.",
      "legal_name": "Alphabet Inc.",
      "website": "https://abc.xyz",
      "country": "US",
      "entity_category": "Company",
      "entity_sub_category": "HoldCo/Investment",
      "reasoning": "Google LLC is a wholly-owned subsidiary of Alphabet Inc., its parent holding company.",
      "confidence": "HIGH"
    },
    "top_parent": {
      "kernel_id": "7944166432",
      "trading_name": "Alphabet Inc.",
      "legal_name": "Alphabet Inc.",
      "website": "https://abc.xyz",
      "country": "US",
      "entity_category": "Company",
      "entity_sub_category": "HoldCo/Investment",
      "confidence": "HIGH"
    },
    "top_operating_parent": {
      "kernel_id": "6347422643",
      "trading_name": "Google",
      "legal_name": "Google LLC",
      "website": "https://google.com",
      "country": "US",
      "entity_category": "Company",
      "entity_sub_category": "Operating",
      "confidence": "HIGH"
    },
    "regional_subsidiary": {
      "is_regional": false,
      "regional_scope": null,
      "reasoning": null
    }
  }
}
```

```json Response (200) — completed, no parent (standalone entity) theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "record": {
    "kernel_id": "6347422643",
    "parent": null,
    "top_parent": {
      "kernel_id": "6347422643",
      "trading_name": "Stripe",
      "legal_name": "Stripe, Inc.",
      "website": "https://stripe.com",
      "country": "US",
      "entity_category": "Company",
      "entity_sub_category": "Operating",
      "confidence": null
    },
    "top_operating_parent": {
      "kernel_id": "6347422643",
      "trading_name": "Stripe",
      "legal_name": "Stripe, Inc.",
      "website": "https://stripe.com",
      "country": "US",
      "entity_category": "Company",
      "entity_sub_category": "Operating",
      "confidence": null
    },
    "regional_subsidiary": {
      "is_regional": false,
      "regional_scope": null,
      "reasoning": null
    }
  }
}
```

```json Response (200) — pending theme={null}
{
  "status": "pending"
}
```

```json Response (200) — failed theme={null}
{
  "jobid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "created_at": "2025-06-05T12:00:00Z",
  "completed_at": "2025-06-05T12:00:05Z",
  "error_message": "Entity not found",
  "error_type": "kernel_id_not_found"
}
```

## Response fields

### `record.parent`

`object | null` — The immediate parent entity. `null` when the entity has no parent (standalone).

| Field                 | Type             | Description                                                                                            |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `kernel_id`           | `string`         | Kernel ID of the parent entity                                                                         |
| `trading_name`        | `string \| null` | Parent trading name                                                                                    |
| `legal_name`          | `string \| null` | Parent registered legal name                                                                           |
| `website`             | `string \| null` | Parent company website URL                                                                             |
| `country`             | `string \| null` | Parent country (ISO 3166-1 alpha-2 or full name)                                                       |
| `entity_category`     | `string \| null` | Parent entity category. One of: `Company`, `Government`, `Education`                                   |
| `entity_sub_category` | `string \| null` | Parent entity sub-category. One of: `Operating`, `HoldCo/Investment`, `Business Unit`, `Establishment` |
| `reasoning`           | `string \| null` | Explanation of why this entity was identified as the parent                                            |
| `confidence`          | `string \| null` | Confidence in the parent identification. One of: `HIGH`, `MEDIUM`, `LOW`                               |

### `record.top_parent`

`object | null` — The ultimate parent entity at the top of the corporate hierarchy. For standalone entities, `top_parent` points to the entity itself and `parent` is `null`. Has the same fields as `parent` except it does not include `reasoning` (only `confidence`).

### `record.top_operating_parent`

`object | null` — The topmost operating company (excluding HoldCo/investment vehicles) found by looking up the corporate hierarchy from the queried entity.

This field is **conditionally present**:

* **Present** when the entity is an operating company or when an operating company is found above it in the hierarchy
* **Omitted** for standalone entities that are not operating companies (e.g. HoldCos with no tree)

When present, the value is `null` if no operating company exists in the upward chain (e.g. a HoldCo whose entire parent chain consists of other HoldCos).

Has the same fields as `top_parent` (no `reasoning`, includes `confidence`).

### `record.regional_subsidiary`

`object` — Whether the queried entity operates as a regional subsidiary of its parent.

| Field            | Type              | Description                                                                                                                                   |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `is_regional`    | `boolean \| null` | `true` if the entity is a regional subsidiary, `false` if not. `null` when not yet determined.                                                |
| `regional_scope` | `string \| null`  | The country scope of the regional operation (e.g. `"United States"`, `"India"`). `null` when not a regional subsidiary or not yet determined. |
| `reasoning`      | `string \| null`  | Explanation of the regional subsidiary classification                                                                                         |

## Polling guidance

* Use exponential backoff between polls (start at 2 seconds, cap at 30 seconds).
* Jobs that do not exist yet (or whose ID is unknown) return `{ "status": "pending" }`.

## Related endpoints

* [Resolve parent](/api-reference/endpoint/resolve-parent) — Start a parent hierarchy resolution job


## OpenAPI

````yaml GET /v1/resolve-parent/{job_id}
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/{job_id}:
    get:
      tags:
        - Parentage
      summary: Get resolve parent result
      description: >-
        Returns the status and result of a parent hierarchy resolution job. When
        `status` is `completed`, the `record` object contains the parent
        hierarchy data.
      operationId: getResolveParent
      parameters:
        - name: job_id
          in: path
          description: Job ID returned by the POST endpoint
          required: true
          schema:
            type: string
            example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Job status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveParentJobStatus'
              examples:
                completed:
                  summary: Completed — parent found
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: completed
                    created_at: '2025-06-05T12:00:00Z'
                    completed_at: '2025-06-05T12:00:05Z'
                    record:
                      kernel_id: '6347422643'
                      parent:
                        kernel_id: '7944166432'
                        trading_name: Alphabet Inc.
                        legal_name: Alphabet Inc.
                        website: https://abc.xyz
                        country: US
                        entity_category: Company
                        entity_sub_category: HoldCo/Investment
                        reasoning: >-
                          Google LLC is a wholly-owned subsidiary of Alphabet
                          Inc., its parent holding company.
                        confidence: HIGH
                      top_parent:
                        kernel_id: '7944166432'
                        trading_name: Alphabet Inc.
                        legal_name: Alphabet Inc.
                        website: https://abc.xyz
                        country: US
                        entity_category: Company
                        entity_sub_category: HoldCo/Investment
                        reasoning: >-
                          Alphabet Inc. is the ultimate parent in the corporate
                          hierarchy, with no parent of its own.
                        confidence: HIGH
                      regional_subsidiary:
                        is_regional: false
                        regional_scope: null
                        reasoning: null
                completed_no_parent:
                  summary: Completed — no parent (standalone)
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: completed
                    created_at: '2025-06-05T12:00:00Z'
                    completed_at: '2025-06-05T12:00:05Z'
                    record:
                      kernel_id: '6347422643'
                      parent: null
                      top_parent:
                        kernel_id: '6347422643'
                        trading_name: Stripe
                        legal_name: Stripe, Inc.
                        website: https://stripe.com
                        country: US
                        entity_category: Company
                        entity_sub_category: Operating
                        reasoning: null
                        confidence: null
                      regional_subsidiary:
                        is_regional: false
                        regional_scope: null
                        reasoning: null
                processing:
                  summary: Still processing
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: processing
                    created_at: '2025-06-05T12:00:00Z'
                pending:
                  summary: Unknown or not yet created
                  value:
                    status: pending
                failed:
                  summary: Failed
                  value:
                    jobid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: failed
                    created_at: '2025-06-05T12:00:00Z'
                    completed_at: '2025-06-05T12:00:05Z'
        '403':
          description: Forbidden — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
              example:
                message: Forbidden
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Service unavailable
components:
  schemas:
    ResolveParentJobStatus:
      title: Resolve parent
      required:
        - status
      type: object
      properties:
        id:
          description: >-
            Unique identifier for the job. Present when `status` is `pending`,
            `processing`, or `completed`.
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        jobid:
          description: >-
            Unique identifier for the job. Present only when `status` is
            `failed`.
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        status:
          description: >-
            Current status of the job. Terminal states are `completed` and
            `failed`.
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        created_at:
          description: ISO 8601 timestamp when the job was created.
          type: string
          format: date-time
          example: '2025-06-05T12:00:00Z'
        completed_at:
          description: ISO 8601 timestamp when the job reached a terminal state.
          type: string
          format: date-time
          example: '2025-06-05T12:00:05Z'
        record:
          $ref: '#/components/schemas/ResolveParentResponse'
          description: Parent hierarchy data. Present when `status` is `completed`.
        error_message:
          description: Error message. Present when `status` is `failed`.
          type: string
        error_type:
          description: >-
            Machine-readable error type. Present when `status` is `failed`. One
            of: `kernel_id_not_found`, `unknown`.
          type: string
    ForbiddenError:
      required:
        - message
      type: object
      properties:
        message:
          description: Error message from API Gateway.
          type: string
          example: Forbidden
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: Error description.
          type: string
          example: Entity not found
    ResolveParentResponse:
      type: object
      required:
        - kernel_id
        - regional_subsidiary
      properties:
        kernel_id:
          description: The kernel_id of the queried entity.
          type: string
          example: '6347422643'
        parent:
          description: >-
            The immediate parent entity. `null` when the entity has no parent
            (standalone).
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ParentEntity'
        top_parent:
          description: >-
            The ultimate parent entity at the top of the corporate hierarchy.
            For standalone entities, top_parent points to the entity itself and
            parent is null.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ParentEntity'
        top_operating_parent:
          description: >-
            The top operating parent entity in the corporate hierarchy,
            excluding HoldCo/investment vehicles. `null` when the entity is
            standalone or has no operating parent.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ParentEntity'
        regional_subsidiary:
          $ref: '#/components/schemas/RegionalSubsidiary'
          description: Whether the entity operates as a regional subsidiary of its parent.
    ParentEntity:
      type: object
      required:
        - kernel_id
      properties:
        kernel_id:
          description: Kernel ID of the parent entity.
          type: string
          example: '7944166432'
        trading_name:
          description: Parent trading name.
          type:
            - string
            - 'null'
          example: Alphabet Inc.
        legal_name:
          description: Parent registered legal name.
          type:
            - string
            - 'null'
          example: Alphabet Inc.
        website:
          description: Parent company website URL.
          type:
            - string
            - 'null'
          example: https://abc.xyz
        country:
          description: Parent country (ISO 3166-1 alpha-2 or full name).
          type:
            - string
            - 'null'
          example: US
        entity_category:
          description: 'Parent entity category. One of: Company, Government, Education.'
          type:
            - string
            - 'null'
          enum:
            - Company
            - Government
            - Education
            - null
        entity_sub_category:
          description: >-
            Parent entity sub-category. E.g. Operating, HoldCo/Investment,
            Business Unit, Establishment.
          type:
            - string
            - 'null'
          example: HoldCo/Investment
        reasoning:
          description: Explanation of why this entity was identified as the parent.
          type:
            - string
            - 'null'
          example: >-
            Google LLC is a wholly-owned subsidiary of Alphabet Inc., its parent
            holding company.
        confidence:
          description: 'Confidence in the parent identification. One of: HIGH, MEDIUM, LOW.'
          type:
            - string
            - 'null'
          enum:
            - HIGH
            - MEDIUM
            - LOW
            - null
    RegionalSubsidiary:
      type: object
      properties:
        is_regional:
          description: >-
            Whether the entity operates as a regional subsidiary. `null` when
            not yet determined.
          type:
            - boolean
            - 'null'
          example: false
        regional_scope:
          description: >-
            The country scope of the regional operation. `null` when not a
            regional subsidiary or not yet determined.
          type:
            - string
            - 'null'
          example: India
        reasoning:
          description: Explanation of the regional subsidiary classification.
          type:
            - string
            - 'null'
          example: Operates as a regional subsidiary focused on the Indian market.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Include your API key in the x-api-key header.

````