Skip to main content
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"
}
'
{
  "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.0_2026-05-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
}

​
Minimum Requirements

Every request must include at least one of the following:
  1. A primary identifier (any single field is sufficient)
  2. 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:
FieldExample
emailjane.doe@example.com
phone+15551234567
social_urlhttps://linkedin.com/in/janedoe
linkedin_id123456789
legion_idfdd85569-f0f0-53a9-bc60-089507193c28
email_hashSHA-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:
ContextFieldsExample
Locationcity, state, country, postal_code, address"first_name": "Jane", "last_name": "Doe", "city": "San Francisco", "state": "CA"
Companycompany"first_name": "Jane", "last_name": "Doe", "company": "Acme Corp"
Schoolschool"first_name": "Jane", "last_name": "Doe", "school": "Stanford University"
Job titlejob_title"first_name": "Jane", "last_name": "Doe", "job_title": "VP of Engineering"
Birth datebirth_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).

​
email
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_url
string | null

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.

​
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 count subquery fails or times out, this falls back to the size of the returned page; the response header Total-Count-Status distinguishes the two cases.