LinktLinkt
Dashboard
Getting Started

Quickstart

Get up and running with the Linkt API in 5 minutes

Get up and running with the Linkt API in 5 minutes. This guide walks you through creating your first AI-powered company research workflow.

Prerequisites

  • A Linkt account with API access
  • Your API key (see Authentication)
  • A REST client (curl, Postman, or your preferred HTTP library)

What You'll Build

By the end of this guide, you'll have:

  1. Created an ICP (Ideal Customer Profile) defining your target companies and enrichment fields
  2. Created a Sheet to store discovered entities
  3. Added Custom Fields to capture ICP-specific enrichment data
  4. Created a Task that defines the search workflow
  5. Executed the task to discover companies matching your criteria

Step 1: Get Your API Key

Before making API calls, you'll need to authenticate. Navigate to your Linkt Dashboard and generate an API key.

All API requests require the x-api-key header:

-H "x-api-key: your_api_key_here"

For detailed authentication information, see the Authentication Guide.

Step 2: Create Your ICP

An ICP (Ideal Customer Profile) defines what entities you want to target and what data to collect. The description field uses markdown with Criteria (filtering requirements) and Enrichment Fields (data to research).

Request:

curl -X POST "https://api.linkt.ai/v1/icp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "name": "Enterprise SaaS Companies",
    "description": "## Criteria\n- B2B SaaS companies\n- 100-500 employees\n- Headquarters in the United States\n- Series A funding or later\n\n## Enrichment Fields\n- Primary product offering\n- Target customer segment\n- Recent funding round details",
    "entity_targets": [
      {
        "entity_type": "company",
        "description": "B2B SaaS companies with 100-500 employees in the United States that have raised Series A or later funding"
      }
    ]
  }'

Response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Enterprise SaaS Companies",
  "description": "## Criteria\n- B2B SaaS companies\n...",
  "entity_targets": [
    {
      "root": true,
      "entity_type": "company",
      "description": "B2B SaaS companies with 100-500 employees..."
    }
  ],
  "created_at": "2025-01-05T12:00:00Z",
  "updated_at": "2025-01-05T12:00:00Z"
}

Step 3: Create Your Sheet

A Sheet is a storage container for entities discovered by your research workflows. Each sheet is linked to an ICP and holds entities of a single type.

Request:

curl -X POST "https://api.linkt.ai/v1/sheet" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "name": "Q1 2025 Target Companies",
    "description": "Companies discovered from our Enterprise SaaS ICP",
    "icp_id": "507f1f77bcf86cd799439011",
    "entity_type": "company"
  }'

Response:

{
  "id": "507f1f77bcf86cd799439012",
  "name": "Q1 2025 Target Companies",
  "entity_type": "company",
  "entity_schema": {
    "properties": {
      "name": { "type": "string" },
      "website": { "type": "string" },
      "industry": { "type": "string" },
      "employees": { "type": "string" }
    }
  }
}

The sheet automatically receives a default schema based on the entity type.

Step 4: Add Custom Fields

Now add the enrichment fields from your ICP description as custom fields on the sheet.

Request:

curl -X PUT "https://api.linkt.ai/v1/sheet/schema/507f1f77bcf86cd799439012" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "fields": [
      {
        "name": "primary_product",
        "field_type": "string",
        "description": "The company primary product or service offering"
      },
      {
        "name": "target_customer_segment",
        "field_type": "string",
        "description": "The target customer segment"
      },
      {
        "name": "recent_funding",
        "field_type": "string",
        "description": "Recent funding round details"
      }
    ]
  }'

Response: 204 No Content on success.

Supported Field Types

TypeDescription
stringText values (most common)
numberDecimal numbers
integerWhole numbers
booleanTrue/false values
arrayLists of values
objectNested objects

Step 5: Create a Search Task

A Task defines the workflow configuration. For company discovery, we'll create a search task.

Request:

curl -X POST "https://api.linkt.ai/v1/task" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "name": "Enterprise SaaS Company Search",
    "description": "Search for B2B SaaS companies matching our ICP",
    "flow_name": "search",
    "deployment_name": "main",
    "icp_id": "507f1f77bcf86cd799439011",
    "task_config": {
      "version": "v3.0",
      "config_type": "search-task",
      "desired_contact_count": 1,
      "user_feedback": ""
    }
  }'

Step 6: Execute the Task

Execute the task to start discovering companies.

Request:

curl -X POST "https://api.linkt.ai/v1/task/507f1f77bcf86cd799439013/execute" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "icp_id": "507f1f77bcf86cd799439011",
    "parameters": {}
  }'

Response:

{
  "run_id": "507f1f77bcf86cd799439014",
  "flow_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SCHEDULED"
}

Step 7: Monitor the Run

Check the status of your workflow execution:

curl -X GET "https://api.linkt.ai/v1/run/507f1f77bcf86cd799439014" \
  -H "x-api-key: your_api_key_here"

The run will progress through states: SCHEDULED → PENDING → RUNNING → COMPLETED. Poll this endpoint until the status reaches COMPLETED (or FAILED).

Step 8: View Results

Once complete, fetch the discovered entities:

curl -X GET "https://api.linkt.ai/v1/sheet/507f1f77bcf86cd799439012/entities" \
  -H "x-api-key: your_api_key_here"

Response:

{
  "entities": [
    {
      "id": "507f1f77bcf86cd799439015",
      "data": {
        "name": "TechCorp Solutions",
        "website": "https://techcorp.com",
        "industry": "Enterprise Software",
        "employees": "250",
        "primary_product": "Cloud-based ERP platform",
        "target_customer_segment": "Mid-Market",
        "recent_funding": "Series B, $45M in March 2024"
      }
    }
  ],
  "total": 1
}

Troubleshooting

Run Status is FAILED

Check the run response for error details. Common causes:

  • Invalid ICP description — Ensure your criteria are clear and specific
  • API key issues — Verify your key has the required permissions
  • Rate limiting — Wait and retry if you've made too many requests

No Entities Found

If the search completes but returns no entities:

  • Criteria too specific — Broaden your ICP criteria
  • Conflicting requirements — Remove contradictory criteria
  • Niche market — Some segments have fewer discoverable companies

Search Duration

Search workflows typically take 15-20 minutes to complete, and can take longer depending on:

  • Complexity of your ICP criteria
  • Number of enrichment fields requested
  • Desired entity count

Set your polling timeout to at least 30 minutes. The AI agents perform thorough research to ensure quality results.

Next Steps

Previous

Introduction

Next

Authentication

On this page