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. Returns JSON `{"results": {<field>: {"original", "cleaned", "normalized"}}}`: for each field, the value sent, the cleaned value, and whether cleaning changed it. `cleaned` is a string, except state and country (always `{full_name, code}`; an unrecognized value comes back lowercased as `full_name`), social_url (`{url, network}`), and company and school (`{name, type}`, `{domain, type}` or `{url, network, type}`). Any other value it can't clean comes back as the trimmed input. An unsupported field name or an empty value is an error. Free; no credits.

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. Returns JSON `{"matches": [{"company": {...}, "match_metadata": {...}}], "total": n}`: the best match, its `match_metadata` (`matched_on`, `match_type`, `match_confidence`: high, moderate or low), and `total`, the number of matches found. Each match consumes one credit; no match is an error (HTTP 404) and costs nothing. Key company fields: `legion_id`, `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`, `locations` (the company's offices: the primary office, `primary: true`, comes first; `current: false` marks a closed office). 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.

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 JSON `{"email", "normalized_email", "hashes": {"sha256", "sha1", "md5"}}`: the email sent, the normalized form that was hashed, and its hex digests. Any of the hashes can be used with person_enrich's email_hash parameter. Free; no credits.

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. No credit cost; available to any signed-in user or valid API key. `field`: omit for 'record'; required for 'group' and 'field'. At least one of `correct_value` or `comment` is required. Returns JSON confirming the recorded report: `report_id`, `status`, `subject_type`, `legion_id`, `issue_type`, `issue_level`, `field` and `created_at`. Each call records a new report.

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. No credit cost; available to any signed-in user or valid API key. `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. Returns JSON confirming the recorded report: `report_id`, `status`, `subject_type`, `legion_id`, `issue_type`, `issue_level`, `field` and `created_at`. Each call records a new report.

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 Filter by office location with city (lowercase), state_code ('US-TX') and country_code ('GB'); hq_city, hq_state_code and hq_country_code match only the headquarters. They take = and IN (...). Returns JSON `{"matches": [{"company": {...}}], "total": n}`: one page of company profiles (the same fields as company_enrich: name, domain, industry, size, headcount, hiring and attrition trends, socials and more) and `total`, the number of companies the WHERE clause matches across the database (an estimate for very broad queries). Each company returned consumes one credit. A `search_warning` string is added when the search flagged a filter (an industry no stored value matches, a one- or two-character pattern); tell the user and adjust the query as it says. `include_fields` / `exclude_fields` take the same names as company_enrich. 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. Use this before enrichment to ensure data quality and improve match rates. Returns JSON `{"valid", "errors", "warnings", "suggestions"}`: `valid` is false when any field has an error; each error and warning names the `field`, the `value`, the problem (`error` / `warning`) and an optional `suggestion`; each suggestion gives a `field` and its `cleaned` value. Free; no credits.

utility_validate