> ## 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.

> 👍 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.

## 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](https://docs.peopledatalabs.com/docs/enrichment-api).

The [list of supported inputs](https://docs.peopledatalabs.com/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`](https://docs.peopledatalabs.com/docs/identify-api-input-parameters#first_name) | `sean`             |
| [`last_name`](https://docs.peopledatalabs.com/docs/identify-api-input-parameters#last_name)   | `thorne`           |
| [`company`](https://docs.peopledatalabs.com/docs/identify-api-input-parameters#company)       | `people data labs` |
| [`pretty`](https://docs.peopledatalabs.com/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:

```python Python3 SDK
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)
```

```shell cURL
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
// 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
# 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
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
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)   
```

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
{
  "status": 200,
  "matches": [
    {
      "data": {
        ...
      },
      "match_score": 92,
      "matched_on": [
        "company",
        "name"
      ]
    },
    {
      "data": {
        ...
      },
      "match_score": 5,
      "matched_on": [
        "name"
      ]
    },
    ...
  ]
}

```

> 📘 Got a Different Result?
>
> If you didn't get this response, check out our [Errors](https://docs.peopledatalabs.com/docs/errors) page for more information.

Each object in the `matches` array contains a unique profile from our Person Dataset as well as a [`match_score`](https://docs.peopledatalabs.com/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.