Data Enrichment

Use the Data Enrichment API to refresh company records from trusted web evidence.

Summary

The Data Enrichment group contains the POST /v1/enrich endpoint and its interactive playground.Use POST /v1/enrich to refresh a company record with structured data gathered from external web evidence.The endpoint is company-only in v1 and supports two input modes:

an existing Sanka company record via record_id
a transient company seed for dry_run proposals without writes

Authentication

External integrations use Authorization: Bearer <access_token>
OAuth callers need the companies:write scope for record updates
OAuth callers can use the companies:read scope for seed-based dry_run requests
Sanka internal tooling can also authenticate with X-Workspace-Code

When to use it

Use enrichment when you want to:

fill in missing company profile fields
refresh stale company details from the web
collect field-level evidence before updating your CRM record

Required request fields:

object_type: must be company
exactly one of record_id or seed
record_id: the company record UUID when enriching an existing Sanka company
seed: a transient company payload with at least name or url when you want proposals without a Sanka record

Coverage

v1 supports object_type=company only
dry_run returns proposed updates without writing
force_refresh allows overwrite evaluation for existing values
seed mode accepts a transient company name and/or URL without requiring a Sanka company record
seed mode is dry_run only and does not persist an enrichment run

Send the request

curl -X POST "https://api.sanka.com/v1/enrich" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "object_type": "company",
    "record_id": "11111111-2222-3333-4444-555555555555",
    "custom_field_map": {
      "industry": "cf_12345",
      "employee_count": "cf_67890"
    }
  }'

Use the interactive playground in the OpenAPI reference on this page to test the same request.For transient enrichment without a Sanka record, use seed with dry_run=true:

{
  "object_type": "company",
  "seed": {
    "name": "Acme",
    "external_id": "row_123"
  },
  "dry_run": true
}

Name-only enrichment is supported. Adding a company URL or domain usually improves evidence quality.

Review the response

The response includes:

updated_builtin_fields: built-in company fields written during the run
updated_custom_fields: mapped custom fields that were updated
proposed_fields: candidate values the pipeline found
field_evidence: source evidence for each accepted field
skipped_fields: fields that were rejected because confidence or overwrite rules did not pass
provider_meta: request metadata from the enrichment providers

The top-level response shape stays consistent with the rest of the API:

{
  "data": {
    "company_id": "<company_uuid_or_null>",
    "seed_external_id": "<external_id_or_null>",
    "run_id": "<run_uuid>",
    "pipeline_version": "v1",
    "updated_builtin_fields": {},
    "updated_custom_fields": {},
    "proposed_fields": {},
    "field_evidence": {},
    "skipped_fields": {},
    "provider_meta": {}
  },
  "message": "ok",
  "ctx_id": "<ctx_id>"
}

Dry run and refresh

Use dry_run when you want proposals and evidence without writing data:

{
  "object_type": "company",
  "record_id": "11111111-2222-3333-4444-555555555555",
  "dry_run": true
}

seed mode requires dry_run=true and does not persist an enrichment run in Sanka.Use force_refresh when you want the pipeline to overwrite existing values when the write policy allows it:

{
  "object_type": "company",
  "record_id": "11111111-2222-3333-4444-555555555555",
  "force_refresh": true
}

PreviousCapability matrix NextData Scoring