> ## 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 entity > Starts an entity resolution job for a company. Returns immediately with an `id` — poll `GET /v1/entity-resolution/{job_id}` until the status is `completed`. Submit a company to resolve its identity. The endpoint returns `202` with an `id` — use it to poll the [Get entity resolution result](/api-reference/endpoint/get-entity-resolution) endpoint until the status is `completed`. No fields are required, but providing at least one identifying field improves resolution accuracy. ## Examples ### Minimal — legal name only ```bash curl theme={null} curl -X POST https://api.kernel.ai/rest/v1/entity-resolution \ -H "x-api-key: $KERNEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"legal_name": "Stripe"}' ``` ```json Response (202) theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing" } ``` ### Full — all fields ```bash curl theme={null} curl -X POST https://api.kernel.ai/rest/v1/entity-resolution \ -H "x-api-key: $KERNEL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "legal_name": "Stripe, Inc.", "trading_name": "Stripe", "website": "https://stripe.com", "match_to_linkedin": true, "identity_bias": "NAME_BIAS", "country": "US", "city": "South San Francisco", "state": "CA", "postal_code": "94070", "email": "info@stripe.com", "external_id": "stripe-001", "webhook_url": "https://example.com/webhooks/kernel" }' ``` ```json Response (202) theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing" } ``` ## Input fields All fields are optional. Provide as many as available to improve resolution accuracy. | Field | Type | Description | | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `legal_name` | string | Registered legal name of the company (e.g. `"Stripe, Inc."`) | | `trading_name` | string | Primary brand or trading name (e.g. `"Stripe"`) | | `website` | string | Company website URL | | `country` | string | Country name or ISO 3166-1 alpha-2 code | | `city` | string | City | | `state` | string | State or province | | `postal_code` | string | ZIP or postal code | | `address` | string | Street address | | `email` | string | Email address | | `external_id` | string | Your own identifier for this record. Echoed back on `record.external_id` in the completed result. | | `match_to_linkedin` | boolean | When `true`, Kernel matches the resolved entity to a LinkedIn company profile. Result appears in the `linkedin` field. Defaults to `false` | | `identity_bias` | string | Bias the resolver toward name or URL matching when they conflict. One of: `NAME_BIAS`, `URL_BIAS`. Defaults to `URL_BIAS` | | `webhook_url` | string | HTTPS URL to receive webhook callbacks when the job completes or fails | ## Input normalization You do not need to clean or normalize inputs before sending them: * Company names are case-insensitive — `"ACME CORP"`, `"Acme Corp"`, and `"acme corp"` are equivalent * Common suffixes like `Inc.`, `LLC`, `Ltd.`, `GmbH` are handled automatically * Website URLs are normalized — `"acme.com"` and `"https://www.acme.com/"` resolve the same way * Country accepts both codes (`"US"`) and full names (`"United States"`) ## OpenAPI ````yaml POST /v1/entity-resolution 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: post: tags: - Entity Resolution summary: Resolve entity description: >- Starts an entity resolution job for a company. Returns immediately with an `id` — poll `GET /v1/entity-resolution/{job_id}` until the status is `completed`. operationId: resolveEntity requestBody: description: >- Company to resolve. All fields are optional — provide as many as available for better accuracy. content: application/json: schema: $ref: '#/components/schemas/EntityResolutionRequest' examples: minimal: summary: Minimal — legal name only value: legal_name: Stripe full: summary: Full — all fields value: legal_name: Stripe, Inc. trading_name: Stripe website: https://stripe.com linkedin_url: https://linkedin.com/company/stripe country: US city: South San Francisco state: CA postal_code: '94070' address: 354 Oyster Point Blvd email: info@stripe.com external_id: stripe-001 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 invalid field values content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_json: summary: Malformed JSON value: error: Unexpected token '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: 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 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. ````