Reference - Person Search API

Reference information for the Person Search API

PDL's Search API is perfect for finding specific segments of people that you need to power your projects and products. This product gives you direct access to our full API dataset. There are many degrees of freedom, which allow you to find any kind of person(s) with a single query.

Endpoint

The endpoint for the Person Search API is https://api.peopledatalabs.com/v5/person/search.

Person Search API Access and Billing

We charge per record retrieved. Each person record in the data array of the response counts as a single credit against your total package.

Requests

See Authentication and Requests to learn how to input requests. We recommend using a JSON object to capture request parameters and will do so in the examples.

Rate Limiting

The current default rate limit is 10 requests per minute.

Input Parameters

📘

For more details, see Input Parameters - Person Search API

You can also click on the individual parameter names in the table below to view more information as well.

Parameter NameDescriptionDefaultExample
queryAn Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.{"query": {"term": {"job_company_name": "people data labs"}}}
sqlA SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving PDL fields. Any use of column selections or the LIMIT keyword will be ignored.SELECT * FROM person WHERE job_company_name='people data labs'
sizeThe batch size or the maximum number of matched records to return for this query if they exist. Must be between 1 and 100.1100
from[LEGACY] An offset value for paginating between batches. Can be a number between 0 and 9999. Pagination can be executed up to a maximum of 10,000 records per query. Note: YOU CANNOT USE FROM WITH SCROLL_TOKEN IN THE SAME REQUEST.00, 100, 200 ...
scroll_tokenAn offset key for paginating between batches. Unlike the legacy from parameter, you can use this parameter for any number of records. Each Person Search API response returns a scroll_token which you can use to fetch the next size records.None104$14.278746
datasetSpecifies which dataset the API should search against. You can input multiple datasets by separating them with a comma. Valid names are resume, email, phone, mobile_phone, street_address, consumer_social, developer and all. You can also exclude datasets by using - as the first character.resumeall
titlecaseAll text in the data of API responses returns as lowercase by default. Setting titlecase to true will titlecase any records returned.falsetrue
prettyWhether the output should have human-readable indentation.falsetrue
api_keyYour API key (Note: you can also provide this in the request header instead, as shown on the Authentication page.)

Response

The HTTP Response code will be 200 for any valid request, regardless of whether records were found for your query or not. For that reason, pay close attention to the total value in your response object to understand query success. Each person record in the data array of the response counts as a single credit against your total package. This value has a maximum of one record by default to prevent accidents.

Response Fields

📘

For more details see Output Response - Person Search API

You can also click the field names in the table below to view more information as well.

FieldDescriptionType
statusResponse code. See a description of our error codes.Integer
errorError details.Object
error.typeError details.List (String)
error.messageError details.String
dataThe data returned. See a full example response or the example company record.Object
totalThe number of records matching a given query or sql input.Integer
scroll_tokenThe scroll value, which is used for pagination.String

Abridged Response Data Structure

Here is an example response from the Person Search API:

{
    "status": 200,
    "data": [
        {
            "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
            "full_name": "sean thorne",
            ...
        },
        ...
    ],
    "scroll_token": "1117$12.176522"
    "total": 99
}

Full Example Response

Full Output Response (click to expand)
{
  "status": 200,
  "data": [
    {
      "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
      "full_name": "sean thorne",
      "first_name": "sean",
      "middle_initial": "f",
      "middle_name": "fong",
      "last_name": "thorne",
      "gender": "male",
      "birth_year": "1990",
      "birth_date": null,
      "linkedin_url": "linkedin.com/in/seanthorne",
      "linkedin_username": "seanthorne",
      "linkedin_id": "145991517",
      "facebook_url": "facebook.com/deseanthorne",
      "facebook_username": "deseanthorne",
      "facebook_id": "1089351304",
      "twitter_url": "twitter.com/seanthorne5",
      "twitter_username": "seanthorne5",
      "github_url": null,
      "github_username": null,
      "work_email": "[email protected]",
      "personal_emails": ["[email protected]"],
      "mobile_phone": "+14155688415",
      "industry": "computer software",
      "job_title": "co-founder and chief executive officer",
      "job_title_role": null,
      "job_title_sub_role": null,
      "job_title_levels": [
        "owner",
        "cxo"
      ],
      "job_company_id": "peopledatalabs",
      "job_company_name": "people data labs",
      "job_company_website": "peopledatalabs.com",
      "job_company_size": "11-50",
      "job_company_founded": "2015",
      "job_company_industry": "computer software",
      "job_company_linkedin_url": "linkedin.com/company/peopledatalabs",
      "job_company_linkedin_id": "18170482",
      "job_company_facebook_url": "facebook.com/peopledatalabs",
      "job_company_twitter_url": "twitter.com/peopledatalabs",
      "job_company_location_name": "san francisco, california, united states",
      "job_company_location_locality": "san francisco",
      "job_company_location_metro": "san francisco, california",
      "job_company_location_region": "california",
      "job_company_location_geo": "37.77,-122.41",
      "job_company_location_street_address": "455 market street",
      "job_company_location_address_line_2": "suite 1670",
      "job_company_location_postal_code": "94105",
      "job_company_location_country": "united states",
      "job_company_location_continent": "north america",
      "job_last_updated": "2020-12-01",
      "job_start_date": "2015-03",
      "location_name": "san francisco, california, united states",
      "location_locality": "san francisco",
      "location_metro": "san francisco, california",
      "location_region": "california",
      "location_country": "united states",
      "location_continent": "north america",
      "location_street_address": null,
      "location_address_line_2": null,
      "location_postal_code": null,
      "location_geo": "37.77,-122.41",
      "location_last_updated": "2020-12-01",
      "phone_numbers": [
        "+14155688415"
      ],
      "emails": [
        {
          "address": "[email protected]",
          "type": null
        },
        {
          "address": "[email protected]",
          "type": "professional"
        },
        {
          "address": "[email protected]",
          "type": "professional"
        },
        {
          "address": "[email protected]",
          "type": "professional"
        },
        {
          "address": "[email protected]",
          "type": "current_professional"
        },
        {
          "address": "[email protected]",
          "type": "current_professional"
        },
        {
          "address": "[email protected]",
          "type": "current_professional"
        }
      ],
      "interests": [
        "location based services",
        "mobile",
        "social media",
        "colleges",
        "university students",
        "consumer internet",
        "college campuses"
      ],
      "skills": [
        "entrepreneurship",
        "start ups",
        "management",
        "public speaking",
        "strategic partnerships",
        "strategy",
        "fundraising",
        "saas",
        "enterprise technology sales",
        "social networking"
      ],
      "location_names": [
        "san francisco, california, united states",
        "albany, california, united states",
        "portland, oregon, united states"
      ],
      "regions": [
        "california, united states",
        "oregon, united states"
      ],
      "countries": [
        "united states"
      ],
      "street_addresses": [],
      "experience": [
        {
          "company": {
            "name": "hallspot",
            "size": "1-10",
            "id": "hallspot",
            "founded": "2013",
            "industry": "computer software",
            "location": {
              "name": "portland, oregon, united states",
              "locality": "portland",
              "region": "oregon",
              "metro": "portland, oregon",
              "country": "united states",
              "continent": "north america",
              "street_address": "1231 northwest hoyt street",
              "address_line_2": "suite 202",
              "postal_code": "97209",
              "geo": "45.52,-122.67"
            },
            "linkedin_url": "linkedin.com/company/hallspot",
            "linkedin_id": "3019184",
            "facebook_url": null,
            "twitter_url": "twitter.com/hallspot",
            "website": "hallspot.com"
          },
          "location_names": [],
          "end_date": "2015-02",
          "start_date": "2012-08",
          "title": {
            "name": "co-founder",
            "role": null,
            "sub_role": null,
            "levels": [
              "owner"
            ]
          },
          "is_primary": false
        },
        {
          "company": {
            "name": "people data labs",
            "size": "11-50",
            "id": "peopledatalabs",
            "founded": "2015",
            "industry": "computer software",
            "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"
            },
            "linkedin_url": "linkedin.com/company/peopledatalabs",
            "linkedin_id": "18170482",
            "facebook_url": "facebook.com/peopledatalabs",
            "twitter_url": "twitter.com/peopledatalabs",
            "website": "peopledatalabs.com"
          },
          "location_names": [],
          "end_date": null,
          "start_date": "2015-03",
          "title": {
            "name": "co-founder and chief executive officer",
            "role": null,
            "sub_role": null,
            "levels": [
              "owner",
              "cxo"
            ]
          },
          "is_primary": true
        }
      ],
      "education": [
        {
          "school": {
            "name": "university of oregon",
            "type": "post-secondary institution",
            "id": "64LkgfdwWYkCC2TjbldMDQ_0",
            "location": {
              "name": "eugene, oregon, united states",
              "locality": "eugene",
              "region": "oregon",
              "country": "united states",
              "continent": "north america"
            },
            "linkedin_url": "linkedin.com/school/university-of-oregon",
            "facebook_url": "facebook.com/universityoforegon",
            "twitter_url": "twitter.com/uoregon",
            "linkedin_id": "19207",
            "website": "uoregon.edu",
            "domain": "uoregon.edu"
          },
          "end_date": "2014",
          "start_date": "2010",
          "gpa": null,
          "degrees": [],
          "majors": [
            "entrepreneurship"
          ],
          "minors": []
        }
      ],
      "profiles": [
        {
          "network": "linkedin",
          "id": "145991517",
          "url": "linkedin.com/in/seanthorne",
          "username": "seanthorne"
        },
        {
          "network": "facebook",
          "id": "1089351304",
          "url": "facebook.com/deseanthorne",
          "username": "deseanthorne"
        },
        {
          "network": "twitter",
          "id": null,
          "url": "twitter.com/seanthorne5",
          "username": "seanthorne5"
        },
        {
          "network": "linkedin",
          "id": null,
          "url": "linkedin.com/in/sean-thorne-9b9a8540",
          "username": "sean-thorne-9b9a8540"
        },
        {
          "network": "angellist",
          "id": null,
          "url": "angel.co/deseanthorne",
          "username": "deseanthorne"
        },
        {
          "network": "gravatar",
          "id": null,
          "url": "gravatar.com/seanthorne5",
          "username": "seanthorne5"
        },
        {
          "network": "klout",
          "id": null,
          "url": "klout.com/seanthorne5",
          "username": "seanthorne5"
        },
        {
          "network": "aboutme",
          "id": null,
          "url": "about.me/sean_thorne",
          "username": "sean_thorne"
        }
      ]
    }
  ],
"scroll_token": "1117$12.176522"  
"total": 94
}

Full Field Mapping

{
  "_routing" : {
    "required" : true
  },
  "date_detection" : false,
  "properties" : {
    "birth_date" : {
      "type" : "keyword"
    },
    "birth_year" : {
      "type" : "keyword"
    },
    "certifications" : {
      "properties" : {
        "end_date" : {
          "type" : "keyword"
        },
        "name" : {
          "type" : "keyword"
        },
        "organization" : {
          "type" : "keyword"
        },
        "start_date" : {
          "type" : "keyword"
        }
      }
    },
    "countries" : {
      "type" : "keyword"
    },
    "datapull" : {
      "type" : "keyword"
    },
    "education" : {
      "properties" : {
        "degrees" : {
          "type" : "keyword"
        },
        "end_date" : {
          "type" : "keyword"
        },
        "gpa" : {
          "type" : "float",
          "doc_values" : false
        },
        "majors" : {
          "type" : "keyword"
        },
        "minors" : {
          "type" : "keyword"
        },
        "raw" : {
          "type" : "keyword",
          "index" : false
        },
        "school" : {
          "properties" : {
            "domain" : {
              "type" : "keyword"
            },
            "facebook_url" : {
              "type" : "keyword"
            },
            "id" : {
              "type" : "keyword"
            },
            "linkedin_id" : {
              "type" : "keyword"
            },
            "linkedin_url" : {
              "type" : "keyword"
            },
            "location" : {
              "properties" : {
                "continent" : {
                  "type" : "keyword"
                },
                "country" : {
                  "type" : "keyword"
                },
                "locality" : {
                  "type" : "keyword"
                },
                "name" : {
                  "type" : "keyword"
                },
                "region" : {
                  "type" : "keyword"
                }
              }
            },
            "name" : {
              "type" : "keyword"
            },
            "raw" : {
              "type" : "keyword"
            },
            "twitter_url" : {
              "type" : "keyword"
            },
            "type" : {
              "type" : "keyword"
            },
            "website" : {
              "type" : "keyword"
            }
          }
        },
        "start_date" : {
          "type" : "keyword"
        },
        "summary" : {
          "type" : "keyword",
          "index" : false
        }
      }
    },
    "email_hashes" : {
      "type" : "keyword"
    },
    "emails" : {
      "properties" : {
        "address" : {
          "type" : "keyword"
        },
        "type" : {
          "type" : "keyword"
        }
      }
    },
    "experience" : {
      "properties" : {
        "company" : {
          "properties" : {
            "email_domains" : {
              "type" : "keyword"
            },
            "facebook_url" : {
              "type" : "keyword"
            },
            "founded" : {
              "type" : "keyword"
            },
            "fuzzy_match" : {
              "type" : "boolean",
              "doc_values" : false
            },
            "id" : {
              "type" : "keyword"
            },
            "industry" : {
              "type" : "keyword"
            },
            "linkedin_id" : {
              "type" : "keyword"
            },
            "linkedin_url" : {
              "type" : "keyword"
            },
            "location" : {
              "properties" : {
                "address_line_2" : {
                  "type" : "keyword"
                },
                "continent" : {
                  "type" : "keyword"
                },
                "country" : {
                  "type" : "keyword"
                },
                "geo" : {
                  "type" : "geo_point",
                  "doc_values" : false
                },
                "locality" : {
                  "type" : "keyword"
                },
                "metro" : {
                  "type" : "keyword"
                },
                "name" : {
                  "type" : "keyword"
                },
                "postal_code" : {
                  "type" : "keyword"
                },
                "region" : {
                  "type" : "keyword"
                },
                "street_address" : {
                  "type" : "keyword"
                }
              }
            },
            "name" : {
              "type" : "keyword"
            },
            "raw" : {
              "type" : "keyword"
            },
            "size" : {
              "type" : "keyword"
            },
            "ticker" : {
              "type" : "keyword"
            },
            "twitter_url" : {
              "type" : "keyword"
            },
            "type" : {
              "type" : "keyword"
            },
            "website" : {
              "type" : "keyword"
            }
          }
        },
        "end_date" : {
          "type" : "keyword"
        },
        "is_primary" : {
          "type" : "boolean",
          "doc_values" : false
        },
        "location_names" : {
          "type" : "keyword"
        },
        "start_date" : {
          "type" : "keyword"
        },
        "summary" : {
          "type" : "text"
        },
        "title" : {
          "properties" : {
            "functions" : {
              "type" : "keyword"
            },
            "levels" : {
              "type" : "keyword"
            },
            "name" : {
              "type" : "keyword",
              "fields" : {
                "text" : {
                  "type" : "text"
                }
              },
              "ignore_above" : 256
            },
            "raw" : {
              "type" : "keyword"
            },
            "role" : {
              "type" : "keyword"
            },
            "sub_role" : {
              "type" : "keyword"
            }
          }
        },
        "type" : {
          "type" : "keyword"
        }
      }
    },
    "facebook_id" : {
      "type" : "keyword"
    },
    "facebook_url" : {
      "type" : "keyword"
    },
    "facebook_username" : {
      "type" : "keyword"
    },
    "first_name" : {
      "type" : "keyword"
    },
    "full_name" : {
      "type" : "keyword"
    },
    "gender" : {
      "type" : "keyword"
    },
    "github_url" : {
      "type" : "keyword"
    },
    "github_username" : {
      "type" : "keyword"
    },
    "id" : {
      "type" : "keyword",
      "index" : false
    },
    "industry" : {
      "type" : "keyword"
    },
    "inferred_location_names" : {
      "type" : "keyword"
    },
    "inferred_salary" : {
      "type" : "keyword"
    },
    "inferred_years_experience" : {
      "type" : "integer",
      "doc_values" : false
    },
    "interests" : {
      "type" : "keyword"
    },
    "is_frankenstein" : {
      "type" : "boolean",
      "doc_values" : false
    },
    "job_company_facebook_url" : {
      "type" : "keyword"
    },
    "job_company_founded" : {
      "type" : "keyword"
    },
    "job_company_id" : {
      "type" : "keyword"
    },
    "job_company_industry" : {
      "type" : "keyword"
    },
    "job_company_linkedin_id" : {
      "type" : "keyword"
    },
    "job_company_linkedin_url" : {
      "type" : "keyword"
    },
    "job_company_location_address_line_2" : {
      "type" : "keyword"
    },
    "job_company_location_continent" : {
      "type" : "keyword"
    },
    "job_company_location_country" : {
      "type" : "keyword"
    },
    "job_company_location_geo" : {
      "type" : "geo_point",
      "doc_values" : false
    },
    "job_company_location_locality" : {
      "type" : "keyword"
    },
    "job_company_location_metro" : {
      "type" : "keyword"
    },
    "job_company_location_name" : {
      "type" : "keyword"
    },
    "job_company_location_postal_code" : {
      "type" : "keyword"
    },
    "job_company_location_region" : {
      "type" : "keyword"
    },
    "job_company_location_street_address" : {
      "type" : "keyword"
    },
    "job_company_name" : {
      "type" : "keyword"
    },
    "job_company_size" : {
      "type" : "keyword"
    },
    "job_company_ticker" : {
      "type" : "keyword"
    },
    "job_company_twitter_url" : {
      "type" : "keyword"
    },
    "job_company_type" : {
      "type" : "keyword"
    },
    "job_company_website" : {
      "type" : "keyword"
    },
    "job_last_updated" : {
      "type" : "keyword"
    },
    "job_start_date" : {
      "type" : "keyword"
    },
    "job_summary" : {
      "type" : "text"
    },
    "job_title" : {
      "type" : "keyword",
      "fields" : {
        "text" : {
          "type" : "text"
        }
      },
      "ignore_above" : 256
    },
    "job_title_levels" : {
      "type" : "keyword"
    },
    "job_title_role" : {
      "type" : "keyword"
    },
    "job_title_sub_role" : {
      "type" : "keyword"
    },
    "languages" : {
      "properties" : {
        "name" : {
          "type" : "keyword"
        },
        "proficiency" : {
          "type" : "integer",
          "doc_values" : false
        }
      }
    },
    "last_name" : {
      "type" : "keyword"
    },
    "linkedin_connections" : {
      "type" : "integer",
      "doc_values" : false
    },
    "linkedin_id" : {
      "type" : "keyword"
    },
    "linkedin_url" : {
      "type" : "keyword"
    },
    "linkedin_username" : {
      "type" : "keyword"
    },
    "location_address_line_2" : {
      "type" : "keyword"
    },
    "location_continent" : {
      "type" : "keyword"
    },
    "location_country" : {
      "type" : "keyword"
    },
    "location_full_address" : {
      "type" : "keyword"
    },
    "location_geo" : {
      "type" : "geo_point",
      "doc_values" : false
    },
    "location_last_updated" : {
      "type" : "keyword"
    },
    "location_locality" : {
      "type" : "keyword"
    },
    "location_metro" : {
      "type" : "keyword"
    },
    "location_name" : {
      "type" : "keyword"
    },
    "location_names" : {
      "type" : "keyword"
    },
    "location_postal_code" : {
      "type" : "keyword"
    },
    "location_region" : {
      "type" : "keyword"
    },
    "location_street_address" : {
      "type" : "keyword"
    },
    "middle_initial" : {
      "type" : "keyword"
    },
    "middle_name" : {
      "type" : "keyword"
    },
    "mobile_phone" : {
      "type" : "keyword"
    },
    "personal_emails" : {
      "type" : "keyword"
    },
    "phone_numbers" : {
      "type" : "keyword"
    },
    "profiles" : {
      "properties" : {
        "id" : {
          "type" : "keyword"
        },
        "network" : {
          "type" : "keyword"
        },
        "url" : {
          "type" : "keyword"
        },
        "username" : {
          "type" : "keyword"
        }
      }
    },
    "regions" : {
      "type" : "keyword"
    },
    "skills" : {
      "type" : "keyword"
    },
    "street_addresses" : {
      "properties" : {
        "address_line_2" : {
          "type" : "keyword"
        },
        "continent" : {
          "type" : "keyword"
        },
        "country" : {
          "type" : "keyword"
        },
        "full_address" : {
          "type" : "keyword"
        },
        "geo" : {
          "type" : "geo_point",
          "doc_values" : false
        },
        "locality" : {
          "type" : "keyword"
        },
        "metro" : {
          "type" : "keyword"
        },
        "name" : {
          "type" : "keyword"
        },
        "postal_code" : {
          "type" : "keyword"
        },
        "region" : {
          "type" : "keyword"
        },
        "street_address" : {
          "type" : "keyword"
        }
      }
    },
    "summary" : {
      "type" : "text"
    },
    "twitter_url" : {
      "type" : "keyword"
    },
    "twitter_username" : {
      "type" : "keyword"
    },
    "version_status" : {
      "properties" : {
        "contains" : {
          "type" : "keyword"
        },
        "current_version" : {
          "type" : "keyword",
          "index" : false
        },
        "previous_version" : {
          "type" : "keyword",
          "index" : false
        },
        "status" : {
          "type" : "keyword"
        }
      }
    },
    "work_email" : {
      "type" : "keyword"
    }
  }
}

All Field Descriptions

See this doc.


Did this page help you?