Entity Operations

Complete guide to listing, searching, updating, and managing entities via the API

This guide covers all entity operations available through the Linkt API, including listing, searching, retrieving, updating, and deleting entities.

Deprecated Endpoint

The legacy endpoint GET /v1/sheet/{sheet_id}/entities is deprecated. Use GET /v1/entity with query parameters instead. See Migrating from Legacy Endpoint below.

List Entities

Retrieve entities with filtering and pagination.

Endpoint: GET /v1/entity

from linkt import Linkt
 
client = Linkt()
 
entities = client.entity.list(
    icp_id="507f1f77bcf86cd799439011",
    entity_type="company",
    status="new"
)

Query Parameters

Parameter	Type	Default	Description
`icp_id`	string	—	Filter by ICP ID
`entity_type`	string	—	Filter by type: `company` or `person`
`status`	string	—	Filter by status (see Entity Statuses)
`hide_duplicates`	boolean	`false`	Hide duplicate entities, showing only primaries
`search`	string	—	Search entity names
`page`	integer	`1`	Page number
`page_size`	integer	`20`	Results per page (max 100)
`sort_by`	string	`created_at`	Sort field
`order`	string	`desc`	Sort order: `asc` or `desc`

Response

{
  "entities": [
    {
      "id": "507f1f77bcf86cd799439015",
      "icp_id": "507f1f77bcf86cd799439011",
      "entity_type": "company",
      "status": "new",
      "data": {
        "name": {
          "value": "Acme Corporation",
          "references": ["https://acme.com"],
          "created_at": "2025-01-05T12:00:00Z",
          "updated_at": "2025-01-05T12:00:00Z"
        },
        "website": {
          "value": "https://acme.com",
          "references": [],
          "created_at": "2025-01-05T12:00:00Z",
          "updated_at": "2025-01-05T12:00:00Z"
        }
      },
      "duplicate_info": {
        "is_duplicate": false,
        "is_primary": true,
        "duplicate_count": 2,
        "duplicate_entity_ids": ["entity_456", "entity_789"],
        "duplicate_icps": [
          {"icp_id": "icp_002", "icp_name": "Fintech Companies"},
          {"icp_id": "icp_003", "icp_name": "US Enterprise"}
        ]
      },
      "created_at": "2025-01-05T12:00:00Z",
      "updated_at": "2025-01-05T12:05:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "page_size": 20
}

Full Example with Pagination

from linkt import Linkt
 
client = Linkt()
 
# List all companies in an ICP with pagination
entities = client.entity.list(
    icp_id="507f...",
    entity_type="company",
    page=1,
    page_size=50
)
print(f"Found {entities.total} companies")
 
for entity in entities.data:
    name = entity.data["name"]["value"]
    print(f"- {name}")
 
# Iterate through all pages
page = 1
while True:
    entities = client.entity.list(
        icp_id="507f...",
        entity_type="company",
        page=page,
        page_size=50
    )
 
    for entity in entities.data:
        print(f"- {entity.data['name']['value']}")
 
    if page * 50 >= entities.total:
        break
    page += 1

Search Entities

Search across entities using a text query.

Endpoint: GET /v1/entity/search

results = client.entity.search(
    q="fintech",
    entity_type="company"
)
print(f"Found {results.total} matching companies")

Query Parameters

Parameter	Type	Default	Description
`q`	string	required	Search query
`icp_id`	string	—	Filter by ICP ID
`entity_type`	string	—	Filter by type
`status`	string	—	Filter by status
`page`	integer	`1`	Page number
`page_size`	integer	`20`	Results per page

Response

Same structure as List Entities.

Retrieve Entity

Get a single entity by ID.

Endpoint: GET /v1/entity/{entity_id}

entity = client.entity.retrieve(entity_id="507f1f77bcf86cd799439015")
print(f"Company: {entity.data['name']['value']}")
print(f"Status: {entity.status}")

Response

{
  "id": "507f1f77bcf86cd799439015",
  "icp_id": "507f1f77bcf86cd799439011",
  "entity_type": "company",
  "status": "qualified",
  "parent_id": null,
  "data": {
    "name": {
      "value": "Acme Corporation",
      "references": ["https://acme.com"],
      "created_at": "2025-01-05T12:00:00Z",
      "updated_at": "2025-01-05T12:00:00Z"
    }
  },
  "duplicate_info": {
    "is_duplicate": false,
    "is_primary": true
  },
  "created_at": "2025-01-05T12:00:00Z",
  "updated_at": "2025-01-05T12:05:00Z"
}

Update Entity

Update an entity's status or data.

Endpoint: PATCH /v1/entity/{entity_id}

updated = client.entity.update(
    entity_id="507f1f77bcf86cd799439015",
    status="contacted"
)
print(f"Updated status to: {updated.status}")

Request Body

Field	Type	Description
`status`	string	New entity status

Response

Returns the updated entity object.

Entity Statuses

Status	Description
`new`	Newly discovered, not yet reviewed
`qualified`	Reviewed and confirmed as matching ICP
`contacted`	Outreach has been initiated
`converted`	Successfully converted (deal closed, meeting booked, etc.)
`disqualified`	Does not match ICP after review
`archived`	Removed from active consideration

Delete Entity

Permanently delete an entity.

Endpoint: DELETE /v1/entity/{entity_id}

client.entity.delete(entity_id="507f1f77bcf86cd799439015")
print("Entity deleted successfully")

Response

204 No Content on success.

Permanent Deletion

Deleting an entity is permanent and cannot be undone. Consider updating the status to archived instead if you may need the data later.

Entity Response Schema

All entity responses follow this structure:

Field	Type	Description
`id`	string	Unique entity identifier
`icp_id`	string	ID of the associated ICP
`entity_type`	string	Type: `company` or `person`
`status`	string	Current workflow status
`parent_id`	string	Parent entity ID (for person entities linked to companies)
`data`	object	Entity attributes as EntityAttribute objects
`duplicate_info`	object	Cross-ICP duplicate detection info
`created_at`	datetime	When the entity was created
`updated_at`	datetime	When the entity was last modified

Duplicate Info Fields

Field	Type	Description
`is_duplicate`	boolean	True if this entity is a duplicate (not the primary)
`is_primary`	boolean	True if this is the primary in a duplicate group
`duplicate_count`	integer	Number of duplicates (primary only)
`duplicate_entity_ids`	array	IDs of duplicate entities (primary only)
`duplicate_icps`	array	ICPs containing duplicates (primary only)
`primary_entity_id`	string	ID of the primary entity (duplicate only)
`primary_icp_name`	string	ICP name of the primary (duplicate only)

Duplicate Detection

Linkt automatically detects when the same company or person appears across multiple ICPs.

How Detection Works

Duplicates are identified by matching:

Normalized name (required) — case-insensitive, whitespace-collapsed
Plus at least one secondary identifier:
- Companies: website domain OR LinkedIn URL
- People: email OR LinkedIn URL

The first entity created (by created_at) becomes the primary. Subsequent matches are marked as duplicates.

Working with Duplicates

Hide duplicates in listings:

entities = client.entity.list(
    icp_id="...",
    hide_duplicates=True
)

Identify primary from a duplicate:

def get_primary_entity(client, duplicate_entity):
    """Get the primary entity for a duplicate."""
    if not duplicate_entity.duplicate_info or not duplicate_entity.duplicate_info.is_duplicate:
        return duplicate_entity  # Already primary
 
    primary_id = duplicate_entity.duplicate_info.primary_entity_id
    return client.entity.retrieve(entity_id=primary_id)

Migrating from Legacy Endpoint

If you're using the deprecated GET /v1/sheet/{sheet_id}/entities endpoint, migrate to the new entity API:

Before (Deprecated)

GET /v1/sheet/{sheet_id}/entities

After (Current)

GET /v1/entity?icp_id={icp_id}&entity_type={type}

Key Differences

Aspect	Legacy	Current
Identifier	`sheet_id`	`icp_id` + `entity_type`
Response format	Simplified `data`	Full `EntityAttribute` structure
Duplicate info	Not included	`duplicate_info` object
Status field	Not included	`status` field

Migration Example

from linkt import Linkt
 
client = Linkt()
 
# BEFORE (deprecated raw HTTP)
# response = requests.get(f"https://api.linkt.ai/v1/sheet/{sheet_id}/entities", ...)
 
# AFTER (SDK)
entities = client.entity.list(
    icp_id=icp_id,
    entity_type="company"
)

Next Steps

Entities Data Model — Entity structure and attributes
Sheets — Where entities are stored
Execution — How entities are created through workflows
API Reference — Complete endpoint documentation

On this page