Data Legion

Clean and normalize one or more data fields. Pass a dict of field names to values. Supported person fields: email, phone, full_name, first_name, last_name, state, country, social_url, school. Supported company fields: company, domain, linkedin_company_url, ticker_symbol. Example: {"email": "[email protected]", "phone": "(555) 123-4567"}

utility_clean

Enrich a company by domain, name, LinkedIn, or ticker symbol. Requires at least one identifier. The 'industry' field narrows name-based matching but is not a standalone lookup. It must be a lowercase LinkedIn Industry V2 taxonomy value (e.g. 'software development') — a free-text value matches nothing and silently zeroes the results. Returns company profile including employee counts, workforce analytics, hiring/attrition trends, and distribution breakdowns. Key response fields: `name` (object: `display`, `cleaned`, `raw`), `domain`, `industry`, `size` (band), `founded`, `type`, `description`, `linkedin_url`, `linkedin_employee_count` (the company's LinkedIn figure), `legion_employee_count` (people Data Legion tracks at the company; a floor, not a full headcount), `legion_new_hire_count`, `legion_attrition_count`, `legion_employee_growth_rate`, `legion_employee_count_by_month`, `legion_seniority_distribution`, `legion_job_function_distribution`, `tickers`, `socials`, `domains`. The hiring, attrition, growth and turnover windows (1m/3m/6m/12m) end at the last month of `legion_employee_count_by_month`, not today. Job changes reach profiles months after they happen, so the most recent months fill in over later releases: read a low recent month as incomplete data, not a hiring freeze. `min_confidence`: one of `high`, `moderate`, `low` — drops matches below that confidence. Any other value is treated as no minimum. `required_fields`: comma-separated filter — matches missing these are dropped. Use response field names (`domain,socials`), a non-empty list subfield (`socials.network`), or a subfield equal to a value (`type:public`, `socials.network:linkedin`). Unknown field names or out-of-range enum values return HTTP 400. `include_fields` / `exclude_fields`: comma-separated response fields to keep or drop (supports dot paths). Use to trim the payload. Unknown field names are rejected with the valid list.

company_enrich

Enrich a person by email, phone, name, social URL, or other identifiers. Requires at least one primary identifier (email, phone, social_url, linkedin_id, legion_id, email_hash) OR name + context (location, company, school, job_title, birth_date). Returns detailed person profile including contact info, work experience, education, skills, and more. Each successful match consumes one credit. Field access is determined by the team's contract. Key response fields: `full_name`, `job_title`, `seniority_level`, `job_function`, `company_name`, `company_domain`, `work_email`, `mobile_phone`, `emails`, `phones`, `linkedin_url`, `city`, `state`, `country`, `experience`, `education`, `skills`, `last_seen`. `emails` and `phones` are lists with `address`/`number` and `type`. `min_confidence`: one of `high`, `moderate`, `low` — drops matches below that confidence. Any other value is treated as no minimum. `required_fields`: comma-separated filter — matches missing these are dropped. Use response field names (`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` / `exclude_fields`: comma-separated response fields to keep or drop (supports dot paths, e.g. `emails.address`). Use to trim the payload. Unknown field names are rejected with the valid list.

person_enrich

Hash an email address for privacy-preserving lookups. Returns SHA-256, SHA-1, and MD5 hashes of the normalized email. The hashes can be used with person_enrich's email_hash parameter.

utility_hash_email

Report a data-quality issue with a company record (by legion_id). Use this to flag bad/incorrect/outdated company data you got from company_enrich or company_search so it can be reviewed and corrected. Returns a report id and status. No credit cost; available to any signed-in user or valid API key. `issue_type` (required): 'frankenstein' (record merges multiple real companies), 'misattributed' (a value belongs to a different company), 'incorrect' (a value is wrong), 'outdated' (a value is stale), or 'duplicate'. ('not_a_real_person' is person-only.) `issue_level` (required): 'record' (whole record), 'group' (a field group), or 'field' (a single field like 'industry'). Some type/level combinations are rejected by the API. `field`: omit for 'record'; required for 'group' and 'field'. At least one of `correct_value` or `comment` is required.

report_company

Report a data-quality issue with a person record (by legion_id). Use this to flag bad/incorrect/outdated person data you got from person_enrich or person_search so it can be reviewed and corrected. Returns a report id and status. No credit cost; available to any signed-in user or valid API key. `issue_type` (required): 'frankenstein' (record merges multiple real people), 'not_a_real_person', 'misattributed' (a value belongs to a different person), 'incorrect' (a value is wrong), 'outdated' (a value is stale), or 'duplicate'. `issue_level` (required): 'record' (whole record), 'group' (a field group like 'experience'), or 'field' (a single field like 'job_title'). Some type/level combinations are rejected by the API. `field`: omit for 'record'; required for 'group' (a field-group slug) and 'field' (a response field name). At least one of `correct_value` or `comment` is required.

report_person

Search for companies using SQL WHERE syntax. Write a SELECT query against the 'companies' table. Do NOT include a LIMIT or OFFSET clause — use the limit and offset parameters instead. Example: query: "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100" limit: 3 offset: 0 # page 1; pass offset: 3 for page 2 with limit: 3 `include_fields` / `exclude_fields`: comma-separated response fields to keep or drop (supports dot paths); same names as company_enrich. Unknown field names are rejected with the valid list. Full companies are large (up to ~6k tokens each), which is why `limit` defaults to 3; to list more companies, name the fields you need in include_fields and raise `limit`.

company_search

Search for people using SQL WHERE syntax. Write a SELECT query against the 'people' table. The query must start with SELECT. Prefer the `limit`/`offset` parameters for pagination instead of a LIMIT/OFFSET clause in the SQL. Example: query: "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'california'" limit: 2 offset: 0 # page 1; pass offset: 2 for page 2 with limit: 2 Available columns include: first_name, last_name, full_name, email, phone, job_title, company_name, company_industry, city, state, state_code, country, linkedin_url, and more. Text values are lowercase: `state` is the full name ('texas'), `state_code` the ISO code ('US-TX'), `country` the full name ('united states'). A title filter alone (`job_title ILIKE '%sales%'`) scans everyone and can time out; pair it with a state, city or company filter. Cross-table columns (title, organization_name, skills, headline, summary) are automatically rewritten to subqueries. `include_fields` / `exclude_fields`: comma-separated response fields to keep or drop (supports dot paths, e.g. `emails.address`); same names as person_enrich. Unknown field names are rejected with the valid list. Full profiles are large (up to ~10k tokens each), which is why `limit` defaults to 2, like person_enrich; to list more people, name the fields you need in include_fields and raise `limit`.

person_search

Validate person or company data and get cleaning suggestions. Pass any combination of fields to validate. Returns errors, warnings, and suggestions for cleaning. Use this before enrichment to ensure data quality and improve match rates.

utility_validate