Custom Fields

Custom fields allow you to extend the default schema of your sheets to capture additional data points specific to your research needs. Define custom enrichment fields to gather targeted intelligence beyond the standard fields.

Overview

Every sheet has a default schema based on its entity type (company or person). Custom fields extend this schema with additional properties that Linkt's AI agents will research and populate.

When to Use Custom Fields

Use Case	Example
Industry-specific data	Healthcare focus areas, fintech verticals
Business intelligence	Tech stack, sales methodology, pain points
Competitive research	Market positioning, key differentiators
Contact enrichment	Decision-making scope, reporting structure

How Custom Fields Work

Define fields in your ICP's entity target description
Linkt researches and populates values during enrichment
Data stored as EntityAttributes with value, references, and timestamps

Field Types

Linkt supports 8 field types for custom fields:

Type	Description	Example Use
`string`	Text values	Industry, description, notes
`number`	Decimal numbers	Revenue, growth rate
`integer`	Whole numbers	Employee count, office count
`boolean`	True/false values	Is public, has raised funding
`array`	Lists of values	Technologies, locations, products
`object`	Nested objects	Funding details, contact info
`reference`	Predefined models	Location, SocialMediaProfile
`enum`	Fixed value lists	Company stage, priority level

CustomField Structure

The complete structure for defining a custom field:

{
  "name": "field_name",
  "field_type": "string",
  "description": "What this field represents and how to research it",
  "required": false,
  "reference_model": null,
  "array_items": null,
  "properties": null,
  "enum_values": null,
  "additional_props": {}
}

Field Properties

Property	Type	Required	Description
`name`	string	Yes	Field name (snake_case recommended)
`field_type`	enum	Yes	One of the 8 supported types
`description`	string	No	Research guidance for the AI
`required`	boolean	No	Always `false` for custom fields
`reference_model`	string	For `reference`	Name of the reference model
`array_items`	object	For `array`	Schema for array elements
`properties`	object	For `object`	Schema for object properties
`enum_values`	array	For `enum`	Allowed values
`additional_props`	object	No	Additional metadata

Custom Fields Are Optional

All custom fields are optional. The required property is always false for custom fields and cannot be changed.

Simple Field Types

String

Text values for descriptions, names, and categories:

{
  "name": "primary_product",
  "field_type": "string",
  "description": "The main product or service the company offers"
}

Entity data result:

{
  "primary_product": {
    "value": "AI-powered customer support automation platform",
    "references": ["https://company.com/products"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Number

Decimal values for metrics and measurements:

{
  "name": "annual_revenue_millions",
  "field_type": "number",
  "description": "Annual revenue in millions of USD"
}

Entity data result:

{
  "annual_revenue_millions": {
    "value": 45.5,
    "references": ["https://pitchbook.com/company"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Integer

Whole numbers for counts:

{
  "name": "office_count",
  "field_type": "integer",
  "description": "Number of office locations worldwide"
}

Boolean

True/false values:

{
  "name": "is_publicly_traded",
  "field_type": "boolean",
  "description": "Whether the company is publicly traded on a stock exchange"
}

Entity data result:

{
  "is_publicly_traded": {
    "value": false,
    "references": [],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Array Fields

Lists of values require the array_items property to define the element schema.

Array of Strings

{
  "name": "technologies",
  "field_type": "array",
  "description": "Key technologies in the company's tech stack",
  "array_items": {
    "type": "string",
    "description": "Individual technology name"
  }
}

Entity data result:

{
  "technologies": {
    "value": ["React", "Node.js", "PostgreSQL", "AWS"],
    "references": ["https://stackshare.io/company"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Array of Numbers

{
  "name": "quarterly_growth_rates",
  "field_type": "array",
  "description": "Quarterly revenue growth rates as percentages",
  "array_items": {
    "type": "number",
    "description": "Growth rate percentage"
  }
}

Array of Objects

{
  "name": "key_products",
  "field_type": "array",
  "description": "Main products offered by the company",
  "array_items": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "category": {"type": "string"},
      "launch_year": {"type": "integer"}
    }
  }
}

Entity data result:

{
  "key_products": {
    "value": [
      {"name": "DataSync Pro", "category": "Integration", "launch_year": 2022},
      {"name": "Analytics Hub", "category": "BI", "launch_year": 2023}
    ],
    "references": ["https://company.com/products"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Object Fields

Nested objects with defined properties:

{
  "name": "funding_details",
  "field_type": "object",
  "description": "Details about the company's most recent funding round",
  "properties": {
    "round_type": {
      "type": "string",
      "description": "Type of funding round (Seed, Series A, etc.)"
    },
    "amount_millions": {
      "type": "number",
      "description": "Amount raised in millions USD"
    },
    "lead_investor": {
      "type": "string",
      "description": "Lead investor in the round"
    },
    "date": {
      "type": "string",
      "description": "Date of the funding announcement"
    }
  }
}

Entity data result:

{
  "funding_details": {
    "value": {
      "round_type": "Series B",
      "amount_millions": 45,
      "lead_investor": "Sequoia Capital",
      "date": "2025-01-15"
    },
    "references": ["https://techcrunch.com/company-series-b"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Reference Fields

Reference fields use predefined models. The reference_model property must specify one of the available models.

Available Reference Models

Model	Description	Fields
`Location`	Geographic address	city, state, country, street, zip_code
`SocialMediaProfile`	Social media link	platform, url
`CriteriaMatch`	Criteria verification	verified, reasoning

Location Reference

{
  "name": "headquarters",
  "field_type": "reference",
  "reference_model": "Location",
  "description": "Company headquarters location"
}

Location model structure:

{
  "street": "123 Main Street",
  "city": "San Francisco",
  "state": "California",
  "country": "United States",
  "zip_code": "94105"
}

Entity data result:

{
  "headquarters": {
    "value": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "zip_code": "94105"
    },
    "references": ["https://company.com/contact"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

SocialMediaProfile Reference

{
  "name": "twitter_profile",
  "field_type": "reference",
  "reference_model": "SocialMediaProfile",
  "description": "Company's Twitter/X profile"
}

SocialMediaProfile model structure:

{
  "platform": "x",
  "url": "https://x.com/companyhandle"
}

Supported platforms:

linkedin — LinkedIn profiles
x — X (Twitter) profiles
instagram — Instagram profiles

CriteriaMatch Reference

Used internally for ICP criteria verification:

{
  "name": "criteria_series_a_funded",
  "field_type": "reference",
  "reference_model": "CriteriaMatch",
  "description": "Company has raised Series A or later funding"
}

CriteriaMatch model structure:

{
  "verified": true,
  "reasoning": "LinkedIn shows $15M Series A raised in 2024"
}

Field	Type	Description
`verified`	boolean/null	`true` = meets criteria, `false` = doesn't meet, `null` = unknown
`reasoning`	string	Evidence or explanation (1 sentence)

Criteria Fields

CriteriaMatch fields are typically auto-generated based on your ICP criteria. They appear with a criteria_ prefix and track how well an entity matches your targeting requirements.

Enum Fields

Fixed value lists using enum_values:

{
  "name": "company_stage",
  "field_type": "enum",
  "description": "Current funding/growth stage of the company",
  "enum_values": ["Pre-seed", "Seed", "Series A", "Series B", "Series C+", "Growth", "Public"]
}

Entity data result:

{
  "company_stage": {
    "value": "Series B",
    "references": ["https://crunchbase.com/company"],
    "created_at": "2025-01-06T10:00:00Z"
  }
}

Enum with Numbers

{
  "name": "priority_score",
  "field_type": "enum",
  "description": "Account priority level (1=highest)",
  "enum_values": [1, 2, 3, 4, 5]
}

Defining Custom Fields in ICPs

Custom fields are defined in the entity target description using the Enrichment Fields pattern:

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SaaS Companies with Enrichment",
    "mode": "discovery",
    "entity_targets": [
      {
        "entity_type": "company",
        "root": true,
        "description": "## Criteria\n- B2B SaaS companies\n- 50-500 employees\n- Series A or B funded\n\n## Enrichment Fields\n- primary_product: Main product or service offered\n- tech_stack: Key technologies used (React, Node.js, etc.)\n- annual_revenue: Estimated annual revenue in millions\n- key_customers: Notable customer names\n- recent_news: Latest company news or announcements"
      }
    ]
  }'

Enrichment Field Best Practices

Do	Don't
Be specific about what to research	Use vague descriptions
Provide examples where helpful	Leave description empty
Use snake_case for field names	Use spaces or special characters
Focus on high-value fields	Request too many fields

Adding Custom Fields to Existing Sheets

Add custom fields to a sheet after creation:

curl -X PUT "https://api.linkt.ai/v1/sheet/schema/{sheet_id}" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "name": "sales_methodology",
        "field_type": "string",
        "description": "Sales approach used by the company"
      },
      {
        "name": "target_market",
        "field_type": "enum",
        "description": "Primary target market segment",
        "enum_values": ["Enterprise", "Mid-Market", "SMB", "Consumer"]
      }
    ]
  }'

Removing Custom Fields

Remove custom fields (cannot remove default fields):

curl -X DELETE "https://api.linkt.ai/v1/sheet/schema/{sheet_id}" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["sales_methodology", "target_market"]
  }'

Schema Evolution

As your research needs evolve, you can modify sheet schemas.

Adding Fields to Active Sheets

New fields can be added at any time:

Existing entities won't have the new field populated
New entities will include the field
Re-running enrichment can populate existing entities

Field Removal Considerations

Removing a field deletes the data from entities
Consider exporting data before removing fields
Default fields cannot be removed

Schema Versioning Pattern

For complex schemas, use a versioning pattern:

{
  "name": "schema_version",
  "field_type": "string",
  "description": "Schema version for this entity"
}

Validation Rules

Custom fields are validated based on their type:

Type	Required Properties
`string`, `number`, `integer`, `boolean`	`name`, `field_type`
`array`	`name`, `field_type`, `array_items`
`object`	`name`, `field_type`, `properties`
`reference`	`name`, `field_type`, `reference_model`
`enum`	`name`, `field_type`, `enum_values`

Common Validation Errors

Error	Cause	Solution
"reference_model required"	Reference field without model	Add `reference_model` property
"array_items required"	Array field without item schema	Add `array_items` property
"enum_values required"	Enum field without values	Add `enum_values` array
"Invalid reference_model"	Unknown model name	Use Location, SocialMediaProfile, or CriteriaMatch

Complete Example

Full ICP with multiple custom field types:

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Healthcare Tech Companies",
    "description": "Healthcare technology companies for market research",
    "mode": "discovery",
    "entity_targets": [
      {
        "entity_type": "company",
        "root": true,
        "description": "## Criteria\n- Healthcare technology sector\n- B2B or B2B2C business model\n- 25-500 employees\n- US headquarters\n\n## Enrichment Fields\n- healthcare_vertical: Specific healthcare focus (mental health, telehealth, clinical trials, etc.)\n- target_customers: Primary customer types (hospitals, clinics, patients, payers)\n- regulatory_status: FDA clearance or HIPAA compliance status\n- key_integrations: Major EHR or healthcare system integrations\n- funding_stage: Current funding stage (Seed, Series A, B, C+)\n- notable_customers: Named healthcare organization customers\n- growth_signals: Recent growth indicators (hiring, expansion, partnerships)"
      },
      {
        "entity_type": "person",
        "desired_count": 2,
        "description": "## Criteria\n- VP, Director, or C-level\n- Product, Engineering, or Sales leadership\n- Decision-making authority\n\n## Enrichment Fields\n- healthcare_experience: Prior healthcare industry experience\n- decision_scope: Areas of purchasing authority"
      }
    ]
  }'

Next Steps

Sheets — Understanding sheet schemas
Entities — How custom fields appear in entity data
Advanced Targeting — Using enrichment fields effectively

On this page