> ## 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 entity resolution result > Returns the status and result of an entity resolution job. When `status` is `completed`, the `record` object contains the resolved entity data. Poll this endpoint with the `id` returned by [Resolve entity](/api-reference/endpoint/create-entity-resolution) to check the status and retrieve the result. ## 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 resolved identity with confidence levels and structured legal and trading information. If you included an `external_id` in the original request, it is echoed back on `record.external_id` so you can correlate the result with the record you submitted. For pending or processing jobs, `record` is absent. 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/entity-resolution/550e8400-e29b-41d4-a716-446655440000 \ -H "x-api-key: $KERNEL_API_KEY" ``` ```json Response (200) — completed theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "created_at": "2025-06-05T12:00:00Z", "completed_at": "2025-06-05T12:00:05Z", "record": { "kernel_id": "6347422643", "identity_type": "legal_entity", "identity_resolution_confidence": "HIGH", "identity_resolution_reasoning": "Company identified as Stripe, Inc. via legal name, website, and country alignment. Official Stripe entity confirmed via terms page.", "legal_info": { "country": "US", "reasoning": "Confirmed via Stripe terms of service page.", "trading_name": "Stripe", "confidence": "HIGH", "legal_name": "Stripe, Inc.", "website": "https://stripe.com" }, "trading_info": { "country": "US", "website": "https://stripe.com", "reasoning": "Primary brand site confirmed via domain ownership.", "trading_name": "Stripe", "confidence": "HIGH" }, "entity_classification": { "type": "Company", "subtype": "Operating", "reasoning": "Classified as an operating company based on commercial activity." }, "external_id": "stripe-001" } } ``` ```json Response (200) — still processing theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing", "created_at": "2025-06-05T12:00:00Z" } ``` ```json Response (200) — failed theme={null} { "jobid": "550e8400-e29b-41d4-a716-446655440000", "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" } ``` ## 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" }`. ### Polling example ```typescript TypeScript theme={null} const API_KEY = "your_api_key"; const BASE_URL = "https://api.kernel.ai/rest"; const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" }; async function resolveEntity(input: Record): Promise { const res = await fetch(`${BASE_URL}/v1/entity-resolution`, { method: "POST", headers, body: JSON.stringify(input), }); if (!res.ok) throw new Error(`POST failed: ${res.status}`); const data = await res.json(); return data.id; } async function pollResult(id: string, timeoutMs = 120_000): Promise> { const start = Date.now(); let interval = 2000; while (Date.now() - start < timeoutMs) { const res = await fetch(`${BASE_URL}/v1/entity-resolution/${id}`, { headers }); if (!res.ok) throw new Error(`GET failed: ${res.status}`); const data: Record = await res.json(); if (data.status === "completed") return data.record as Record; if (data.status === "failed") throw new Error("Job failed — retry with more identifying fields"); await new Promise((r) => setTimeout(r, interval)); interval = Math.min(interval * 2, 30_000); } throw new Error(`Job ${id} did not complete within ${timeoutMs / 1000}s`); } const id = await resolveEntity({ legal_name: "Stripe, Inc.", website: "https://stripe.com", country: "US" }); const result = await pollResult(id); console.log(result.identity_type); // "legal_entity" ``` For the full `IdentityResult` schema, see [Completed result](/api-reference/schemas/entity-resolution-result). ## OpenAPI ````yaml GET /v1/entity-resolution/{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/entity-resolution/{job_id}: get: tags: - Entity Resolution summary: Get entity resolution result description: >- Returns the status and result of an entity resolution job. When `status` is `completed`, the `record` object contains the resolved entity data. operationId: getEntityResolution parameters: - name: job_id in: path description: Job ID returned by the POST endpoint required: true schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 responses: '200': description: Job status response content: application/json: schema: $ref: '#/components/schemas/EntityResolutionJobStatus' examples: completed: summary: Completed — resolved value: id: 550e8400-e29b-41d4-a716-446655440000 status: completed created_at: '2025-06-05T12:00:00Z' completed_at: '2025-06-05T12:00:05Z' record: kernel_id: '6347422643' identity_type: legal_entity identity_resolution_confidence: HIGH identity_resolution_reasoning: >- Company identified as Stripe, Inc. via legal name, website, and country alignment. legal_info: country: US reasoning: Confirmed via Stripe terms of service page. trading_name: Stripe confidence: HIGH legal_name: Stripe, Inc. website: https://stripe.com trading_info: country: US website: https://stripe.com reasoning: Primary brand site confirmed via domain ownership. trading_name: Stripe confidence: HIGH entity_classification: type: Company subtype: Operating reasoning: >- Classified as an operating company based on commercial activity. processing: summary: Still processing value: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: processing created_at: '2025-06-05T12:00:00Z' processing_with_subprocesses: summary: Processing with nested subprocess status value: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: processing created_at: '2025-06-05T12:00:00Z' subprocesses: entity-resolution: completed resolve-parent: processing firmographics: pending pending: summary: Unknown or not yet created value: status: pending failed: summary: Failed value: jobid: 550e8400-e29b-41d4-a716-446655440000 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: EntityResolutionJobStatus: title: Entity resolution required: - status type: object properties: id: description: >- Unique identifier for the job. Present when `status` is `pending`, `processing`, or `completed`. type: string example: 550e8400-e29b-41d4-a716-446655440000 jobid: description: >- Unique identifier for the job. Present only when `status` is `failed`. type: string example: 550e8400-e29b-41d4-a716-446655440000 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/EntityResolutionResult' description: Result payload. 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 EntityResolutionResult: required: - identity_type - identity_resolution_confidence - identity_resolution_reasoning - legal_info - trading_info type: object properties: kernel_id: description: >- A 10-digit unique identifier for the resolved entity in Kernel's database. The same company always resolves to the same kernel_id. Null when the entity could not be determined. type: - string - 'null' example: '6347422643' identity_type: description: The resolved identity classification. type: string enum: - legal_entity - trading_entity identity_resolution_confidence: description: Overall confidence in the identity resolution. type: string enum: - HIGH - MEDIUM - LOW identity_resolution_reasoning: description: >- A brief explanation of why the entity was identified as this account. type: string legal_info: $ref: '#/components/schemas/LegalInfo' description: Information about the legal entity. trading_info: $ref: '#/components/schemas/TradingInfo' description: Information about the trading identity. entity_classification: description: >- Classification of the resolved entity by industry/domain. Null when classification is unavailable. oneOf: - type: 'null' - $ref: '#/components/schemas/EntityClassification' linkedin: description: >- LinkedIn company profile match. Only present when `match_to_linkedin` was set to `true` in the request. oneOf: - type: 'null' - $ref: '#/components/schemas/LinkedIn' external_id: description: >- Echoed back from your request. Present only when you included an `external_id` in the submitted record. Use it to correlate this result with the record you sent. type: string example: stripe-001 LegalInfo: type: object required: - country - reasoning - trading_name - confidence - legal_name - website properties: country: description: Country of the legal entity. type: - string - 'null' example: US reasoning: description: Explanation of how the legal entity was identified. type: string example: Confirmed via Stripe terms of service page. trading_name: description: Trading name associated with the legal entity. type: - string - 'null' example: Stripe, Inc. confidence: description: Confidence in the legal entity info. type: string enum: - HIGH - MEDIUM - LOW legal_name: description: Registered legal name. type: - string - 'null' example: Stripe, Inc. website: description: Official URL of the legal entity. type: - string - 'null' example: https://stripe.com TradingInfo: type: object required: - country - website - reasoning - trading_name - confidence properties: country: description: Country of the trading entity's operational region. type: - string - 'null' example: US website: description: Primary trading website URL. type: - string - 'null' example: https://stripe.com reasoning: description: Explanation of how the trading identity was identified. type: string example: Primary brand site confirmed via domain ownership. trading_name: description: Primary trading name. type: - string - 'null' example: Stripe confidence: description: Confidence in the trading identity info. type: string enum: - HIGH - MEDIUM - LOW EntityClassification: type: object required: - type - subtype properties: type: description: 'Entity category. One of: Company, Government, Education.' type: string example: Company subtype: description: >- Entity sub-category. E.g. Operating, HoldCo/Investment, Business Unit, Establishment. type: string example: Operating reasoning: description: Explanation of the classification. type: - string - 'null' example: Classified as an operating company based on commercial activity. LinkedIn: type: object properties: url: description: Full LinkedIn company profile URL. type: - string - 'null' example: https://www.linkedin.com/company/stripe slug: description: Company slug extracted from the LinkedIn URL. type: - string - 'null' example: stripe match_type: description: >- How the LinkedIn profile was matched. `actual` is a verified direct match; `indicative` is a best-guess match; `none` when no match was found. type: string enum: - actual - indicative - none reasoning: description: Explanation of how the LinkedIn match was determined. type: - string - 'null' example: Matched via verified website domain stripe.com. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: Include your API key in the x-api-key header. ````