Bulk Person Enrichment API

The endpoint for the bulk enrichment api is /v5/person/bulk.

Bulk Endpoint

Up to 100 persons can be enriched in a single HTTP request using the /v5/person/bulk endpoint. Enrichments executed against the bulk endpoint must be a POST. The request body of a bulk enrichment request must contain an array, requests, with 1-100 individual request objects, each containing an object params of request parameters. A JSON schema describing the structure of a /v5/person/bulk enrichment response can be found here.

import json

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

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

data = {
   "requests": [
       {
           "params": {
               "profile": ["linkedin.com/in/seanthorne"]
           }
       },
       {
           "params": {
               "profile": ["linkedin.com/in/randrewn"]
           }
       }
   ]
}

json_responses = client.person.bulk(**data).json()

for response in json_responses:
  if response["status"] == 200:

    record = response['data']

    print(
      record['work_email'],
      record['full_name'],
      record['job_title'],
      record['job_company_name']
    )

    print(f"successfully enriched profile with pdl data")

    # Save enrichment data to json file
    with open(f"my_pdl_enrichment.{record['linkedin_username']}.jsonl", "w") as out:
      out.write(json.dumps(record) + "\n")
  else:
    print("Enrichment unsuccessful. See error and try again.")
    print("error:", response)
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

import fs from 'fs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const records = {
  requests: [
    {
      params: {
        profile: ['linkedin.com/in/seanthorne']
      }
    },
    {
      params: {
        profile: ['linkedin.com/in/randrewn']
      }
    }
  ]
};

PDLJSClient.person.bulk(records).then((data) => {
    var record
    
    for (let response in data) {
    
        record = data[response].data
     
        console.log(
            record["work_email"],
            record["full_name"],
            record["job_title"],
            record["job_company_name"],
            )
        
        console.log("successfully enriched profile with pdl data")
    
        fs.writeFile(`my_pdl_enrichment.${record["linkedin_username"]}.jsonl`, Buffer.from(JSON.stringify(record)), (err) => {
            if (err) throw err;
        });
    }
}).catch((error) => {
    console.log("Enrichment unsuccessful. See error and try again.")
    console.log(error);
});
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

data = {
   "requests": [
       {
           "params": {
               "profile": ["linkedin.com/in/seanthorne"]
           }
       },
       {
           "params": {
               "profile": ["linkedin.com/in/randrewn"]
           }
       }
   ]
}

json_response = Peopledatalabs::Bulk.people(params: data)
items = json_response['items']

items.each do |response|
    if response['status'] == 200
        record = response['data']
    
        puts \
            "#{record['work_email']}\
             #{record['full_name']}\
             #{record['job_title']}\
             #{record['job_company_name']}"
    
        puts "successfully enriched profile with pdl data"
    
        # Save enrichment data to json file
        File.open("my_pdl_enrichment.#{record['linkedin_username']}.jsonl", "w") do |out|
            out.write(JSON.dump(record) + "\n")
        end
    else
        puts "Enrichment unsuccessful. See error and try again."
        puts "error: #{json_response}"
    end
end
package main

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

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

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

    client := pdl.New(apiKey)
    
    params := pdlmodel.BulkEnrichPersonParams {
        Requests: []pdlmodel.BulkEnrichSinglePersonParams {
            {
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"linkedin.com/in/seanthorne"},
                },
            },
            {
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"linkedin.com/in/randrewn"},
                },
           },
        },
    }

    responses, err := client.Person.BulkEnrich(params)
    
    for _, response := range responses {
        if err == nil {
            jsonResponse, jsonErr := json.Marshal(response.Data)
            if jsonErr == nil {
                var record map[string]interface{}
                json.Unmarshal(jsonResponse, &record)
                fmt.Println(
                            record["work_email"], 
                            record["full_name"], 
                            record["job_title"], 
                            record["job_company_name"])
        
                fmt.Println("successfully enriched profile with pdl data")
        
                // Save enrichment data to json file
                out, outErr := os.Create(fmt.Sprintf("my_pdl_enrichment.%s.jsonl", record["linkedin_username"]))
                defer out.Close()
                if outErr == nil {
                    out.WriteString(string(jsonResponse) + "\n")
                }
                out.Sync()
            }
        } else {
            fmt.Println("Enrichment unsuccessful. See error and try again.")
            fmt.Println("error:", err)
        }
    }

}
import requests
import json

API_KEY = # Enter your API key here

headers = {
   'X-Api-Key': API_KEY,
   'Content-Type': 'application/json',
}
 
data = {
   "requests": [
       {
           "params": {
               "profile": ["linkedin.com/in/seanthorne"]
           }
       },
       {
           "params": {
               "profile": ["linkedin.com/in/randrewn"]
           }
       }
   ]
}
json_responses = requests.post(
   'https://api.peopledatalabs.com/v5/person/bulk',
   headers=headers,
   json=data
).json()
 
for response in json_responses:
  if response["status"] == 200:

    record = response['data']

    print(
      record['work_email'],
      record['full_name'],
      record['job_title'],
      record['job_company_name']
    )

    print(f"successfully enriched profile with pdl data")

    # Save enrichment data to json file
    with open(f"my_pdl_enrichment.{record['linkedin_username']}.jsonl", "w") as out:
      out.write(json.dumps(record) + "\n")
  else:
    print("Enrichment unsuccessful. See error and try again.")
    print("error:", response)

Responses are returned as an array of response objects.

[
    {"status": 200, "likelihood": 10, "data": ...},
    {"status": 200, "likelihood": 10, "data": ...}
]

Tracking Responses

Response objects are always returned in the same order as they were defined in the requests array. However you can also add an object metadata to each request, containing any information specific to that request. If metadata is defined in a request object, it will be returned, unchanged in that request's corresponding response object:

import json

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

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

data = {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = client.person.bulk(**data).json()

print(json.dumps(json_response))
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const records = {
  requests: [
    {
      metadata: {
        user_id: "123"
      },
      params: {
        profile: ['linkedin.com/in/seanthorne'],
            location: "SF Bay Area",
            name: "Sean F Thorne"
      }
    },
    {
      metadata: {
        user_id: "345"
      },
      params: {
        profile: ["https://www.linkedin.com/in/haydenconrad/"],
        first_name: "Hayden",
        last_name: "Conrad"
      }
    }
  ]
};

PDLJSClient.person.bulk(records).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

data = {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = Peopledatalabs::Bulk.people(params: data)

puts JSON.dump(json_response)
package main

import (
    "fmt"
    "encoding/json"
)

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

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

    client := pdl.New(apiKey)
    
    params := pdlmodel.BulkEnrichPersonParams {
        Requests: []pdlmodel.BulkEnrichSinglePersonParams {
            {
                Metadata: map[string]string {
                    "user_id": "123",
                },
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"linkedin.com/in/seanthorne"},
                    Location:  []string{"SF Bay Area"},
                    Name:  []string{"Sean F. Thorne"},
                },
            },
            {
                Metadata: map[string]string {
                    "user_id": "345",
                },
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"https://www.linkedin.com/in/haydenconrad/"},
                    FirstName:  []string{"Hayden"},
                    LastName:  []string{"Conrad"},
                },
           },
        },
    }

    response, err := client.Person.BulkEnrich(params)
    
    if err == nil {
        data, jsonErr := json.Marshal(response)
        if (jsonErr == nil) {
            fmt.Println(string(data))
        }
    }
 }
import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {
    "requests": [
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
).json()

print(json.dumps(json_response))
[
    {"metadata": {"user_id": "123"}, "status": 200, "likelihood": 10, "data": ...},
    {"metadata": {"user_id": "345"}, "status": 200, "likelihood": 10, "data": ...}
]

Any of the response filtering or formatting params documented in the Parameters section can be defined globally for all request objects:

import json

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

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

data = {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = client.person.bulk(**data).json()

print(json.dumps(json_response))
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}'
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const records = {
  required: "emails AND profiles",
  requests: [
    {
      params: {
        profile: ['linkedin.com/in/seanthorne'],
            location: "SF Bay Area",
            name: "Sean F Thorne"
      }
    },
    {
      params: {
        profile: ["https://www.linkedin.com/in/haydenconrad/"],
        first_name: "Hayden",
        last_name: "Conrad"
      }
    }
  ]
};

PDLJSClient.person.bulk(records).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

data = {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = Peopledatalabs::Bulk.people(params: data)

puts JSON.dump(json_response)
package main

import (
    "fmt"
    "encoding/json"
)

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

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

    client := pdl.New(apiKey)
    
    params := pdlmodel.BulkEnrichPersonParams {
        Required: "emails AND profiles",
        Requests: []pdlmodel.BulkEnrichSinglePersonParams {
            {
                Params: pdlmodel.PersonParams {
                    Profile:  []string{"linkedin.com/in/seanthorne"},
                    Location:  []string{"SF Bay Area"},
                    Name:  []string{"Sean F. Thorne"},
                },
            },
            {
                 Params: pdlmodel.PersonParams {
                    Profile:  []string{"https://www.linkedin.com/in/haydenconrad/"},
                    FirstName:  []string{"Hayden"},
                    LastName:  []string{"Conrad"},
                },
           },
        },
    }

    response, err := client.Person.BulkEnrich(params)
    
    if err == nil {
        data, jsonErr := json.Marshal(response)
        if (jsonErr == nil) {
            fmt.Println(string(data))
        }
    }
 }
import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {
    "required": "emails AND profiles",
    "requests": [
        {
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"]
            }
        },
        {
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad"
            }
        }
    ]
}

json_response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
).json()

print(json.dumps(json_response))

Response filtering/formatting params defined locally in an individual request object will override those defined in the request body root.

Any response object in a /v5/person/bulk response will either have a status code of 200, 404, or 400. Any valid /v5/person/bulk will return with a status code of 200.

The number of remaining enrichment matches in your account will be deducted by the number of 200 responses in a bulk enrichment request as though each request was made individually.

Any malformed, unauthenticated, or throttled request will return errors in the same format as documented in the errors section.

import json

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

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

data = {"required": "names"}

try:
    json_response = client.person.bulk(**data).json()
except Exception as err:
    print(err);
curl -X POST "https://api.peopledatalabs.com/v5/person/bulk" \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: XXX' \
-d ' {
    "required": "names"
}'
// See https://github.com/peopledatalabs/peopledatalabs-js
import PDLJS from 'peopledatalabs';

const PDLJSClient = new PDLJS({ apiKey: "YOUR API KEY" });

const records = {
  required: "names"
};

PDLJSClient.person.bulk(records).then((data) => {
  console.log(data);
}).catch((error) => {
  console.log(error);
});
require 'json'

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

Peopledatalabs.api_key = 'YOUR API KEY'

data = {"required": "names"}

json_response = Peopledatalabs::Bulk.people(params: data)

if json_response['status'] != 200
    puts json_response['error']['message']
end
package main

import (
    "fmt"
     "encoding/json"
)

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

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

    client := pdl.New(apiKey)
    
    data := pdlmodel.BulkEnrichPersonParams {
        Required: "names",
    }

    response, err := client.Person.BulkEnrich(data)
    
    if err == nil {
        fmt.Println(response)
    } else {
        message, jsonErr := json.Marshal(err)
        if jsonErr == nil {
            fmt.Println(string(message))
        }
    }
 }
import requests
import json

headers = {
    'Content-Type': 'application/json',
    'X-api-key': #YOURAPIKEY
}

data = {"required": "names"}

response = requests.post(
  'https://api.peopledatalabs.com/v5/person/bulk',
  headers=headers,
  json=data
)
{
    "status": 400,
    "error": {
        "type": "invalid_request_error",
        "message": "Request object must contain `requests` field"
    }
} 

Did this page help you?