> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peopledatalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart - Person Search API

## Getting Started

In order to use our Person Search API, you must have an active API key. You can look up your API key by logging into our [self-serve dashboard](https://www.peopledatalabs.com/main/api-keys) and going to the **API Keys** section.

<Tip>
  **Need an API Key?**

  If you don't have an API key, you can easily create one by [signing up](https://peopledatalabs.com/signup) for a self-serve account. For more information, check out our [Self-Serve Quickstart Guide](https://blog.peopledatalabs.com/post/self-signup-api-quickstart), which walks you through the sign-up process as well as shows you how to use the self-serve API dashboard.
</Tip>

## Simple Example

As mentioned in the [Overview](/docs/person-search-api#overview), the Person Search API is a means of filtering and segmenting individual profiles included in our [Person Dataset](/docs/fields). In order to use the Person Search API, **you will need to use either an [Elasticsearch query](/docs/input-parameters-person-search-api#query) or an [SQL query](/docs/input-parameters-person-search-api#sql)**.

Here's a quick example to search for profiles whose `location_country` is `mexico`, whose `job_title_role` is `health`, and whose record includes at least one `phone_numbers`:

<Danger>
  **Heads Up! Credit Usage**

  Person Search API calls cost the number of **total search results** returned.

  If you are making a search that could have a large number of results, make sure to use the [`size` parameter](/docs/input-parameters-person-search-api#size) to set the maximum number of results and cap your credit usage.
</Danger>

<CodeGroup>
  ```python Python3 SDK (Elasticsearch) expandable theme={null}
  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': {'location_country': "mexico"}},
              {'term': {'job_title_role': "health"}},
              {'exists': {'field': "phone_numbers"}}
        ]
      }
    }
  }

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

  # Pass the parameters object to the Person Search API
  response = CLIENT.person.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)
  ```

  ```python Python3 SDK (SQL) expandable theme={null}
  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 person
    WHERE location_country='mexico'
    AND job_title_role='health'
    AND phone_numbers IS NOT NULL;
   """

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

  # Pass the parameters object to the Person Search API
  response = CLIENT.person.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)
  ```

  ```bash cURL theme={null}
  # Elasticsearch
  curl -X GET 'https://api.peopledatalabs.com/v5/person/search' \
  -H 'X-Api-Key: xxxx' \
  --data-raw '{
    "size": 10,
    "query": {
      "bool": {
        "must": [
          {"term": {"location_country": "mexico"}},
          {"term": {"job_title_role": "health"}},
          {"exists": {"field": "phone_numbers"}}
        ]
      }
    }
  }'

  # SQL
  curl -X GET \
    'https://api.peopledatalabs.com/v5/person/search' \
    -H 'X-Api-Key: xxxx' \
    --data-raw '{
      "size": 10,
      "sql": "SELECT * FROM person WHERE location_country='\''mexico'\'' AND job_title_role='\''health'\'' AND phone_numbers IS NOT NULL;"
  }'
  ```

  ```javascript JavaScript (Elasticsearch) expandable theme={null}
  // 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: {location_country: "mexico"}}, 
          {term: {job_title_role: "health"}}, 
          {exists: {field: "phone_numbers"}}
        ]
      }
    }
  }

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

  // Pass the parameters object to the Person Search API
  PDLJSClient.person.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);
  });
  ```

  ```javascript JavaScript (SQL) theme={null}
  // 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 person 
                    WHERE location_country='mexico' 
                    AND job_title_role='health'
                    AND phone_numbers IS NOT NULL;`

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

  // Pass the parameters object to the Person Search API
  PDLJSClient.person.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);
  });
  ```

  ```ruby Ruby (Elasticsearch) expandable theme={null}
  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": {"location_country": "mexico"}},
              {"term": {"job_title_role": "health"}},
              {"exists": {"field": "phone_numbers"}}
        ]
      }
    }
  }

  # Pass parameters to the Person Search API
  response = Peopledatalabs::Search.person(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
  ```

  ```ruby Ruby (SQL) theme={null}
  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 person
    WHERE location_country='mexico'
    AND job_title_role='health'
    AND phone_numbers IS NOT NULL;
   """

  # Pass parameters to the Person Search API
  response = Peopledatalabs::Search.person(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
  ```

  ```go Go (Elasticsearch) expandable theme={null}
  package main

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

  // 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{}{"location_country": "mexico"}},
                      {"term": map[string]interface{}{"job_title_role": "health"}},
                      {"exists": map[string]interface{}{"field": "phone_numbers"}},
                  },
              },
          },
      }

      // 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 Person Search API
      response, err := client.Person.Search(context.Background(), 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)
      }  
  }
  ```

  ```go Go (SQL) expandable theme={null}
  package main

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

  // 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 person" +
          " WHERE location_country='mexico'" +
          " AND job_title_role='health'" +
          " AND phone_numbers IS NOT NULL;"

      // 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 Person Search API
      response, err := client.Person.Search(context.Background(), 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)
      }  
  }
  ```

  ```python Python3 (Elasticsearch) expandable theme={null}
  import requests, json

  # Set your API key
  API_KEY = "YOUR API KEY"

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

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

  # Create an Elasticsearch query
  ES_QUERY = {
    'query': {
      'bool': {
          'must': [
              {'term': {'location_country': "mexico"}},
              {'term': {'job_title_role': "health"}},
              {'exists': {'field': "phone_numbers"}}
        ]
      }
    }
  }

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

  # Pass the parameters object to the Person Search API
  response = requests.get(
    PDL_URL,
    headers=HEADERS,
    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)
  ```

  ```python Python3 (SQL) expandable theme={null}
  import requests, json

  # Set your API key
  API_KEY = "YOUR API KEY"

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

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

  # Create an SQL query
  SQL_QUERY = \
  """
    SELECT * FROM person
    WHERE location_country='mexico'
    AND job_title_role='health'
    AND phone_numbers IS NOT NULL;
   """

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

  # Pass the parameters object to the Person Search API
  response = requests.get(
    PDL_URL,
    headers=HEADERS,
    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)
  ```
</CodeGroup>

The returned API response is a list of the records in our dataset that match the request query in the format:

```json JSON theme={null}
{
  "status": 200,
  "data": [
    {
      "id": "qEnOZ5Oh0poWnQ1luFBfVw_0000",
      "full_name": "sean thorne",
      ...
    },
    ...
  ],
"scroll_token": "1117$12.176522"  
"total": 94
}
```

The objects in the `data` array will follow the [Person Schema](/docs/fields). For a full example, see the [Example Person Record](/docs/example-record).

### Troubleshooting

If you don't get this response, check out our [Errors](/docs/errors) page for more information.

***


## Related topics

- [Quickstart - Company Search API](/docs/quickstart-company-search-api.md)
- [Quickstart - Job Posting Search API](/docs/quickstart-job-posting-search-api.md)
- [Person Search API](/docs/person-search-api.md)
- [Quickstart - Person Identify API](/docs/quickstart-person-identify-api.md)
- [Quickstart - Person Enrichment API](/docs/quickstart-person-enrichment-api.md)