Quickstart - Company Search API

A fast hands-on introduction to the Company Search API

Getting Started

In order to use our Company Search API, you must have an active API key. You can look up your API key by logging into our self-serve dashboard and going to the API Keys section.

👍

Need an API Key?

If you don't have an API key, you can easily create one by signing up for a self-serve account. Check out our Self-Serve Quickstart Guide, which walks you through the sign-up process as well as how to use the self-serve API dashboard.

Simple Example

As mentioned in the Overview, the Company Search API is a way to filter and segment individual profiles included in our Company Dataset. In order to use the Company Search API, you will need either an Elasticsearch query or an SQL query.

Here's a quick example that demonstrates retrieving the company profiles of those whose website is google.com:

import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
client = PDLPY(
    api_key="YOUR API KEY",
)

# Create an Elasticsearch query
ES_QUERY = {
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}

# Create a parameters JSON object
PARAMS = {
  'query': ES_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Company Search API
response = client.company.search(**PARAMS).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"successfully grabbed {len(data)} records from pdl")
  print(f"{response['total']} total pdl records exist matching this query")
else:
  print("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)
import json

# See https://github.com/peopledatalabs/peopledatalabs-python
from peopledatalabs import PDLPY

# Create a client, specifying your API key
client = PDLPY(
    api_key="YOUR API KEY",
)

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

# Create a parameters JSON object
PARAMS = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Company Search API
response = client.company.search(**PARAMS).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"successfully grabbed {len(data)} records from pdl")
  print(f"{response['total']} total pdl records exist matching this query")
else:
  print("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)
# Elasticsearch
curl -X GET 'https://api.peopledatalabs.com/v5/company/search' \
-H 'X-Api-Key: xxxx' \
--data-raw '{
  "size": 10,
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}'

# SQL
curl -X GET \
  'https://api.peopledatalabs.com/v5/company/search' \
  -H 'X-Api-Key: xxxx' \
  --data-raw '{
    "size": 10,
    "sql": "SELECT * FROM company WHERE website='\''google.com'\'';"
}'
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

import fs from 'fs';

// Create a client, specifying your API key
const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

// Create an Elasticsearch query
const esQuery = {
  query: {
    bool: {
      must:[
        {"term": {"website": "google.com"}} 
      ]
    }
  }
}

// Create a parameters JSON object
const params = {
  searchQuery: esQuery, 
  size: 10,
  pretty: true
}

// Pass the parameters object to the Company Search API
PDLJSClient.company.search.elastic(params).then((data) => {
    // Write out all profiles found to file
    fs.writeFile("my_pdl_search.jsonl", Buffer.from(JSON.stringify(data.data)), (err) => {
        if (err) throw err;
    });
    console.log(`successfully grabbed ${data.data.length} records from pdl`);
    console.log(`${data["total"]} total pdl records exist matching this query`)
}).catch((error) => {
    console.log("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
    console.log(error);
});
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

import fs from 'fs';

// Create a client, specifying your API key
const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

// Create an SQL query
const sqlQuery = `SELECT * FROM company
                    WHERE website='google.com';`;

// Create a parameters JSON object
var params = {
    searchQuery: sqlQuery, 
    size: 10,
    pretty: true
}

// Pass the parameters object to the Company Search API
PDLJSClient.company.search.sql(params).then((data) => {
    // Write out all profiles found to file
    fs.writeFile("my_pdl_search.jsonl", Buffer.from(JSON.stringify(data.data)), (err) => {
        if (err) throw err;
    });
    console.log(`successfully grabbed ${data.data.length} records from pdl`);
    console.log(`${data["total"]} total pdl records exist matching this query`)
}).catch((error) => {
    console.log("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
    console.log(error);
});
require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

# Set your API key
Peopledatalabs.api_key = 'YOUR API KEY'

# Create an Elasticsearch query
ES_QUERY = {
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}

# Pass parameters to the Company Search API
response = Peopledatalabs::Search.company(searchType: 'elastic', query: ES_QUERY, size: 10, pretty: true)

# Check for successful response
if response['status'] == 200
    data = response['data']
    # Write out each profile found to file
    File.open("my_pdl_search.jsonl", "w") do |out|
        data.each { |record| out.write(JSON.dump(record) + "\n") }
    end
    puts "successfully grabbed #{data.length()} records from pdl"
    puts "#{response['total']} total pdl records exist matching this query"
else
    puts "NOTE. The carrier pigeons lost motivation in flight. See error and try again."
    puts "Error: #{response}"
end
require 'json'

# See https://github.com/peopledatalabs/peopledatalabs-ruby
require 'peopledatalabs'

# Set your API key
Peopledatalabs.api_key = 'YOUR API KEY'

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

# Pass parameters to the Company Search API
response = Peopledatalabs::Search.company(searchType: 'sql', query: SQL_QUERY, size: 10, pretty: true)

# Check for successful response
if response['status'] == 200
    data = response['data']
    # Write out each profile found to file
    File.open("my_pdl_search.jsonl", "w") do |out|
        data.each { |record| out.write(JSON.dump(record) + "\n") }
    end
    puts "successfully grabbed #{data.length()} records from pdl"
    puts "#{response['total']} total pdl records exist matching this query"
else
    puts "NOTE. The carrier pigeons lost motivation in flight. See error and try again."
    puts "Error: #{response}"
end
package main

import (
    "fmt"
    "os"
    "encoding/json"
)

// See https://github.com/peopledatalabs/peopledatalabs-go
import (
    pdl "github.com/peopledatalabs/peopledatalabs-go"
    pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
)

func main() {
    // Set your API key
    apiKey := "YOUR API KEY"
    // Set API key as environmental variable
    // apiKey := os.Getenv("API_KEY")

    // Create a client, specifying your API key
    client := pdl.New(apiKey)
    
    // Create an Elasticsearch query
    elasticSearchQuery := map[string]interface{} {
        "query": map[string]interface{} {
            "bool": map[string]interface{} {
                "must": []map[string]interface{} {
                    {"term": map[string]interface{}{"website": "google.com"}},
                },
            },
        },
    }

    // Create a parameters JSON object
    params := pdlmodel.SearchParams {
        BaseParams: pdlmodel.BaseParams {
            Size: 10,
            Pretty: true,
        },
        SearchBaseParams: pdlmodel.SearchBaseParams {
            Query: elasticSearchQuery,
        },
    }
    
    // Pass the parameters object to the Company Search API
    response, err := client.Company.Search(params)
    // Check for successful response
    if err == nil {
        data := response.Data
        // Create file
        out, outErr := os.Create("my_pdl_search.jsonl")
        defer out.Close()
        if (outErr == nil) {
            for i := range data {
                // Convert each profile found to JSON
                record, jsonErr := json.Marshal(data[i])
                // Write out each profile to file
                if (jsonErr == nil) {
                    out.WriteString(string(record) + "\n")
                }
            }
            out.Sync()
        }
        fmt.Printf("successfully grabbed %d records from pdl\n", len(data))
        fmt.Printf("%d total pdl records exist matching this query\n", response.Total)
    } else {
        fmt.Println("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
        fmt.Println("Error:", err)
    } 
}
package main

import (
    "fmt"
    "os"
    "encoding/json"
)

// See https://github.com/peopledatalabs/peopledatalabs-go
import (
    pdl "github.com/peopledatalabs/peopledatalabs-go"
    pdlmodel "github.com/peopledatalabs/peopledatalabs-go/model"
)

func main() {
     // Set your API key
    apiKey := "YOUR API KEY"
    // Set API key as environmental variable
    // apiKey := os.Getenv("API_KEY")

    // Create a client, specifying your API key
    client := pdl.New(apiKey)
    
    // Create an SQL query
    sqlQuery := "SELECT * FROM company" +
        " WHERE website='google.com';"

    // Create a parameters JSON object
    params := pdlmodel.SearchParams {
        BaseParams: pdlmodel.BaseParams {
            Size: 10,
            Pretty: true,
        },
        SearchBaseParams: pdlmodel.SearchBaseParams {
            SQL: sqlQuery,
        },
    }
    
    // Pass the parameters object to the Company Search API
    response, err := client.Company.Search(params)
    // Check for successful response
    if err == nil {
        data := response.Data
        // Create file
        out, outErr := os.Create("my_pdl_search.jsonl")
        defer out.Close()
        if (outErr == nil) {
            for i := range data {
                // Convert each profile found to JSON
                record, jsonErr := json.Marshal(data[i])
                // Write out each profile to file
                if (jsonErr == nil) {
                    out.WriteString(string(record) + "\n")
                }
            }
            out.Sync()
        }
        fmt.Printf("successfully grabbed %d records from pdl\n", len(data))
        fmt.Printf("%d total pdl records exist matching this query\n", response.Total)
    } else {
        fmt.Println("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
        fmt.Println("Error:", err)
    } 
}
import requests, json

# Set your API key
API_KEY = # YOUR API KEY

# Set the Company Search API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

# Set headers
H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

# Create an Elasticsearch query
ES_QUERY = {
  "query": {
    "bool": {
      "must": [
        {"term": {"website": "google.com"}},
      ]
    }
  }
}

# Create a parameters JSON object
PARAMS = {
  'query': json.dumps(ES_QUERY),
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Company Search API
response = requests.get(
  PDL_URL,
  headers=H,
  params=PARAMS
).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"successfully grabbed {len(data)} records from pdl")
  print(f"{response['total']} total pdl records exist matching this query")
else:
  print("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
  print("Error:", response)
import requests, json

# Set your API key
API_KEY = # YOUR API KEY

# Set the Company Search API URL
PDL_URL = "https://api.peopledatalabs.com/v5/company/search"

# Set headers
H = {
  'Content-Type': "application/json",
  'X-api-key': API_KEY
}

# Create an SQL query
SQL_QUERY = \
"""
  SELECT * FROM company
  WHERE website='google.com';
 """

# Create a parameters JSON object
PARAMS = {
  'sql': SQL_QUERY,
  'size': 10,
  'pretty': True
}

# Pass the parameters object to the Company Search API
response = requests.get(
  PDL_URL,
  headers=H,
  params=PARAMS
).json()

# Check for successful response
if response["status"] == 200:
  data = response['data']
  # Write out each profile found to file
  with open("my_pdl_search.jsonl", "w") as out:
    for record in data:
      out.write(json.dumps(record) + "\n")
  print(f"successfully grabbed {len(data)} records from pdl")
  print(f"{response['total']} total pdl records exist matching this query")
else:
  print("NOTE. The carrier pigeons lost motivation in flight. See error and try again.")
  print("error:", response)

The response returned is a list of company profiles if the query passed matches records in our dataset:

{
  "status": 200,
  "data": [
    {
      "id": "peopledatalabs",
      "website": "peopledatalabs.com",
      "name": "people data labs",
      "founded": 2015,
      "size": "11-50",
      "location": {
        "name": "san francisco, california, united states",
        "locality": "san francisco",
        "region": "california",
        "metro": "san francisco, california",
        "country": "united states",
        "continent": "north america",
        "street_address": "455 market street",
        "address_line_2": "suite 1670",
        "postal_code": "94105",
        "geo": "37.77,-122.41"
      },
      "industry": "computer software",
      "facebook_url": "facebook.com/peopledatalabs",
      "twitter_url": "twitter.com/peopledatalabs",
      "linkedin_url": "linkedin.com/company/peopledatalabs",
      "linkedin_id": "18170482",
      "email_domains": [],
      "ticker": null,
      "type": "private",
      "profiles": [
        "linkedin.com/company/peopledatalabs",
        "linkedin.com/company/18170482",
        "facebook.com/peopledatalabs",
        "twitter.com/peopledatalabs",
        "crunchbase.com/organization/talentiq"
      ],
      "tags": [
        "data",
        "people data",
        "data science",
        "artificial intelligence",
        "data and analytics",
        "machine learning",
        "analytics",
        "database",
        "software",
        "developer apis"
      ],
      "summary": "people data labs builds people data. \n\nuse our dataset of 1.5 billion unique person profiles to build products, enrich person profiles, power predictive modeling/ai, analysis, and more. we work with technical teams as their engineering focused people data partner. \n\nwe work with thousands of data science teams as their engineering focused people data partner. these include enterprises like adidas, ebay, and acxiom, as well as startups like madison logic, zoho, and workable. we are a deeply technical company, and are backed by two leading engineering venture capital firms - founders fund and 8vc.",
      "headline": "Your Single Source of Truth",
      "alternative_names": [],
      "alternative_domains": [],
      "affiliated_profiles": []
    }
  ],
  "scroll_token": "13.312621$5439277"
  "total": 6
}

If you don't get this response, check out our errors page for more information.



Did this page help you?