LinkedIn Agent

Semantic People Search

API Documentation

Complete guide to the LinkedIn Agent API for programmatic access to semantic people search.

Overview

The LinkedIn Agent API allows you to search for people using natural language queries and retrieve detailed candidate profiles.

Base URL

https://linksearch.ai/api

Authentication

Include your API key in the Authorization header: Bearer YOUR_API_KEY

POST

/search

Create a new search job with natural language query and optional filters.

Request Body

{
  "query": "Startup founders in bay area with big tech background",
  "filters": {
    "location": "San Francisco Bay Area",
    "gender": "any",
    "ageFrom": 25,
    "ageTo": 45,
    "language": "English, Mandarin"
  },
  "deepSearch": true
}

Parameters

query

required

string

Natural language description of the people you want to find

filters

optional

object

Additional filters for location, gender, age, and language

deepSearch

optional

boolean

Enable real-time LinkedIn search (default: false)

Response

{
  "job_id": "job_abc123def456",
  "status": "PENDING",
  "created_at": "2024-01-15T10:30:00Z"
}

GET

/jobs/{job_id}

Retrieve the status and results of a search job.

Path Parameters

job_id

required

string

The job ID returned from the search endpoint

Response (PENDING/RUNNING)

{
  "job_id": "job_abc123def456",
  "status": "RUNNING",
  "progress": 45,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:32:15Z"
}

Response (FINISHED)

{
  "job_id": "job_abc123def456",
  "status": "FINISHED",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:35:22Z",
  "results": [
    {
      "name": "John Smith",
      "linkedinUrl": "https://linkedin.com/in/johnsmith",
      "summary": "Experienced startup founder with 10+ years...",
      "skills": ["Leadership", "Product Management", "AI/ML"],
      "education": [
        {
          "school": "Stanford University",
          "degree": "MBA",
          "field": "Business Administration",
          "years": "2010-2012"
        }
      ],
      "experiences": [
        {
          "company": "TechCorp",
          "title": "Founder & CEO",
          "duration": "2018-Present",
          "description": "Founded and scaled AI startup..."
        }
      ],
      "others": {
        "age": 35,
        "gender": "Male",
        "currentLocation": "San Francisco, CA",
        "languages": ["English", "Spanish"]
      }
    }
  ]
}

Status Codes

HTTP status codes and job statuses you may encounter

HTTP Status Codes

200

Success

400

Bad Request - Invalid parameters

401

Unauthorized - Invalid API key

404

Not Found - Job ID not found

429

Rate Limited - Too many requests

Job Statuses

PENDING

Job created, waiting to start

RUNNING

Job is actively searching

FINISHED

Job completed successfully

FAILED

Job failed due to error

Rate Limits

API usage limits and best practices

Search Requests

10/hour

Maximum search jobs per hour

Status Checks

100/minute

Job status polling limit

Best Practices

• Poll job status every 30-60 seconds, not continuously
• Cache results to avoid redundant searches
• Use specific queries to get better results
• Enable deep search only when necessary

Code Examples

Sample implementations in different languages

JavaScript/Node.js

// Create a search job
const response = await fetch('/api/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    query: 'AI engineers with startup experience',
    deepSearch: true
  })
});

const { job_id } = await response.json();

// Poll for results
const pollJob = async (jobId) => {
  const response = await fetch(`/api/jobs/${jobId}`);
  const job = await response.json();
  
  if (job.status === 'FINISHED') {
    return job.results;
  } else if (job.status === 'FAILED') {
    throw new Error('Job failed');
  } else {
    // Wait and poll again
    await new Promise(resolve => setTimeout(resolve, 30000));
    return pollJob(jobId);
  }
};

const results = await pollJob(job_id);

Python

import requests
import time

# Create search job
response = requests.post('/api/search', 
  headers={'Authorization': 'Bearer YOUR_API_KEY'},
  json={
    'query': 'AI engineers with startup experience',
    'deepSearch': True
  }
)

job_id = response.json()['job_id']

# Poll for results
while True:
    response = requests.get(f'/api/jobs/{job_id}')
    job = response.json()
    
    if job['status'] == 'FINISHED':
        results = job['results']
        break
    elif job['status'] == 'FAILED':
        raise Exception('Job failed')
    else:
        time.sleep(30)  # Wait 30 seconds