Entities

Entities are the core data objects in Linkt—companies and contacts discovered and enriched through your research workflows.

Overview

An entity represents a single record in a sheet. Each entity contains:

Identity fields - Unique identifier and relationships
Data - Attributes containing researched information

Entities are created when:

A search workflow discovers new companies or contacts
You import data via CSV ingest
Contacts are discovered for existing companies

Entity Structure

{
  "id": "507f1f77bcf86cd799439015",
  "sheet_id": "507f1f77bcf86cd799439012",
  "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"
    },
    "website": {
      "value": "https://acme.com",
      "references": [],
      "created_at": "2025-01-05T12:00:00Z",
      "updated_at": "2025-01-05T12:00:00Z"
    },
    "headquarters": {
      "value": {
        "city": "San Francisco",
        "state": "CA",
        "country": "United States"
      },
      "references": ["https://linkedin.com/company/acme"],
      "created_at": "2025-01-05T12:00:00Z",
      "updated_at": "2025-01-05T12:00:00Z"
    }
  },
  "created_at": "2025-01-05T12:00:00Z",
  "updated_at": "2025-01-05T12:05:00Z"
}

Top-Level Fields

Field	Type	Description
`id`	string	Unique entity identifier
`sheet_id`	string	ID of the sheet containing this entity
`parent_id`	string	ID of parent entity (for hierarchical relationships)
`data`	object	Entity attributes (see below)
`created_at`	datetime	When the entity was created
`updated_at`	datetime	When the entity was last modified

EntityAttribute Structure

Each field in the data object is an EntityAttribute with metadata about the value:

{
  "value": "The actual data value",
  "references": ["https://source1.com", "https://source2.com"],
  "created_at": "2025-01-05T12:00:00Z",
  "updated_at": "2025-01-05T12:00:00Z"
}

Field	Type	Description
`value`	any	The attribute value (string, number, object, etc.)
`references`	array	Source URLs where this information was found
`created_at`	datetime	When this attribute was first set
`updated_at`	datetime	When this attribute was last modified

Source References

The references array provides transparency into where Linkt found each piece of information. Use these to verify data accuracy or for compliance requirements.

Primitive Attribute Types

Basic attribute values can be:

Type	Example	Description
`string`	`"Acme Corp"`	Text values
`number`	`45.5`	Decimal numbers
`integer`	`150`	Whole numbers
`boolean`	`true`	True/false values

{
  "name": {
    "value": "Acme Corporation",
    "references": ["https://acme.com"]
  },
  "employees": {
    "value": 150,
    "references": ["https://linkedin.com/company/acme"]
  },
  "is_public": {
    "value": false,
    "references": []
  }
}

Complex Attribute Types

Some attributes contain structured objects as their value.

Location

Geographic location data with structured address components:

{
  "headquarters": {
    "value": {
      "street": "123 Market Street",
      "city": "San Francisco",
      "state": "CA",
      "country": "United States",
      "zip_code": "94105"
    },
    "references": ["https://linkedin.com/company/acme"]
  }
}

Field	Type	Description
`street`	string	Street address
`city`	string	City name
`state`	string	State or province
`country`	string	Country name
`zip_code`	string	Postal/ZIP code

SocialMediaProfile

Links to social media profiles:

{
  "linkedin": {
    "value": {
      "platform": "linkedin",
      "url": "https://linkedin.com/company/acme"
    },
    "references": []
  }
}

Field	Type	Description
`platform`	string	Social platform name (`linkedin`, `x`, `instagram`)
`url`	string	Full profile URL

CriteriaMatch

For ICP criteria verification, indicates whether the entity matches specific criteria:

{
  "criteria_match": {
    "value": {
      "verified": true,
      "reasoning": "Company has 200 employees and is headquartered in the US, matching the ICP criteria for mid-market US companies."
    },
    "references": ["https://linkedin.com/company/acme"]
  }
}

Field	Type	Description
`verified`	boolean	Whether criteria was verified as matching
`reasoning`	string	AI explanation of the match decision

Entity Hierarchy

Entities can have parent-child relationships, enabling you to model organizational structures.

How Hierarchy Works

When you create an ICP with multiple entity targets (e.g., company + person), discovered people are linked to their parent company:

Loading diagram...

Example: Company with Contacts

Parent Company:

{
  "id": "company_123",
  "parent_id": null,
  "data": {
    "name": {"value": "Acme Corporation"}
  }
}

Child Contact:

{
  "id": "person_456",
  "parent_id": "company_123",
  "data": {
    "name": {"value": "Jane Smith"},
    "title": {"value": "VP of Sales"},
    "company": {"value": "Acme Corporation"}
  }
}

Querying Hierarchies

To get all contacts for a company:

Query entities with the company's sheet
Filter by parent_id equal to the company's id

Entity Types and Hierarchy

Parent-child relationships only exist within the same sheet. Company entities have parent_id: null, while person entities reference their parent company.

Working with Entity Data

Accessing Attribute Values

When working with entity data in code, access the value field of each attribute:

entity = get_entity(entity_id)
 
# Get simple values
company_name = entity["data"]["name"]["value"]
employee_count = entity["data"]["employees"]["value"]
 
# Get complex values
city = entity["data"]["headquarters"]["value"]["city"]
linkedin_url = entity["data"]["linkedin"]["value"]["url"]
 
# Check references
sources = entity["data"]["name"]["references"]

Handling Missing Data

Not all entities will have all fields populated. Always check for field existence:

# Safe access pattern
website = entity["data"].get("website", {}).get("value")
if website:
    print(f"Website: {website}")

Custom Fields

Custom fields from your ICP's enrichment section appear in data alongside default fields:

{
  "data": {
    "name": {"value": "Acme Corp", "references": []},
    "primary_product": {"value": "CRM Software", "references": ["https://acme.com/products"]},
    "target_market": {"value": "Mid-market B2B", "references": ["https://acme.com/about"]}
  }
}

Next Steps

Sheets - Where entities are stored
Custom Fields - Extending entity schemas
ICPs - Defining what entities to discover
API Reference - Complete entity endpoint documentation

On this page