Entities

REST endpoints for golden-record entities. List entities, inspect detail with source lineage, and merge duplicates. All operations require Clerk JWT auth.

Entities

Endpoints for querying golden records, inspecting entity detail with lineage, and merging entities.

List entities with optional filtering and pagination.

Request

Query parameters:

Param	Type	Required	Description
`type`	string	No	Filter by entity type (e.g. `customer`, `vendor`)
`limit`	integer	No	Page size (default 50)
`offset`	integer	No	Number of records to skip

Response

{
  "entities": [
    {
      "id": "ent_01",
      "type": "customer",
      "name": "Acme Corp",
      "member_count": 3,
      "created_at": "2026-03-20T14:00:00Z"
    }
  ],
  "total": 1842
}

Errors

Status	Meaning
`401 Unauthorized`	Missing or invalid token
`422 Unprocessable Entity`	Invalid query parameters

Retrieve a single entity including its golden record, member records, and lineage.

Response

{
  "id": "ent_01",
  "type": "customer",
  "golden_record": {
    "name": "Acme Corp",
    "email": "info@acme.com",
    "phone": "+1-555-0100"
  },
  "members": [
    {
      "source_id": "src_01",
      "source_name": "CRM Export",
      "record": { "name": "Acme Corporation", "email": "info@acme.com" }
    }
  ],
  "lineage": {
    "name": { "source": "src_01", "strategy": "most_recent" },
    "email": { "source": "src_01", "strategy": "most_complete" },
    "phone": { "source": "src_02", "strategy": "source_priority" }
  }
}

Errors

Status	Meaning
`404 Not Found`	Entity not found

Manually merge two entities into one. The target entity absorbs the source entity's members.

Request

{
  "source_id": "ent_02",
  "target_id": "ent_01"
}

Field	Type	Required	Description
`source_id`	string	Yes	Entity to merge from (will be retired)
`target_id`	string	Yes	Entity to merge into (survives)

Response

{
  "merged_entity_id": "ent_01"
}

Errors

Status	Meaning
`404 Not Found`	One or both entity IDs not found
`409 Conflict`	Entities are already the same record
`422 Unprocessable Entity`	Invalid request body

Was this page helpful?

Edit this page on GitHub

PreviousDestinations NextPPRL Linkage