Skip to main content
POST
/
person
/
discover
Discover persons using natural language
curl --request POST \
  --url https://api.example.com/person/discover \
  --header 'API-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "VP of Engineering at fintech companies in New York",
  "limit": 10
}
'
{
  "matches": [
    {
      "person": {
        "legion_id": "a7e91c34-2b8f-4d6e-9c1a-3f5b7d8e2a10",
        "full_name": "michael chen",
        "first_name": "michael",
        "last_name": "chen",
        "city": "new york",
        "state": "new york",
        "state_code": "US-NY",
        "country": "united states",
        "country_code": "US",
        "job_title": "vp of engineering",
        "company_name": "fintech startup",
        "company_domain": "fintechstartup.com",
        "company_industry": "financial services",
        "company_size": "201-500",
        "seniority_level": "vp",
        "job_function": "engineering",
        "is_decision_maker": true,
        "is_platform_worker": false,
        "work_email": "michael.chen@fintechstartup.com",
        "linkedin_url": "https://www.linkedin.com/in/michaelchen",
        "linkedin_id": "987654321",
        "years_of_experience": 18,
        "last_seen": "2026-01-18"
      }
    }
  ],
  "total": 1
}

​
How It Works

Describe who you’re looking for in plain English. The API translates your description into a SQL query and returns matching profiles. The generated SQL query is returned in the Generated-Query response header so you can see exactly how your description was interpreted.

​
Example Queries

software engineers in Austin who worked at Meta
marketing directors at Fortune 500 companies in New York
nurses in California with 10+ years of experience
VP of Sales at SaaS companies with over 1000 employees
data scientists with Python skills in the Bay Area
For precise control over filtering, use Person Search with SQL syntax instead.

Authorizations

​
API-Key
string
header
required

Body

application/json

Request model for natural language person discovery.

​
query
string
required

Natural language description of who you're looking for

Required string length: 3 - 1000
​
limit
integer

Maximum number of results to return

Required range: 1 <= x <= 100
​
titlecase
boolean
default:false

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

​
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 - persons found matching natural language query. Returns Generated-Query header with the SQL query.

Multiple person matches response.

​
matches
PersonMatchResponse · object[]
required

List of matches sorted by confidence (descending)

​
total
integer
required

Total number of matches found