> ## 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 Identify API

## Getting Started

In order to use the Person Identify 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. 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 how to use the self-serve API dashboard.
</Tip>

## Simple Example

Let's say that you want to find all the profiles associated with the CEO of People Data Labs, Sean Thorne. The Person Identify API is the perfect tool for doing this, as it allows you to find multiple profiles using  a set of input characteristics, similar to our [Person Enrichment API](/docs/enrichment-api).

The [list of supported inputs](/docs/identify-api-input-parameters) includes names, email addresses, company information, profiles and much more. In this case, we'll assume all we have is Sean's name and his company's name:

**Input Parameters**

| Parameter Name                                                 | Parameter Value    |
| -------------------------------------------------------------- | ------------------ |
| [`first_name`](/docs/identify-api-input-parameters#first_name) | `sean`             |
| [`last_name`](/docs/identify-api-input-parameters#last_name)   | `thorne`           |
| [`company`](/docs/identify-api-input-parameters#company)       | `people data labs` |
| [`pretty`](/docs/identify-api-input-parameters#pretty)         | `True`             |

Using this information, you can now query the Person Identify API to find the profiles associated with Sean:

<CodeGroup>
  ```python Python3 SDK 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 a parameters JSON object
  PARAMS = {
   "first_name": "sean", 
   "last_name": "thorne", 
   "company": "people data labs",
   "pretty": True
  }

  # Pass the parameters object to the Person Identify API
  response_data = CLIENT.person.identify(**PARAMS).json()

  # Check for successful response
  if json_response["status"] == 200:
     # Create a list of matches
     identities = response_data['matches']

     # Print the matches in JSON format
     print(identities)
     print(f"Found {len(identities)} identities!")
  else:
     print("Identify unsuccessful. See error and try again.")
     print("error:", json_response)
  ```

  ```bash cURL theme={null}
  API_KEY="ENTER YOUR API KEY HERE"
  curl -X GET -G \
   "https://api.peopledatalabs.com/v5/person/identify"\
   -H "X-Api-Key: ${API_KEY}" \
   --data-urlencode 'first_name=sean'\
   --data-urlencode 'last_name=thorne'\
   --data-urlencode 'company="people data labs"'\
   --data-urlencode 'pretty=True'
  ```

  ```javascript JavaScript theme={null}
  // See https://github.com/peopledatalabs/peopledatalabs-js
  import PDLJS from 'peopledatalabs';

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

  // Create a parameters JSON object
  const params = {
    first_name: "sean", 
    last_name: "thorne", 
    company: "people data labs",
    pretty: true,
  }

  // Pass the parameters object to the Person Identify API
  PDLJSClient.person.identify(params).then((data) => {
    // Create a list of matches
    var identities = data["matches"]
    
    // Print the matches in JSON format
    console.log(identities);
    console.log(`Found ${identities.length} identities!`)
  }).catch((error) => {
    console.log("Identify unsuccessful. See error and try again.")
    console.log(error);
  });
  ```

  ```ruby Ruby theme={null}
  # See https://github.com/peopledatalabs/peopledatalabs-ruby
  require 'peopledatalabs'

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

  # Create a parameters JSON object
  PARAMS = {
   "first_name": "sean", 
   "last_name": "thorne", 
   "company": "people data labs",
   "pretty": true
  }

  # Pass the parameters object to the Person Identify API
  response = Peopledatalabs::Identify.person(params: PARAMS)

  # Check for successful response
  if json_response['status'] == 200

      # Create a list of matches
      identities = response['matches']

      # Print the matches in JSON format
      puts identities
      puts "Found #{identities.length()} identities!"
      end
  else
      puts "Identify unsuccessful. See error and try again."
      puts "error: #{json_response}"
  end
  ```

  ```go Go expandable theme={null}
  package main

  import (
      "fmt"
      "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 a parameters JSON object
      params := pdlmodel.IdentifyPersonParams {
          BaseParams: pdlmodel.BaseParams {
              Pretty: true,
          },
          PersonParams: pdlmodel.PersonParams {
              FirstName: []string{"sean"},
              LastName: []string{"thorne"},
              Company: []string{"people data labs"},
          },
      }
      
      // Pass the parameters object to the Person Identify API
      response, err := client.Person.Identify(context.Background(), params)
      // Check for successful response
      if err == nil {
          // Create a list of matches
          identities := response.Matches
          // Convert the matches to JSON
          jsonResponse, jsonErr := json.Marshal(identities)
          // Print the matches
          if (jsonErr == nil) {
              fmt.Println(string(jsonResponse))
          }
          
          fmt.Printf("Found %d identities!\n", len(identities))
      } else {
          fmt.Println("Identify unsuccessful. See error and try again.")
          fmt.Println("error:", err)
      }
  }
  ```

  ```python Python3 theme={null}
  import requests

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

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

  # Create a parameters JSON object
  PARAMS = {
   "first_name": "sean", 
   "last_name": "thorne", 
   "company": "people data labs",
   "pretty": True,
   "api_key": API_KEY
  }

  # Pass the parameters object to the Person Identify API
  json_response = requests.get(PDL_URL, params=PARAMS).json()

  # Check for successful response
  if json_response['status'] == 200:
     # Create a list of matches
     identities = json_response['matches']

     # Print the matches in JSON format
     print(identities)
     print(f"Found {len(identities)} identities!")

  else:
     print("Identify unsuccessful. See error and try again.")
     print("error:", json_response)   
  ```
</CodeGroup>

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

```json JSON theme={null}
{
  "status": 200,
  "matches": [
    {
      "data": {
        ...
      },
      "match_score": 92,
      "matched_on": [
        "company",
        "name"
      ]
    },
    {
      "data": {
        ...
      },
      "match_score": 5,
      "matched_on": [
        "name"
      ]
    },
    ...
  ]
}

```

<Info>
  **Got a Different Result?**

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

Each object in the `matches` array contains a unique profile from our Person Dataset as well as a [`match_score`](/docs/identify-api-output-response#matchesmatch_score), which the API uses to sort the profiles in the `matches` array. You can use this profile data for various purposes. Typically, our users tend to fuse this with additional data to build more comprehensive identities.


## Related topics

- [Person Identify API](/docs/person-identify-api.md)
- [Reference - Person Identify API](/docs/reference-person-identify-api.md)
- [Examples - Person Identify API](/docs/examples-person-identify-api.md)
- [Quickstart - Person Enrichment API](/docs/quickstart-person-enrichment-api.md)
- [Quickstart - Person Search API](/docs/quickstart-person-search-api.md)