Person Enrichment

Enrich person by multiple parameters

curl --request POST \
  --url https://api.datalegion.ai/person/enrich \
  --header 'API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "city": "San Francisco",
  "company": "Acme Corp",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "state": "CA"
}
'

import requests

url = "https://api.datalegion.ai/person/enrich"

payload = {
    "city": "San Francisco",
    "company": "Acme Corp",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "state": "CA"
}
headers = {
    "API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    city: 'San Francisco',
    company: 'Acme Corp',
    email: 'john.doe@example.com',
    first_name: 'John',
    last_name: 'Doe',
    state: 'CA'
  })
};

fetch('https://api.datalegion.ai/person/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.datalegion.ai/person/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'city' => 'San Francisco',
    'company' => 'Acme Corp',
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'state' => 'CA'
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.datalegion.ai/person/enrich"

	payload := strings.NewReader("{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.datalegion.ai/person/enrich")
  .header("API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.datalegion.ai/person/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}"

response = http.request(request)
puts response.read_body

{
  "matches": [
    {
      "person": {
        "legion_id": "fdd85569-f0f0-53a9-bc60-089507193c28",
        "full_name": "jane marie doe",
        "first_name": "jane",
        "middle_name": "marie",
        "middle_initial": "m",
        "last_name": "doe",
        "last_initial": "d",
        "suffix": null,
        "prefix": null,
        "sex": "female",
        "birth_date": "1985-03-15",
        "birth_year": 1985,
        "birth_month": 3,
        "birth_day": 15,
        "age": 41,
        "work_email": "jane.doe@techcompany.com",
        "mobile_phone": "+15551234567",
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "linkedin_id": "123456789",
        "city": "san francisco",
        "state": "california",
        "state_code": "US-CA",
        "country": "united states",
        "country_code": "US",
        "job_title": "senior product manager",
        "company_name": "tech company",
        "company_domain": "techcompany.com",
        "company_industry": "technology, information and internet",
        "company_size": "1001-5000",
        "company_legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
        "company_linkedin_url": "https://www.linkedin.com/company/tech-company-inc",
        "company_linkedin_id": "12345678",
        "seniority_level": "senior",
        "job_function": "product",
        "expense_category": "research_and_development",
        "is_decision_maker": false,
        "is_platform_worker": false,
        "years_of_experience": 12,
        "avg_tenure_months": 24.5,
        "highest_degree_level": "masters",
        "current_jobs_last_confirmed": "2026-01-15",
        "current_jobs_last_updated": "2026-01-10",
        "current_location_last_confirmed": "2026-01-15",
        "current_location_last_updated": "2025-12-20",
        "linkedin_followers": 1250,
        "linkedin_connections": 500,
        "headline": {
          "cleaned": "senior product manager at tech company",
          "raw": [
            "Senior Product Manager at Tech Company"
          ]
        },
        "summary": {
          "cleaned": "experienced product leader with 10+ years in technology...",
          "raw": [
            "Experienced product leader with 10+ years in technology..."
          ]
        },
        "num_sources": 3,
        "last_seen": "2026-01-20",
        "build_version": "1.3.2_2026-07-12",
        "phones": [
          {
            "type": "mobile",
            "number": "+15551234567",
            "current": true,
            "confidence": "high",
            "last_seen": "2026-01-15",
            "num_sources": 3
          }
        ],
        "emails": [
          {
            "address": "jane.doe@techcompany.com",
            "type": "professional",
            "current": true,
            "validated": true,
            "confidence": "high",
            "last_seen": "2026-01-20",
            "num_sources": 2,
            "validation_status": "valid",
            "hash_sha256": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
            "hash_sha1": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
            "hash_md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
          }
        ],
        "locations": [
          {
            "street_address": "123 main st",
            "address_line_2": "apt 4b",
            "city": "san francisco",
            "state": "california",
            "state_code": "US-CA",
            "country": "united states",
            "country_code": "US",
            "continent": "north america",
            "continent_code": "NA",
            "postal_code": "94102",
            "postal_code_4": "1234",
            "geo": "37.7749,-122.4194",
            "raw": [
              "123 Main St, Apt 4B, San Francisco, CA 94102"
            ],
            "current": true,
            "num_sources": 2,
            "confidence": "high",
            "last_seen": "2026-01-10"
          }
        ],
        "experience": [
          {
            "title": {
              "cleaned": "senior product manager",
              "raw": [
                "Senior Product Manager"
              ]
            },
            "seniority_level": "senior",
            "job_function": "product",
            "expense_category": "research_and_development",
            "is_decision_maker": false,
            "is_platform_worker": false,
            "organization": {
              "name": {
                "cleaned": "tech company inc",
                "raw": [
                  "Tech Company Inc"
                ]
              },
              "website": "techcompany.com",
              "linkedin_url": "https://www.linkedin.com/company/tech-company-inc",
              "linkedin_id": "12345678",
              "legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
              "industry": "technology, information and internet",
              "size": "1001-5000"
            },
            "start_date": "2020-06-01",
            "end_date": null,
            "current": true,
            "tenure_months": 67,
            "description": {
              "cleaned": "leading product strategy for enterprise platform...",
              "raw": [
                "Leading product strategy for enterprise platform..."
              ]
            }
          }
        ],
        "education": [
          {
            "organization": {
              "name": {
                "cleaned": "stanford university",
                "raw": [
                  "Stanford University"
                ]
              },
              "website": "stanford.edu",
              "linkedin_url": "https://www.linkedin.com/school/stanford-university"
            },
            "degree": {
              "cleaned": "master of business administration",
              "raw": [
                "Master of Business Administration"
              ]
            },
            "degree_level": "masters",
            "field_of_study": {
              "cleaned": "business administration",
              "raw": [
                "Business Administration"
              ]
            },
            "start_date": "2015",
            "end_date": "2017",
            "current": false
          }
        ],
        "certifications": [
          {
            "name": {
              "cleaned": "project management professional",
              "raw": [
                "Project Management Professional",
                "PMP"
              ]
            },
            "institution": {
              "cleaned": "project management institute",
              "raw": [
                "Project Management Institute"
              ]
            },
            "credential_id": "1234567",
            "issue_date": "2018-06",
            "expiration_date": "2024-06"
          }
        ],
        "socials": [
          {
            "network": "linkedin",
            "url": "https://www.linkedin.com/in/janedoe",
            "username": "janedoe",
            "id": null,
            "current": true,
            "num_sources": 2,
            "confidence": "high",
            "last_seen": "2026-01-20"
          },
          {
            "network": "github",
            "url": "https://github.com/janedoe",
            "username": "janedoe",
            "id": "12345678",
            "current": true,
            "num_sources": 1,
            "confidence": "moderate",
            "last_seen": "2026-01-20"
          }
        ],
        "skills": [
          {
            "cleaned": "project management",
            "raw": [
              "Project Management"
            ]
          },
          {
            "cleaned": "data analysis",
            "raw": [
              "Data Analysis"
            ]
          }
        ],
        "languages": [
          {
            "cleaned": "english",
            "raw": [
              "English"
            ],
            "proficiency": "native"
          }
        ]
      },
      "match_metadata": {
        "matched_on": [
          "email",
          "first_name",
          "last_name"
        ],
        "match_type": "exact",
        "match_confidence": "high"
      }
    }
  ],
  "total": 1
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

POST

person

enrich

Enrich person by multiple parameters

curl --request POST \
  --url https://api.datalegion.ai/person/enrich \
  --header 'API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "city": "San Francisco",
  "company": "Acme Corp",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "state": "CA"
}
'

import requests

url = "https://api.datalegion.ai/person/enrich"

payload = {
    "city": "San Francisco",
    "company": "Acme Corp",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "state": "CA"
}
headers = {
    "API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    city: 'San Francisco',
    company: 'Acme Corp',
    email: 'john.doe@example.com',
    first_name: 'John',
    last_name: 'Doe',
    state: 'CA'
  })
};

fetch('https://api.datalegion.ai/person/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.datalegion.ai/person/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'city' => 'San Francisco',
    'company' => 'Acme Corp',
    'email' => 'john.doe@example.com',
    'first_name' => 'John',
    'last_name' => 'Doe',
    'state' => 'CA'
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Key: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.datalegion.ai/person/enrich"

	payload := strings.NewReader("{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.datalegion.ai/person/enrich")
  .header("API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.datalegion.ai/person/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"city\": \"San Francisco\",\n  \"company\": \"Acme Corp\",\n  \"email\": \"john.doe@example.com\",\n  \"first_name\": \"John\",\n  \"last_name\": \"Doe\",\n  \"state\": \"CA\"\n}"

response = http.request(request)
puts response.read_body

{
  "matches": [
    {
      "person": {
        "legion_id": "fdd85569-f0f0-53a9-bc60-089507193c28",
        "full_name": "jane marie doe",
        "first_name": "jane",
        "middle_name": "marie",
        "middle_initial": "m",
        "last_name": "doe",
        "last_initial": "d",
        "suffix": null,
        "prefix": null,
        "sex": "female",
        "birth_date": "1985-03-15",
        "birth_year": 1985,
        "birth_month": 3,
        "birth_day": 15,
        "age": 41,
        "work_email": "jane.doe@techcompany.com",
        "mobile_phone": "+15551234567",
        "linkedin_url": "https://www.linkedin.com/in/janedoe",
        "linkedin_id": "123456789",
        "city": "san francisco",
        "state": "california",
        "state_code": "US-CA",
        "country": "united states",
        "country_code": "US",
        "job_title": "senior product manager",
        "company_name": "tech company",
        "company_domain": "techcompany.com",
        "company_industry": "technology, information and internet",
        "company_size": "1001-5000",
        "company_legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
        "company_linkedin_url": "https://www.linkedin.com/company/tech-company-inc",
        "company_linkedin_id": "12345678",
        "seniority_level": "senior",
        "job_function": "product",
        "expense_category": "research_and_development",
        "is_decision_maker": false,
        "is_platform_worker": false,
        "years_of_experience": 12,
        "avg_tenure_months": 24.5,
        "highest_degree_level": "masters",
        "current_jobs_last_confirmed": "2026-01-15",
        "current_jobs_last_updated": "2026-01-10",
        "current_location_last_confirmed": "2026-01-15",
        "current_location_last_updated": "2025-12-20",
        "linkedin_followers": 1250,
        "linkedin_connections": 500,
        "headline": {
          "cleaned": "senior product manager at tech company",
          "raw": [
            "Senior Product Manager at Tech Company"
          ]
        },
        "summary": {
          "cleaned": "experienced product leader with 10+ years in technology...",
          "raw": [
            "Experienced product leader with 10+ years in technology..."
          ]
        },
        "num_sources": 3,
        "last_seen": "2026-01-20",
        "build_version": "1.3.2_2026-07-12",
        "phones": [
          {
            "type": "mobile",
            "number": "+15551234567",
            "current": true,
            "confidence": "high",
            "last_seen": "2026-01-15",
            "num_sources": 3
          }
        ],
        "emails": [
          {
            "address": "jane.doe@techcompany.com",
            "type": "professional",
            "current": true,
            "validated": true,
            "confidence": "high",
            "last_seen": "2026-01-20",
            "num_sources": 2,
            "validation_status": "valid",
            "hash_sha256": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
            "hash_sha1": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
            "hash_md5": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
          }
        ],
        "locations": [
          {
            "street_address": "123 main st",
            "address_line_2": "apt 4b",
            "city": "san francisco",
            "state": "california",
            "state_code": "US-CA",
            "country": "united states",
            "country_code": "US",
            "continent": "north america",
            "continent_code": "NA",
            "postal_code": "94102",
            "postal_code_4": "1234",
            "geo": "37.7749,-122.4194",
            "raw": [
              "123 Main St, Apt 4B, San Francisco, CA 94102"
            ],
            "current": true,
            "num_sources": 2,
            "confidence": "high",
            "last_seen": "2026-01-10"
          }
        ],
        "experience": [
          {
            "title": {
              "cleaned": "senior product manager",
              "raw": [
                "Senior Product Manager"
              ]
            },
            "seniority_level": "senior",
            "job_function": "product",
            "expense_category": "research_and_development",
            "is_decision_maker": false,
            "is_platform_worker": false,
            "organization": {
              "name": {
                "cleaned": "tech company inc",
                "raw": [
                  "Tech Company Inc"
                ]
              },
              "website": "techcompany.com",
              "linkedin_url": "https://www.linkedin.com/company/tech-company-inc",
              "linkedin_id": "12345678",
              "legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c",
              "industry": "technology, information and internet",
              "size": "1001-5000"
            },
            "start_date": "2020-06-01",
            "end_date": null,
            "current": true,
            "tenure_months": 67,
            "description": {
              "cleaned": "leading product strategy for enterprise platform...",
              "raw": [
                "Leading product strategy for enterprise platform..."
              ]
            }
          }
        ],
        "education": [
          {
            "organization": {
              "name": {
                "cleaned": "stanford university",
                "raw": [
                  "Stanford University"
                ]
              },
              "website": "stanford.edu",
              "linkedin_url": "https://www.linkedin.com/school/stanford-university"
            },
            "degree": {
              "cleaned": "master of business administration",
              "raw": [
                "Master of Business Administration"
              ]
            },
            "degree_level": "masters",
            "field_of_study": {
              "cleaned": "business administration",
              "raw": [
                "Business Administration"
              ]
            },
            "start_date": "2015",
            "end_date": "2017",
            "current": false
          }
        ],
        "certifications": [
          {
            "name": {
              "cleaned": "project management professional",
              "raw": [
                "Project Management Professional",
                "PMP"
              ]
            },
            "institution": {
              "cleaned": "project management institute",
              "raw": [
                "Project Management Institute"
              ]
            },
            "credential_id": "1234567",
            "issue_date": "2018-06",
            "expiration_date": "2024-06"
          }
        ],
        "socials": [
          {
            "network": "linkedin",
            "url": "https://www.linkedin.com/in/janedoe",
            "username": "janedoe",
            "id": null,
            "current": true,
            "num_sources": 2,
            "confidence": "high",
            "last_seen": "2026-01-20"
          },
          {
            "network": "github",
            "url": "https://github.com/janedoe",
            "username": "janedoe",
            "id": "12345678",
            "current": true,
            "num_sources": 1,
            "confidence": "moderate",
            "last_seen": "2026-01-20"
          }
        ],
        "skills": [
          {
            "cleaned": "project management",
            "raw": [
              "Project Management"
            ]
          },
          {
            "cleaned": "data analysis",
            "raw": [
              "Data Analysis"
            ]
          }
        ],
        "languages": [
          {
            "cleaned": "english",
            "raw": [
              "English"
            ],
            "proficiency": "native"
          }
        ]
      },
      "match_metadata": {
        "matched_on": [
          "email",
          "first_name",
          "last_name"
        ],
        "match_type": "exact",
        "match_confidence": "high"
      }
    }
  ],
  "total": 1
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Minimum Requirements

Every request must include at least one of the following:

A primary identifier (any single field is sufficient)
Name + context (name plus at least one contextual field)

Requests that don’t meet these requirements return 400 Bad Request.

Primary Identifiers

Any one of these fields is enough to look up a person on its own:

Field	Example
`email`	`jane.doe@example.com`
`phone`	`+15551234567`
`social_url`	`https://linkedin.com/in/janedoe`
`linkedin_id`	`123456789`
`legion_id`	`fdd85569-f0f0-53a9-bc60-089507193c28`
`email_hash`	SHA-256, SHA-1, or MD5 hash of normalized email

Name + Context

When no primary identifier is available, provide a name (first_name, last_name, or full_name) plus at least one contextual field:

Context	Fields	Example
Location	`city`, `state`, `country`, `postal_code`, `address`	`"first_name": "Jane", "last_name": "Doe", "city": "San Francisco", "state": "CA"`
Company	`company`	`"first_name": "Jane", "last_name": "Doe", "company": "Acme Corp"`
School	`school`	`"first_name": "Jane", "last_name": "Doe", "school": "Stanford University"`
Job title	`job_title`	`"first_name": "Jane", "last_name": "Doe", "job_title": "VP of Engineering"`
Birth date	`birth_date`	`"first_name": "Jane", "last_name": "Doe", "birth_date": "1985"`

You can combine multiple context fields for better match accuracy. For example, name + company + birth_date uses company for matching and birth_date to narrow results.

Name alone or location alone is not sufficient. The API requires name plus at least one contextual field for non-identifier lookups.

URLs and Domains

The company and school fields accept names, website URLs, or social URLs:

{"first_name": "Jane", "last_name": "Doe", "company": "Acme Corp"}
{"first_name": "Jane", "last_name": "Doe", "company": "acme.com"}
{"first_name": "Jane", "last_name": "Doe", "company": "https://www.acme.com"}
{"first_name": "Jane", "last_name": "Doe", "school": "https://linkedin.com/school/stanford-university"}

URLs and domains are resolved to the corresponding company or school name before matching.

Authorizations

API-Key

string

header

required

Body

application/json

Request model for person enrichment. Requires a primary identifier (email, phone, social_url, linkedin_id, legion_id, email_hash) OR name + context (location, company, school, job_title, birth_date).

string | null

Email address (will be normalized)

email_hash

string | null

SHA-256 (64 chars), SHA-1 (40 chars), or MD5 (32 chars) hash of normalized email address (for privacy)

phone

string | null

Phone number (will be normalized to E.164)

linkedin_id

string | null

LinkedIn numeric ID

Social profile URL (LinkedIn, Twitter/X, GitHub, Facebook - will be normalized and detected)

legion_id

string | null

Legion ID (exact match)

full_name

string | null

Full name (will be normalized)

first_name

string | null

First name (will be normalized)

last_name

string | null

Last name (will be normalized)

address

string | null

Full address string (will be parsed to extract city, state, postal_code, and country)

city

string | null

City name

state

string | null

State name or code

country

string | null

Country name or code

postal_code

string | null

Postal/ZIP code

job_title

string | null

Job title

company

string | null

Company name, website, or social URL

school

string | null

School name, website, or social URL

birth_date

string | null

Birth date for matching or narrowing name-based results (YYYY-MM-DD, YYYY-MM, or YYYY). Can be used as name + birth_date lookup or as a qualifier on other name-based combos.

multiple_results

boolean

default:false

If true, return multiple matches sorted by confidence

limit

integer

default:2

Maximum number of results to return when multiple_results=true (default: 2, max: 10)

Required range: 1 <= x <= 10

min_confidence

string | null

Minimum match confidence level to include in results: 'high', 'moderate', or 'low'. Matches below this threshold will be filtered out.

titlecase

boolean

default:false

If true, format text fields in title case (names, job titles, company names, locations, skills, headlines). Raw fields, IDs, URLs, codes, and confidence fields are excluded.

required_fields

string | null

Comma-separated list of fields that must be present, else the match is filtered out. Supports top-level fields ('work_email,phones'), a non-empty list subfield ('emails.type'), or a subfield equal to a value ('emails.type:personal', 'phones.type:mobile', 'socials.network:linkedin'). Unknown field names or out-of-range enum values return HTTP 400.

include_fields

string | null

Comma-separated list of fields to include in response. If omitted, all fields are returned.

exclude_fields

string | null

Comma-separated list of fields to exclude from response. Applied after include_fields filter.

pretty_print

boolean

default:false

If true, pretty-print JSON response with indentation.

Response

Success - person(s) found

Multiple person matches response.

matches

PersonMatchResponse · object[]

required

List of matches sorted by confidence (descending). Capped at the request's limit.

Show child attributes

total

integer

required

For /person/search and /person/discover, the total number of rows matching the query's WHERE clause across the database (not just this page). For /person/enrich, the number of matches found for the input identifier. On search/discover, if the exact count exceeds its time budget (broad, low-selectivity queries) it falls back to the query planner's row estimate, and if that is unavailable, to the size of the returned page; the response header Total-Count-Status reports which (exact, estimate, or page).

API Overview Person Search (Beta)

API Reference

Person

Company

Utilities

Minimum Requirements

Primary Identifiers

Name + Context

URLs and Domains

Authorizations

Body

Response

​Minimum Requirements

​Primary Identifiers

​Name + Context

​URLs and Domains

Authorizations

Body

Response

Minimum Requirements

Primary Identifiers

Name + Context

URLs and Domains