{ "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" } ], "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": "Crosscheck", "description": "Resolve an entity and run the full CRM crosscheck pass in one call" }, { "name": "LinkedIn Lookup", "description": "Provisional LinkedIn company match jobs (not Kernel-verified)" } ], "security": [ { "apiKeyAuth": [] } ], "paths": { "/v1/entity-resolution": { "post": { "operationId": "resolveEntity", "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`.", "x-mint": { "content": "## Completed result\n\nThis endpoint returns `202` with an `id` immediately. Poll `GET /v1/entity-resolution/{job_id}` until `status` is `completed`, then read the result:\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"status\": \"completed\",\n \"created_at\": \"2025-06-05T12:00:00Z\",\n \"completed_at\": \"2025-06-05T12:00:05Z\",\n \"record\": {\n \"kernel_id\": \"6347422643\",\n \"company_registration\": {\n \"number\": \"01234567\",\n \"country\": \"GB\",\n \"source\": \"request\"\n },\n \"company_registration_number\": \"01234567\",\n \"identity_type\": \"legal_entity\",\n \"identity_resolution_confidence\": \"HIGH\",\n \"legal_info\": {\n \"country\": \"US\",\n \"legal_name\": \"Stripe, Inc.\",\n \"confidence\": \"HIGH\"\n },\n \"trading_info\": {\n \"country\": \"US\",\n \"trading_name\": \"Stripe\",\n \"confidence\": \"HIGH\"\n }\n }\n}\n```\n\nSee the [Completed result](/api-reference/schemas/entity-resolution-result) page for the full schema." }, "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", "company_registration_number": "01234567", "company_registration_country": "GB", "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" } } } } } }, "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." } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/entity-resolution/{job_id}": { "get": { "operationId": "getEntityResolution", "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.", "x-mint": { "content": "## Status lifecycle\n\nJobs follow a linear progression to a terminal state:\n\n```\npending → processing → completed | failed\n```\n\nOnce a job reaches `completed` or `failed`, the status does not change.\n\n## Polling guidance\n\n- Use exponential backoff: start at 2 seconds, double up to 30 seconds.\n- Jobs that do not exist yet (or whose ID is unknown) return `{ \"status\": \"pending\" }`." }, "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", "company_registration": { "number": "01234567", "country": "GB", "source": "request" }, "company_registration_number": "01234567", "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" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Service unavailable" } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/resolve-parent": { "post": { "operationId": "resolveParent", "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`.", "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" } } } }, "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." } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/resolve-parent/{job_id}": { "get": { "operationId": "getResolveParent", "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.", "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" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Service unavailable" } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/firmographics": { "post": { "operationId": "enrichFirmographics", "tags": ["Firmographics"], "summary": "Enrich firmographics", "description": "Starts a firmographic enrichment job for a resolved entity. Returns immediately with an `id` — poll `GET /v1/firmographics/{job_id}` until the status is `completed`.", "requestBody": { "description": "The entity to enrich with firmographic data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmographicRequest" }, "examples": { "minimal": { "summary": "Minimal — kernel_id only", "value": { "kernel_id": "2532551796" } }, "with_webhook": { "summary": "With webhook callback", "value": { "kernel_id": "2532551796", "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" } } } }, "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." } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/firmographics/{job_id}": { "get": { "operationId": "getFirmographicsJob", "tags": ["Firmographics"], "summary": "Get firmographic enrichment result", "description": "Returns the status and result of a firmographic enrichment job. When `status` is `completed`, the `record` field contains the enriched firmographic data.", "parameters": [ { "name": "job_id", "in": "path", "description": "ID of the firmographic enrichment job", "required": true, "schema": { "type": "string", "example": "test-firmo-001" } } ], "responses": { "200": { "description": "Job status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmographicJobStatus" }, "examples": { "completed": { "summary": "Completed — enrichment done", "value": { "id": "test-firmo-001", "status": "completed", "created_at": "2026-06-08T14:00:32.411Z", "completed_at": "2026-06-08T14:53:53.151Z", "record": { "kernel_id": "7944166432", "op_status": { "operational_status": "Active", "reasoning": "Entity is actively operating." }, "location": { "operating": { "street": null, "city": "Singrauli", "state": "Madhya Pradesh", "country": "India", "postcode": "486889", "reasoning": "Address derived from company registration records." }, "registered": { "street": "P.O. Singrauli Colliery", "city": "Singrauli", "state": "Madhya Pradesh", "country": "India", "postcode": "486889", "reasoning": "Address from official registry filing." } }, "headcount": { "count": 13307, "count_consolidated": 13307, "confidence": "HIGH", "reasoning": "Headcount derived from annual report figures." }, "revenue": { "usd": 2613846573, "consolidated_usd": 2613846573, "confidence": "HIGH", "local_currency": "INR", "consolidated_local": 217820547750, "consolidated_currency": "INR", "local": 217820547750, "reasoning": "Revenue sourced from audited annual financial statements.", "source": "identified" } } } }, "pending": { "summary": "Pending — job not yet started", "value": { "status": "pending" } }, "failed": { "summary": "Failed", "value": { "jobid": "test-firmo-001", "status": "failed", "created_at": "2026-06-08T14:00:32.411Z", "completed_at": "2026-06-08T14:00:50.456Z" } } } } } }, "503": { "description": "Service unavailable — database error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Service unavailable" } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/combined": { "post": { "operationId": "combined", "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.", "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'" } } } }, "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." } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/combined/{job_id}": { "get": { "operationId": "getCombined", "tags": ["Combined"], "summary": "Get combined result", "description": "Returns the status and result of a combined job. When `status` is `completed`, the `record` object contains the entity resolution result and the requested enrichment.", "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/CombinedJobStatus" }, "examples": { "completed_firmographics": { "summary": "Completed with firmographics", "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", "company_registration": { "number": "01234567", "country": "GB", "source": "request" }, "company_registration_number": "01234567", "identity_type": "legal_entity", "identity_resolution_confidence": "HIGH", "identity_resolution_reasoning": "Matched by domain and legal name.", "legal_info": { "country": "US", "reasoning": "Confirmed via Stripe terms of service page.", "trading_name": "Stripe, Inc.", "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." }, "firmographics": { "kernel_id": "6347422643", "op_status": { "operational_status": "Active", "reasoning": "Website is live." }, "location": { "operating": { "city": "South San Francisco", "country": "US" } }, "headcount": { "count": 7000 }, "revenue": { "usd": 1000000000 } } } } }, "completed_parentage": { "summary": "Completed with parentage", "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", "company_registration": null, "company_registration_number": null, "identity_type": "legal_entity", "identity_resolution_confidence": "HIGH", "identity_resolution_reasoning": "Matched by domain and legal name.", "legal_info": { "country": "US", "reasoning": "Confirmed via Stripe terms of service page.", "trading_name": "Stripe, Inc.", "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." }, "parentage": { "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 } } } } }, "completed_full_bundle": { "summary": "Completed with firmographics and parentage", "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", "company_registration": null, "company_registration_number": null, "identity_type": "legal_entity", "identity_resolution_confidence": "HIGH", "identity_resolution_reasoning": "Matched by domain and legal name.", "legal_info": { "country": "US", "reasoning": "Confirmed via Stripe terms of service page.", "trading_name": "Stripe, Inc.", "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." }, "firmographics": { "kernel_id": "6347422643", "op_status": { "operational_status": "Active", "reasoning": "Website is live." }, "location": { "operating": { "street": null, "city": "South San Francisco", "state": "California", "country": "United States", "postcode": "94080", "reasoning": "Address derived from company registration records." }, "registered": { "street": "354 Oyster Point Blvd", "city": "South San Francisco", "state": "California", "country": "United States", "postcode": "94080", "reasoning": "Address from official registry filing." } }, "headcount": { "count": 7000, "count_entity": 7000, "count_consolidated": 7000, "confidence": "HIGH", "reasoning": "Headcount derived from annual report figures." }, "revenue": { "usd": 1000000000, "usd_entity": 1000000000, "consolidated_usd": 1000000000, "confidence": "HIGH", "local_currency": "USD", "local_currency_entity": "USD", "local": 1000000000, "local_entity": 1000000000, "consolidated_local": 1000000000, "consolidated_currency": "USD", "reasoning": "Revenue sourced from audited annual financial statements.", "source": "identified" } }, "parentage": { "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 } } } } }, "completed_no_match": { "summary": "Completed — no match 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": null, "company_registration": null, "company_registration_number": null, "identity_resolution_confidence": "HIGH", "identity_resolution_reasoning": "Company identified as Acme Inc. via legal name and website alignment, but no matching entity exists in Kernel's database.", "legal_info": null, "trading_info": null, "entity_classification": null, "firmographics": null, "parentage": 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", "error_message": "Job failed", "error_type": "unknown" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Service unavailable" } } } }, "403": { "description": "Forbidden — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" }, "example": { "message": "Forbidden" } } } } } } }, "/v1/lookup/linkedin": { "post": { "operationId": "submitLinkedInLookup", "tags": ["LinkedIn Lookup"], "summary": "Lookup LinkedIn company", "description": "Starts a provisional LinkedIn company lookup job. Returns immediately with an `id` — poll `GET /v1/lookup/linkedin/{job_id}` until the status is `completed`. Provide at least one of `name`, `website`, or `linkedin_url`. Matching priority: LinkedIn URL → website → name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedInLookupRequest" }, "examples": { "by_linkedin": { "summary": "Lookup by LinkedIn URL", "value": { "linkedin_url": "https://www.linkedin.com/company/stripe" } }, "by_website": { "summary": "Lookup by website", "value": { "website": "stripe.com" } }, "by_name": { "summary": "Lookup by name only (low confidence)", "value": { "name": "Stripe" } } } } } }, "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreatedResponse" }, "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "processing" } } } }, "400": { "description": "Invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key" }, "503": { "description": "Service unavailable" } } } }, "/v1/lookup/linkedin/{job_id}": { "get": { "operationId": "getLinkedInLookupJob", "tags": ["LinkedIn Lookup"], "summary": "Get LinkedIn lookup result", "description": "Poll the status and result of a LinkedIn lookup job submitted via Lookup LinkedIn company.", "parameters": [ { "name": "job_id", "in": "path", "description": "ID of the LinkedIn lookup job", "required": true, "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Job status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedInLookupJobStatus" }, "examples": { "completed": { "summary": "Completed — match found", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "created_at": "2026-06-08T14:00:32.411Z", "completed_at": "2026-06-08T14:00:38.151Z", "record": { "match": { "linkedin_url": "https://www.linkedin.com/company/stripe", "slug": "stripe", "match_method": "website", "confidence": "HIGH" }, "profile": { "linkedin_name": "Stripe", "linkedin_website": "https://stripe.com", "linkedin_headcount": 8000, "linkedin_industry": "Financial Services", "linkedin_country": "United States", "linkedin_company_size_range": "1001-5000", "linkedin_company_type": "Privately Held", "linkedin_locality": "San Francisco, CA", "linkedin_address": null, "linkedin_founded_year": 2010, "linkedin_follower_count": 500000 }, "provenance": { "kernel_approved": false } } } }, "pending": { "summary": "Pending — job not yet started", "value": { "status": "pending" } } } } } }, "401": { "description": "Missing or invalid API key" } } } }, "/v1/crosscheck": { "post": { "operationId": "crosscheck", "tags": ["Crosscheck"], "summary": "Crosscheck", "description": "Resolves a company to a canonical entity, creating it if it is new, then runs the full CRM crosscheck pass on it. Returns immediately with an `id` — poll `GET /v1/crosscheck/{job_id}` until the status is `completed`. The pass covers duplicate detection, corporate hierarchy, operational status, regional-subsidiary classification, and the resulting recommended action.", "requestBody": { "description": "Company to resolve and crosscheck. `external_id` identifies the record in your CRM and is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrosscheckRequest" }, "examples": { "by_external_id": { "summary": "Crosscheck a CRM record", "value": { "external_id": "0014x00001LMZCDAA5", "legal_name": "Stripe, Inc.", "website": "stripe.com" } }, "with_linkedin": { "summary": "Crosscheck and match LinkedIn", "value": { "external_id": "0014x00001LMZCDAA5", "website": "stripe.com", "match_to_linkedin": true } } } } }, "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, missing `external_id`, or no identifying field provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "At least one of legal_name, trading_name, website, or kernel_id is required" } } } }, "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 server error" } } } } } } }, "/v1/crosscheck/{job_id}": { "get": { "operationId": "getCrosscheck", "tags": ["Crosscheck"], "summary": "Get crosscheck result", "description": "Returns the status and result of a crosscheck job. When `status` is `completed`, the `record` object contains the resolved `identity` and the `crosscheck` outcome.", "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/CrosscheckJobStatus" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Job not found" } } } }, "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 server error" } } } } } } } }, "components": { "schemas": { "LinkedInLookupRequest": { "type": "object", "description": "At least one of name, website, or linkedin_url is required.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Company name. Name-only matches are low confidence.", "example": "Stripe" }, "website": { "type": "string", "minLength": 1, "description": "Company website or domain.", "example": "https://stripe.com" }, "linkedin_url": { "type": "string", "minLength": 1, "description": "LinkedIn company URL.", "example": "https://www.linkedin.com/company/stripe" }, "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" } } }, "LinkedInLookupResponse": { "type": "object", "required": ["match", "profile", "provenance"], "properties": { "match": { "type": "object", "required": ["linkedin_url", "slug", "match_method", "confidence"], "properties": { "linkedin_url": { "type": ["string", "null"] }, "slug": { "type": ["string", "null"] }, "match_method": { "type": "string", "enum": ["linkedin_url", "website", "name", "none"] }, "confidence": { "type": "string", "enum": ["HIGH", "MEDIUM", "LOW"] } } }, "profile": { "type": ["object", "null"], "description": "LinkedIn profile fields (prefixed so they are never confused with Kernel firmographics).", "properties": { "linkedin_name": { "type": ["string", "null"] }, "linkedin_website": { "type": ["string", "null"] }, "linkedin_headcount": { "type": ["number", "null"] }, "linkedin_industry": { "type": ["string", "null"] }, "linkedin_country": { "type": ["string", "null"] }, "linkedin_company_size_range": { "type": ["string", "null"], "example": "11-50" }, "linkedin_company_type": { "type": ["string", "null"], "example": "Privately Held" }, "linkedin_locality": { "type": ["string", "null"], "example": "San Francisco, CA" }, "linkedin_address": { "type": ["string", "null"] }, "linkedin_founded_year": { "type": ["number", "null"] }, "linkedin_follower_count": { "type": ["number", "null"] }, "linkedin_description": { "type": ["string", "null"] } } }, "provenance": { "type": "object", "required": ["kernel_approved"], "properties": { "kernel_approved": { "type": "boolean", "enum": [false] } } } } }, "LinkedInLookupJobStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Job identifier, present for non-failed jobs." }, "jobid": { "type": "string", "description": "Job identifier, present instead of id when the job has failed." }, "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "record": { "$ref": "#/components/schemas/LinkedInLookupResponse" }, "error_message": { "type": "string" } } }, "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" }, "company_registration_number": { "description": "Primary incorporation/registration number. The same number can exist in more than one country — pair it with company_registration_country when known.", "type": "string", "minLength": 1, "example": "01234567" }, "company_registration_country": { "description": "Registry jurisdiction for company_registration_number (ISO 3166-1 alpha-2 preferred). England, Scotland, Wales, and Northern Ireland map to GB. Falls back to country when omitted.", "type": "string", "minLength": 1, "example": "GB" }, "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"] } } }, "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" }, "company_registration": { "description": "Structured registration identity (number, registry country, and source) when a registration number is known. Null when unknown.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompanyRegistration" } ] }, "company_registration_number": { "description": "Deprecated. Same value as company_registration.number. Prefer company_registration for number, country, and source. Null when unknown.", "type": ["string", "null"], "example": "01234567", "deprecated": true }, "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": { "description": "Information about the legal entity.", "$ref": "#/components/schemas/LegalInfo" }, "trading_info": { "description": "Information about the trading identity.", "$ref": "#/components/schemas/TradingInfo" }, "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" } } }, "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": { "description": "Result payload. Present when `status` is `completed`.", "$ref": "#/components/schemas/EntityResolutionResult" }, "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" } } }, "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." } } }, "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" } } }, "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": { "description": "Whether the entity operates as a regional subsidiary of its parent.", "$ref": "#/components/schemas/RegionalSubsidiary" } } }, "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": { "description": "Parent hierarchy data. Present when `status` is `completed`.", "$ref": "#/components/schemas/ResolveParentResponse" }, "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" } } }, "FirmographicRequest": { "type": "object", "required": ["kernel_id"], "properties": { "kernel_id": { "description": "The kernel_id of a resolved entity to enrich with firmographic data.", "type": "string", "example": "2532551796" }, "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" } } }, "FirmographicResult": { "required": ["kernel_id", "op_status", "location", "headcount", "revenue"], "type": "object", "properties": { "kernel_id": { "description": "The unique identifier for the entity in Kernel's database.", "type": "string", "example": "2532551796" }, "op_status": { "description": "Operational status of the entity. `null` when not yet determined.", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "operational_status": { "description": "Current operational status.", "type": ["string", "null"], "enum": ["Active", "Out of business", "Absorbed", "Undetermined", null], "example": "Active" }, "reasoning": { "description": "Explanation of how the operational status was determined.", "type": ["string", "null"], "example": "Entity is actively operating with no signs of cessation." } } } ] }, "location": { "description": "Operating and registered addresses. `null` when not yet determined.", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "operating": { "description": "Operating address.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "registered": { "description": "Registered/legal address.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] } } } ] }, "headcount": { "description": "Headcount data. `null` when not yet determined.", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "count": { "description": "Recommended (headline) headcount. Kernel automatically picks the entity-direct or consolidated figure based on entity type; equals `count_entity` or `count_consolidated`.", "type": ["number", "null"], "example": 5300 }, "count_entity": { "description": "Entity-direct headcount, excluding subsidiaries.", "type": ["number", "null"], "example": 5300 }, "count_consolidated": { "description": "Consolidated headcount including subsidiaries.", "type": ["number", "null"], "example": 8150 }, "confidence": { "description": "Confidence in the headcount figure.", "type": ["string", "null"], "enum": ["HIGH", "MEDIUM", "LOW", null] }, "reasoning": { "description": "Explanation of how the headcount was determined.", "type": ["string", "null"], "example": "Headcount derived from annual report figures." } } } ] }, "revenue": { "description": "Revenue data. `null` when not yet determined.", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "usd": { "description": "Recommended (headline) annual revenue in USD. Kernel automatically picks the entity-direct or consolidated figure based on entity type; equals `usd_entity` or `consolidated_usd`.", "type": ["number", "null"], "example": 16000000000 }, "usd_entity": { "description": "Entity-direct annual revenue in USD, excluding subsidiaries.", "type": ["number", "null"], "example": 16000000000 }, "consolidated_usd": { "description": "Consolidated annual revenue in USD including subsidiaries.", "type": ["number", "null"], "example": 16000000000 }, "confidence": { "description": "Confidence in the revenue figure.", "type": ["string", "null"], "enum": ["HIGH", "MEDIUM", "LOW", null] }, "local_currency": { "description": "The local currency of the recommended source figure, before USD conversion.", "type": ["string", "null"], "example": "USD" }, "local_currency_entity": { "description": "The local currency of the entity-direct source figure, before USD conversion.", "type": ["string", "null"], "example": "USD" }, "local": { "description": "Recommended annual revenue in local currency, matching `usd`.", "type": ["number", "null"], "example": 16000000000 }, "local_entity": { "description": "Entity-direct annual revenue in local currency.", "type": ["number", "null"], "example": 16000000000 }, "consolidated_local": { "description": "Consolidated revenue in local currency.", "type": ["number", "null"], "example": 16000000000 }, "consolidated_currency": { "description": "The currency of the consolidated source figure, before USD conversion.", "type": ["string", "null"], "example": "USD" }, "reasoning": { "description": "Explanation of how the revenue figure was determined.", "type": ["string", "null"], "example": "Revenue sourced from audited annual financial statements." }, "source": { "description": "Source of the revenue data. One of: `identified`, `estimated`.", "type": ["string", "null"], "enum": ["identified", "estimated", null], "example": "identified" } } } ] } } }, "FirmographicJobStatus": { "type": "object", "required": ["status"], "properties": { "id": { "description": "Unique identifier for the job. Present when `status` is `pending`, `processing`, or `completed`.", "type": "string", "example": "test-firmo-001" }, "jobid": { "description": "Unique identifier for the job. Present only when `status` is `failed`.", "type": "string", "example": "test-firmo-001" }, "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": "2026-06-08T14:00:32.411Z" }, "completed_at": { "description": "ISO 8601 timestamp when the job reached a terminal state.", "type": "string", "format": "date-time", "example": "2026-06-08T14:53:53.151Z" }, "record": { "description": "Firmographic data. Present when `status` is `completed`.", "$ref": "#/components/schemas/FirmographicResult" }, "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" } } }, "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"] } } } ] }, "CombinedResult": { "type": "object", "required": ["kernel_id", "identity_resolution_confidence", "identity_resolution_reasoning", "legal_info", "trading_info", "entity_classification"], "properties": { "kernel_id": { "description": "The unique identifier for the resolved entity in Kernel's database. `null` when no entity is resolved.", "type": ["string", "null"], "example": "6347422643" }, "company_registration": { "description": "Structured registration identity (number, registry country, and source) when a registration number is known. Null when unknown. Same field as entity resolution.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompanyRegistration" } ] }, "company_registration_number": { "description": "Deprecated. Same value as company_registration.number. Prefer company_registration for number, country, and source. Null when unknown.", "type": ["string", "null"], "example": "01234567", "deprecated": true }, "identity_type": { "description": "Type of identity resolved.", "type": "string", "enum": ["legal_entity", "trading_entity"], "example": "legal_entity" }, "identity_resolution_confidence": { "description": "Confidence that the resolved identity is correct.", "type": "string", "enum": ["HIGH", "MEDIUM", "LOW"] }, "identity_resolution_reasoning": { "description": "Explanation of how the identity was resolved.", "type": "string" }, "legal_info": { "description": "Legal entity information. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LegalInfo" } ] }, "trading_info": { "description": "Trading entity information. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TradingInfo" } ] }, "entity_classification": { "description": "Classification of the entity. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntityClassification" } ] }, "linkedin": { "description": "LinkedIn profile match. Only present when `match_to_linkedin` is true. `null` when entity resolution found no match.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LinkedIn" } ] }, "firmographics": { "description": "Firmographic enrichment result. Present when `jobs` includes `firmographics`. `null` when entity resolution found no match.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FirmographicResult" } ] }, "parentage": { "description": "Parentage result. Present when `jobs` includes `resolve-parent`. `null` when entity resolution found no match.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResolveParentResponse" } ] }, "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" } } }, "CombinedJobStatus": { "type": "object", "required": ["status"], "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": { "description": "Combined entity resolution and enrichment result. Present when `status` is `completed`.", "$ref": "#/components/schemas/CombinedResult" }, "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" } } }, "Address": { "type": "object", "properties": { "street": { "description": "Street address.", "type": ["string", "null"], "example": "354 Oyster Point Blvd" }, "city": { "description": "City.", "type": ["string", "null"], "example": "South San Francisco" }, "state": { "description": "State or province.", "type": ["string", "null"], "example": "California" }, "country": { "description": "Country.", "type": ["string", "null"], "example": "United States" }, "postcode": { "description": "ZIP or postal code.", "type": ["string", "null"], "example": "94080" }, "reasoning": { "description": "Explanation of how the address was determined.", "type": ["string", "null"], "example": "Address derived from company registration records." } } }, "CompanyRegistration": { "type": "object", "required": ["number", "country", "source"], "properties": { "number": { "description": "Registration / national ID.", "type": ["string", "null"], "example": "01234567" }, "country": { "description": "Registry jurisdiction as ISO 3166-1 alpha-2 when known.", "type": ["string", "null"], "example": "GB" }, "source": { "description": "Where the number came from.", "type": ["string", "null"], "enum": ["registry", "companies_house", "request", null] } } }, "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." } } }, "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" } } }, "CrosscheckRequest": { "allOf": [ { "$ref": "#/components/schemas/EntityResolutionRequest" }, { "type": "object", "required": ["external_id"], "properties": { "external_id": { "description": "Your CRM identifier for the record to crosscheck. Required — it selects which account in your dataset the crosscheck pass runs on.", "type": "string", "minLength": 1, "example": "0014x00001LMZCDAA5" } } } ] }, "CrosscheckEntityRef": { "type": "object", "properties": { "kernel_id": { "description": "Kernel identifier for the related entity.", "type": ["string", "null"], "example": "8514783664" }, "external_id": { "description": "Your CRM identifier for the related entity, when it exists in your dataset.", "type": ["string", "null"], "example": "0014x00001TopParentA" } } }, "CrosscheckAction": { "type": "object", "properties": { "action": { "description": "Recommended CRM action. One of `Delete`, `Merge`, `Associate`, `Associate (missing parent)`, or `None`.", "type": ["string", "null"], "example": "Associate" }, "association_type": { "description": "How the account should be associated when `action` is an Associate variant. One of `set_initial_parent`, `reparent`, `create_parent`, or `remove_parent`.", "type": ["string", "null"], "example": "reparent" }, "reasoning": { "description": "Explanation for the recommended action.", "type": ["string", "null"], "example": "Regional entity controlled by the identified operating parent." } } }, "CrosscheckDuplicateMember": { "type": "object", "properties": { "external_id": { "description": "CRM identifier of the duplicate group member.", "type": ["string", "null"], "example": "0014x00001oXQfLAAW" }, "kernel_id": { "description": "Kernel identifier of the duplicate group member.", "type": ["string", "null"], "example": "7643512876" }, "type": { "description": "How this member is linked into the group. `PRIMARY` marks the surviving record; other values describe the match that grouped it (for example `EXACT`, `REGIONAL`, `LOCATION`, `TRADING`, `WEBSITE`).", "type": ["string", "null"], "example": "REGIONAL" }, "reasoning": { "description": "Explanation for this member's inclusion, when available.", "type": ["string", "null"] } } }, "CrosscheckDuplicate": { "type": "object", "properties": { "type": { "description": "How the crosschecked account itself is linked into the duplicate group. `null` when it is not a duplicate.", "type": ["string", "null"], "example": "REGIONAL" }, "reasoning": { "description": "Explanation of the duplicate match.", "type": ["string", "null"] }, "group_id": { "description": "Identifier grouping the accounts considered the same duplicate set.", "type": ["string", "null"], "example": "60498" }, "duplicate_of": { "description": "The surviving or canonical record this account duplicates. `null` when it is not a duplicate.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrosscheckEntityRef" } ] }, "members": { "description": "All accounts in the duplicate group. Empty when the account is not a duplicate.", "type": "array", "items": { "$ref": "#/components/schemas/CrosscheckDuplicateMember" } }, "checked_at": { "description": "ISO 8601 timestamp of the last duplicate check.", "type": ["string", "null"], "example": "2026-07-29T09:14:07.642Z" } } }, "CrosscheckOpStatus": { "type": "object", "properties": { "operational_status": { "description": "Operational status of the entity. One of `Active`, `Out of business`, `Absorbed`, or `Undetermined`.", "type": ["string", "null"], "example": "Active" }, "reasoning": { "description": "Explanation of the operational status.", "type": ["string", "null"], "example": "The company has an active website and current evidence of business operations." } } }, "CrosscheckBlock": { "type": "object", "properties": { "recommended_action": { "$ref": "#/components/schemas/CrosscheckAction" }, "duplicate": { "$ref": "#/components/schemas/CrosscheckDuplicate" }, "op_status": { "$ref": "#/components/schemas/CrosscheckOpStatus" }, "checked_at": { "description": "ISO 8601 timestamp of the last crosscheck run.", "type": ["string", "null"], "example": "2026-07-29T09:14:09.771Z" } }, "description": "The crosscheck outcome for the record: recommended action, duplicate grouping, and operational status. Hierarchy lives under `parentage`." }, "CrosscheckIdentity": { "type": "object", "required": ["identity_resolution_confidence", "identity_resolution_reasoning", "legal_info", "trading_info", "entity_classification"], "properties": { "identity_type": { "description": "Type of identity resolved.", "type": "string", "enum": ["legal_entity", "trading_entity"], "example": "legal_entity" }, "identity_resolution_confidence": { "description": "Confidence that the resolved identity is correct.", "type": "string", "enum": ["HIGH", "MEDIUM", "LOW"] }, "identity_resolution_reasoning": { "description": "Explanation of how the identity was resolved.", "type": "string" }, "company_registration_number": { "description": "Company registration number, when known.", "type": ["string", "null"], "example": "15117085" }, "legal_info": { "description": "Legal entity information. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LegalInfo" } ] }, "trading_info": { "description": "Trading entity information. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TradingInfo" } ] }, "entity_classification": { "description": "Entity type classification. `null` when no entity is resolved.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EntityClassification" } ] } } }, "CrosscheckResult": { "type": "object", "required": ["kernel_id", "external_id", "identity", "crosscheck", "parentage"], "properties": { "kernel_id": { "description": "Kernel identifier for the resolved entity. `null` when no entity is resolved.", "type": ["string", "null"], "example": "6347422643" }, "external_id": { "description": "Your CRM identifier, echoed back from the request.", "type": ["string", "null"], "example": "0014x00001LMZCDAA5" }, "identity": { "$ref": "#/components/schemas/CrosscheckIdentity" }, "linkedin": { "description": "LinkedIn match. Present only when `match_to_linkedin` was requested.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LinkedIn" } ] }, "crosscheck": { "description": "Crosscheck outcome. `null` when the pass did not run — that is, when no entity was resolved or the `external_id` does not match an account in your Kernel dataset. In that case the crosscheck portion of the credit cost is refunded.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrosscheckBlock" } ] }, "parentage": { "description": "Corporate hierarchy. `null` under the same conditions as `crosscheck` — both come from the same pass.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrosscheckParentage" } ] } } }, "CrosscheckJobStatus": { "type": "object", "required": ["status"], "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": { "description": "Crosscheck result. Present when `status` is `completed`.", "$ref": "#/components/schemas/CrosscheckResult" }, "error_message": { "description": "Error message. Present when `status` is `failed`.", "type": "string" }, "error_type": { "description": "Machine-readable error category. Present when `status` is `failed`.", "type": "string" } } }, "CrosscheckParentageEntity": { "description": "A hierarchy entity, as returned by the resolve-parent and combined endpoints, plus the CRM identifier when the entity exists in your dataset.", "allOf": [ { "$ref": "#/components/schemas/ParentEntity" }, { "type": "object", "properties": { "external_id": { "description": "Your CRM identifier for the entity, when it exists in your dataset.", "type": ["string", "null"], "example": "0014x00001TopParentA" } } } ] }, "CrosscheckParentage": { "type": "object", "description": "Corporate hierarchy for the record, matching the shape returned by the resolve-parent and combined endpoints.", "properties": { "kernel_id": { "description": "Kernel identifier of the crosschecked entity.", "type": ["string", "null"], "example": "6347422643" }, "parent": { "description": "Immediate parent. `null` when the entity has none.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrosscheckParentageEntity" } ] }, "top_parent": { "description": "The ultimate parent 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/CrosscheckParentageEntity" } ] }, "top_operating_parent": { "description": "Highest operating (non-holding) parent. `null` when the entity has none.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrosscheckParentageEntity" } ] }, "regional_subsidiary": { "$ref": "#/components/schemas/RegionalSubsidiary" } } } }, "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Include your API key in the x-api-key header." } } } }