{ "openapi": "3.1.0", "info": { "title": "Data Legion API", "description": "API for enriching, searching, and discovering person and company data", "version": "1.0.0" }, "servers": [ { "url": "https://api.datalegion.ai" } ], "paths": { "/person/enrich": { "post": { "tags": [ "person", "enrichment" ], "summary": "Enrich person by multiple parameters", "description": "Find the best matching person(s) based on provided parameters. Requires a primary identifier (email, phone, social_url, linkedin_id, legion_id, email_hash) OR a first and last name + context (location, company, school, job_title, birth_date). Supports fuzzy matching, confidence levels (high, moderate, low), and multiple results. Inputs are automatically cleaned and normalized.", "operationId": "enrich_person_person_enrich_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentRequest" } } } }, "responses": { "200": { "description": "Success - person(s) found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonMatchesResponse" }, "example": { "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.5.0_2026-10-15", "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": "30635629dd8765da9df5e2eaf96313b4ec1ecaa918fc75586a34dada419cc150", "hash_sha1": "8536f7aa61cbb79c1ed3771e4cce7eb9fcf009d6", "hash_md5": "44087cd018be7077209cf1eccd76d0f8" } ], "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 } } } }, "400": { "description": "Bad request - invalid input or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found - no person matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (100 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable - database or service temporarily unavailable; retry after the seconds in the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/person/search": { "post": { "tags": [ "person", "search" ], "summary": "Search persons using SQL query", "description": "Execute a SQL query against the database and return person results. The query must not contain LIMIT or OFFSET clauses - use the 'limit' and 'offset' parameters for pagination. Supports titlecase formatting and field filtering.", "operationId": "search_persons_person_search_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Success - query executed and results returned", "headers": { "Total-Count-Status": { "$ref": "#/components/headers/TotalCountStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonMatchesResponse" }, "example": { "matches": [ { "person": { "legion_id": "fdd85569-f0f0-53a9-bc60-089507193c28", "full_name": "jane marie doe", "first_name": "jane", "last_name": "doe", "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", "seniority_level": "senior", "job_function": "product", "work_email": "jane.doe@techcompany.com", "linkedin_url": "https://www.linkedin.com/in/janedoe", "linkedin_id": "123456789", "years_of_experience": 12, "last_seen": "2026-01-20" } } ], "total": 8492 } } } }, "400": { "description": "Bad request - invalid query or contains LIMIT clause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout - the query exceeded the execution time limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (10 requests per minute by default)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable - database or service temporarily unavailable; retry after the seconds in the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/utility/clean": { "post": { "tags": [ "utility" ], "summary": "Clean and normalize fields", "description": "Clean and normalize one or more fields to match API format. Supports person fields (email, phone, full_name, first_name, last_name, state, country, social_url, school) and company fields (company, domain, linkedin_company_url, ticker_symbol). Rate limited to 100 requests per minute.", "operationId": "clean_fields_utility_clean_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldCleanRequest" } } }, "required": true }, "responses": { "200": { "description": "Success - fields cleaned and normalized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldCleanResponse" }, "example": { "results": { "email": { "original": "John.Doe+tag@gmail.com", "cleaned": "johndoe@gmail.com", "normalized": true }, "phone": { "original": "(650) 253-0000", "cleaned": "+16502530000", "normalized": true }, "domain": { "original": "https://www.Google.com/about", "cleaned": "google.com", "normalized": true }, "company": { "original": "Google LLC", "cleaned": { "name": "google", "type": "name" }, "normalized": true } } } } } }, "400": { "description": "Bad request - invalid field or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (100 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/utility/hash/email": { "post": { "tags": [ "utility" ], "summary": "Hash email address for privacy", "description": "Hash an email address using SHA-256, SHA-1, and MD5. Returns all hashes. Rate limited to 100 emails per minute.", "operationId": "hash_email_endpoint_utility_hash_email_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailHashRequest" } } }, "required": true }, "responses": { "200": { "description": "Success - email hashed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailHashResponse" }, "example": { "email": "Jane.Doe+tag@gmail.com", "normalized_email": "janedoe@gmail.com", "hashes": { "sha256": "d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69", "sha1": "3e12c6d13e5c00d46fee94de65239ce9c5e7bc25", "md5": "a9601f3839e5d5da764c1861a5e1daf6" } } } } }, "400": { "description": "Bad request - invalid email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (100 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/utility/validate": { "post": { "tags": [ "utility" ], "summary": "Validate person or company data", "description": "Validate person or company data format and provide suggestions before sending to search/enrich endpoints. Supports person fields (email, phone, name, birth_date, address, state, country, social_url, school) and company fields (company, domain, ticker_symbol, linkedin_company_url). Rate limited to 100 validations per minute.", "operationId": "validate_person_data_utility_validate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationRequest" } } }, "required": true }, "responses": { "200": { "description": "Success - validation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "example": { "valid": true, "errors": [], "warnings": [ { "field": "email", "value": "John.Doe@gmial.com", "warning": "Email contains formatting that will be normalized", "suggestion": "Consider using normalized form: john.doe@gmial.com" }, { "field": "email", "value": "John.Doe@gmial.com", "warning": "gmial.com looks like a typo of gmail.com", "suggestion": "Did you mean john.doe@gmail.com?" }, { "field": "phone", "value": "(650) 253-0000", "warning": "Phone number will be normalized to E.164 format", "suggestion": "Consider using normalized form: +16502530000" } ], "suggestions": [ { "field": "email", "cleaned": "john.doe@gmial.com" }, { "field": "phone", "cleaned": "+16502530000" }, { "field": "first_name", "cleaned": "john" }, { "field": "last_name", "cleaned": "doe" }, { "field": "company", "cleaned": "google" } ], "email_check": { "domain": "gmial.com", "mail": "implicit", "mail_servers": [], "disposable": false, "free": false, "relay": false, "intended_domain": "gmail.com" } } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (100 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/person/discover": { "post": { "tags": [ "person", "discover" ], "summary": "Discover persons using natural language", "description": "Describe who you're looking for in plain English. AI translates your description into precise database queries. The generated SQL is returned in the response body as `generated_query`.", "operationId": "discover_persons_person_discover_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverRequest" } } } }, "responses": { "200": { "description": "Success - persons found matching natural language query.", "headers": { "Total-Count-Status": { "$ref": "#/components/headers/TotalCountStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonDiscoverResponse" }, "example": { "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": 1247, "generated_query": "SELECT * FROM people WHERE job_title ILIKE '%vp%engineer%' AND state_code = 'US-NY'" } } } }, "400": { "description": "Bad request - invalid or unclear query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout - the query exceeded the execution time limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (10 requests per minute by default)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Natural language search is not configured on this server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Query generation service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/company/enrich": { "post": { "tags": [ "company", "enrichment" ], "summary": "Enrich company by multiple parameters", "description": "Find the best matching company/companies based on provided parameters. Supports 6 matching methods: domain, company name (fuzzy with optional industry), LinkedIn ID, social URL, ticker symbol, and Legion ID. Inputs are automatically cleaned and normalized.", "operationId": "enrich_company_company_enrich_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEnrichmentRequest" } } } }, "responses": { "200": { "description": "Success - company/companies found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMatchesResponse" }, "example": { "matches": [ { "company": { "legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c", "name": { "cleaned": "stripe inc", "display": "Stripe", "raw": [ "Stripe, Inc.", "Stripe" ] }, "headline": { "cleaned": "financial infrastructure for the internet", "raw": [ "Financial infrastructure for the internet" ] }, "description": { "cleaned": "stripe is a financial infrastructure platform for businesses...", "raw": [ "Stripe is a financial infrastructure platform for businesses..." ] }, "domain": "stripe.com", "linkedin_url": "https://www.linkedin.com/company/stripe", "linkedin_id": "2135371", "linkedin_followers": 1250000, "linkedin_employee_count": 8000, "industry": "financial services", "type": "private", "size": "5001-10000", "founded": 2010, "legion_employee_count": 8500, "legion_average_tenure": 28.4, "legion_new_hire_count": { "1m": 85, "3m": 240, "6m": 420, "12m": 780 }, "legion_attrition_count": { "1m": 35, "3m": 95, "6m": 170, "12m": 310 }, "legion_employee_growth_rate": { "1m": 0.012, "3m": 0.035, "6m": 0.068, "12m": 0.125 }, "legion_turnover_rate": { "1m": 0.004, "3m": 0.011, "6m": 0.02, "12m": 0.036 }, "legion_seniority_distribution": { "c_level": 15, "vp": 85, "director": 320, "manager": 1100, "senior": 2800, "junior": 3200 }, "legion_job_function_distribution": { "engineering": 3400, "sales": 1200, "operations": 800, "marketing": 600, "information_technology": 500, "product": 450 }, "legion_expense_category_distribution": { "research_and_development": 3850, "general_and_administrative": 2850, "sales_and_marketing": 1800 }, "legion_tenure_distribution": { "<1yr": 1200, "1-2yr": 2100, "2-5yr": 3200, "5-10yr": 1400, "10+yr": 600 }, "legion_education_distribution": { "bachelors": 4200, "masters": 2800, "high_school": 950, "associates": 400, "doctorate": 150 }, "legion_seniority_growth_rate": { "senior": { "1m": 0.015, "3m": 0.04, "6m": 0.08, "12m": 0.15 } }, "legion_job_function_growth_rate": { "engineering": { "1m": 0.018, "3m": 0.05, "6m": 0.09, "12m": 0.17 } }, "legion_expense_category_growth_rate": { "research_and_development": { "1m": 0.016, "3m": 0.045, "6m": 0.085, "12m": 0.16 } }, "tickers": [], "socials": [ { "network": "x", "url": "https://www.x.com/stripe", "username": "stripe", "id": "16177321" }, { "network": "github", "url": "https://github.com/stripe", "username": "stripe", "id": null } ], "domains": [ { "domain": "stripe.com" }, { "domain": "stripe.dev" } ], "locations": [ { "street_address": "354 oyster point blvd", "address_line_2": null, "city": "south san francisco", "state": "california", "state_code": "US-CA", "country": "united states", "country_code": "US", "continent": "north america", "continent_code": "NA", "postal_code": "94080", "geo": "37.66,-122.39", "raw": [ "354 Oyster Point Blvd, South San Francisco, CA 94080" ], "current": true, "primary": true, "num_sources": 2, "last_seen": "2026-08-01" } ], "legion_employee_count_by_month": [ { "month": "2026-01", "count": 8500, "net_change": 50, "growth_rate": 0.006, "hires": 120, "departures": 70 }, { "month": "2025-12", "count": 8450, "net_change": 65, "growth_rate": 0.008, "hires": 135, "departures": 70 } ], "num_sources": 5, "last_seen": "2026-01", "build_version": "1.5.0_2026-10-15" }, "match_metadata": { "matched_on": [ "domain" ], "match_type": "exact", "match_confidence": "high" } } ], "total": 1 } } } }, "400": { "description": "Bad request - invalid input or missing required fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found - no company matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (100 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable - database or service temporarily unavailable; retry after the seconds in the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/company/search": { "post": { "tags": [ "company", "search" ], "summary": "Search companies using SQL query", "description": "Execute a SQL query against the company database. The query must not contain LIMIT or OFFSET clauses - use the 'limit' and 'offset' parameters for pagination.", "operationId": "search_companies_company_search_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" } } } }, "responses": { "200": { "description": "Success - query executed and results returned", "headers": { "Total-Count-Status": { "$ref": "#/components/headers/TotalCountStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyMatchesResponse" }, "example": { "matches": [ { "company": { "legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c", "name": { "cleaned": "stripe inc", "display": "Stripe", "raw": [ "Stripe, Inc." ] }, "domain": "stripe.com", "industry": "financial services", "type": "private", "size": "5001-10000", "founded": 2010, "linkedin_url": "https://www.linkedin.com/company/stripe", "linkedin_id": "2135371", "legion_employee_count": 8500, "legion_average_tenure": 28.4, "legion_employee_growth_rate": { "1m": 0.012, "3m": 0.035, "6m": 0.068, "12m": 0.125 }, "last_seen": "2026-01", "num_sources": 5 } } ], "total": 3417 } } } }, "400": { "description": "Bad request - invalid query or contains LIMIT clause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout - the query exceeded the execution time limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (10 requests per minute by default)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Service unavailable - database or service temporarily unavailable; retry after the seconds in the Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/company/discover": { "post": { "tags": [ "company", "discover" ], "summary": "Discover companies using natural language", "description": "Describe the companies you're looking for in plain English. AI translates your description into precise database queries. The generated SQL is returned in the response body as `generated_query`.", "operationId": "discover_companies_company_discover_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDiscoverRequest" } } } }, "responses": { "200": { "description": "Success - companies found matching natural language query.", "headers": { "Total-Count-Status": { "$ref": "#/components/headers/TotalCountStatus" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDiscoverResponse" }, "example": { "matches": [ { "company": { "legion_id": "e9f2a4b6-8c3d-4e7f-a1b2-5d6e8f9a0c3b", "name": { "cleaned": "openai inc", "display": "OpenAI", "raw": [ "OpenAI, Inc." ] }, "domain": "openai.com", "industry": "technology, information and internet", "type": "private", "size": "1001-5000", "founded": 2015, "linkedin_url": "https://www.linkedin.com/company/openai", "linkedin_id": "17876832", "legion_employee_count": 3200, "legion_average_tenure": 18.6, "legion_employee_growth_rate": { "1m": 0.028, "3m": 0.085, "6m": 0.18, "12m": 0.42 }, "last_seen": "2026-01", "num_sources": 4 } } ], "total": 562, "generated_query": "SELECT * FROM companies WHERE industry ILIKE '%ai%' AND type = 'private' AND founded >= 2010" } } } }, "400": { "description": "Bad request - invalid or unclear query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Payment required - insufficient credits or expired contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - the API key or the team's contract does not cover this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "408": { "description": "Request timeout - the query exceeded the execution time limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error - invalid field format or value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (10 requests per minute by default)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Natural language search is not configured on this server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Query generation service temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/utility/report/person": { "post": { "tags": [ "report" ], "summary": "Report a data-quality issue with a person record", "description": "Report an issue with a person record identified by legion_id. No credit cost; available to any valid API key. Rate limited to 50 requests per minute.", "operationId": "report_person_utility_report_person_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataIssueReportRequest" } } }, "required": true }, "responses": { "201": { "description": "Report recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataIssueReportResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key is not attributed to a team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (50 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/utility/report/company": { "post": { "tags": [ "report" ], "summary": "Report a data-quality issue with a company record", "description": "Report an issue with a company record identified by legion_id. No credit cost; available to any valid API key. Rate limited to 50 requests per minute.", "operationId": "report_company_utility_report_company_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataIssueReportRequest" } } }, "required": true }, "responses": { "201": { "description": "Report recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataIssueReportResponse" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "API key is not attributed to a team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - rate limit exceeded (50 requests per minute)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "headers": { "TotalCountStatus": { "description": "`exact` when the response `total` is the full row count matching the WHERE clause across the database. `estimate` when the exact count exceeded its time budget (broad, low-selectivity queries) and `total` is the query planner's row estimate (a rough magnitude, not a precise figure). `page` when neither was available and `total` is just the size of the returned page.", "schema": { "type": "string", "enum": [ "exact", "estimate", "page" ] } } }, "schemas": { "CleanedRawResponse": { "properties": { "cleaned": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cleaned" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] } }, "type": "object", "title": "CleanedRawResponse", "description": "Generic {cleaned, raw[]} structure used for titles, degrees, headlines, summaries, skills, languages, and certification names/institutions." }, "CertificationResponse": { "properties": { "name": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "institution": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "credential_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Credential Id" }, "issue_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Issue Date" }, "expiration_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expiration Date" } }, "type": "object", "title": "CertificationResponse", "description": "Certification entry response." }, "EducationOrganizationResponse": { "properties": { "name": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url" } }, "type": "object", "title": "EducationOrganizationResponse", "description": "Organization within an education entry." }, "EducationResponse": { "properties": { "organization": { "anyOf": [ { "$ref": "#/components/schemas/EducationOrganizationResponse" }, { "type": "null" } ] }, "degree": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "degree_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Degree Level" }, "field_of_study": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" } }, "type": "object", "title": "EducationResponse", "description": "Education entry response." }, "EmailDomainCheck": { "properties": { "domain": { "type": "string", "title": "Domain", "description": "The domain checked, in ASCII (punycode) form" }, "mail": { "type": "string", "enum": [ "mx", "implicit", "null_mx", "none", "unknown" ], "title": "Mail", "description": "Whether the domain takes mail: `mx` (it publishes mail servers), `implicit` (no mail servers but an address record, which senders fall back to), `null_mx` (it publishes a record saying it takes no mail), `none` (the domain does not exist or has no record mail can use) or `unknown` (DNS timed out or failed, so the answer is not known)" }, "mail_servers": { "items": { "type": "string" }, "type": "array", "title": "Mail Servers", "description": "Mail servers, best first (empty unless `mail` is `mx`)" }, "disposable": { "type": "boolean", "title": "Disposable", "description": "Throwaway inbox service (such as mailinator.com)" }, "free": { "type": "boolean", "title": "Free", "description": "Free personal mailbox provider (such as gmail.com)" }, "relay": { "type": "boolean", "title": "Relay", "description": "Alias or relay service that forwards to a hidden inbox (such as Firefox Relay)" }, "intended_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Intended Domain", "description": "The webmail domain this one looks like a typo of (gmial.com: gmail.com)" } }, "type": "object", "required": [ "domain", "mail", "disposable", "free", "relay" ], "title": "EmailDomainCheck", "description": "What the email's domain says about the address (the mailbox itself is not checked)." }, "EmailHashRequest": { "properties": { "email": { "type": "string", "title": "Email", "description": "Email address to hash" } }, "type": "object", "required": [ "email" ], "title": "EmailHashRequest", "description": "Request model for email hashing.", "example": { "email": "Jane.Doe+tag@gmail.com" } }, "EmailHashResponse": { "properties": { "email": { "type": "string", "title": "Email", "description": "Original email address" }, "normalized_email": { "type": "string", "title": "Normalized Email", "description": "Normalized email address (used for hashing)" }, "hashes": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Hashes", "description": "Hash values keyed by algorithm (sha256, sha1, md5)" } }, "type": "object", "required": [ "email", "normalized_email", "hashes" ], "title": "EmailHashResponse", "description": "Response model for email hashing." }, "EmailResponse": { "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" }, "validated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Validated" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "validation_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Validation Status" }, "hash_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash Sha256" }, "hash_sha1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash Sha1" }, "hash_md5": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hash Md5" } }, "type": "object", "title": "EmailResponse", "description": "Email response." }, "EnrichmentRequest": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email", "description": "Email address (will be normalized)" }, "email_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email Hash", "description": "SHA-256 (64 chars), SHA-1 (40 chars), or MD5 (32 chars) hash of normalized email address (for privacy)" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone", "description": "Phone number (will be normalized to E.164)" }, "linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Id", "description": "LinkedIn numeric ID" }, "social_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Social Url", "description": "Social profile URL (LinkedIn, Twitter/X, GitHub, Facebook - will be normalized and detected)" }, "legion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legion Id", "description": "Legion ID (exact match)" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name", "description": "Full name (will be normalized)" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name", "description": "First name (will be normalized)" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name", "description": "Last name (will be normalized)" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address", "description": "Full address string (will be parsed to extract city, state, postal_code, and country)" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City", "description": "City name" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State", "description": "State name or code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country", "description": "Country name or code" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code", "description": "Postal/ZIP code" }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Title", "description": "Job title" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company", "description": "Company name, website, or social URL" }, "school": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "School", "description": "School name, website, or social URL" }, "birth_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Birth Date", "description": "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": { "type": "boolean", "title": "Multiple Results", "description": "If true, return multiple matches sorted by confidence. Enterprise only: enabled per account (ask your account manager or support@datalegion.ai); without it the request answers 403 feature_not_available. Each match returned is billed.", "default": false }, "limit": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Limit", "description": "Maximum number of results to return when multiple_results=true (default: 2, max: 10)", "default": 2 }, "min_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min Confidence", "description": "Minimum match confidence level to include in results: 'high', 'moderate', or 'low'. Matches below this threshold will be filtered out." }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "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.", "default": false }, "required_fields": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Required Fields", "description": "Fields a match must have, else it is filtered out (and not billed). Top-level fields ('work_email'), a non-empty subfield of a list item ('emails.type'), or a subfield equal to a value ('emails.type:personal', 'phones.type:mobile', 'socials.network:linkedin'). Combine them with AND, OR and parentheses: '(work_email OR mobile_phone) AND job_title'. Put a value holding the word \"and\" or \"or\", a comma or a parenthesis in double quotes: 'company_industry:\"oil and energy\"'." }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "title": "EnrichmentRequest", "description": "Request model for person enrichment. Requires a primary identifier (email, phone, social_url, linkedin_id, legion_id, email_hash) OR a first and last name + context (location, company, school, job_title, birth_date).", "example": { "city": "San Francisco", "company": "Acme Corp", "first_name": "John", "last_name": "Doe", "state": "CA" } }, "ErrorResponse": { "properties": { "error": { "type": "string", "title": "Error", "description": "Error type/code" }, "message": { "type": "string", "title": "Message", "description": "Human-readable error message" }, "details": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "items": {}, "type": "array" }, { "type": "null" } ], "title": "Details", "description": "Additional error details (for validation errors)" } }, "type": "object", "required": [ "error", "message" ], "title": "ErrorResponse", "description": "Error response model for customer-facing API." }, "ExperienceOrganizationResponse": { "properties": { "name": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Website" }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url" }, "linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Id" }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry" }, "size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Size" }, "legion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legion Id" } }, "type": "object", "title": "ExperienceOrganizationResponse", "description": "Organization within an experience entry." }, "ExperienceResponse": { "properties": { "title": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "seniority_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seniority Level" }, "job_function": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Function" }, "expense_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expense Category" }, "is_decision_maker": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Decision Maker" }, "is_platform_worker": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Platform Worker" }, "organization": { "anyOf": [ { "$ref": "#/components/schemas/ExperienceOrganizationResponse" }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start Date" }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End Date" }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" }, "tenure_months": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Tenure Months" }, "description": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] } }, "type": "object", "title": "ExperienceResponse", "description": "Experience entry response." }, "FieldCleanRequest": { "properties": { "fields": { "additionalProperties": { "type": "string" }, "type": "object", "minProperties": 1, "title": "Fields", "description": "Map of field names to values to clean (e.g., {'email': 'John.Doe+tag@gmail.com', 'domain': 'https://www.Google.com/about'}). 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." }, "default_region": { "type": "string", "title": "Default Region", "description": "Default region for phone number normalization (ISO 3166-1 alpha-2 code)", "default": "US" } }, "type": "object", "required": [ "fields" ], "title": "FieldCleanRequest", "description": "Request model for batch field cleaning.", "example": { "fields": { "email": "John.Doe+tag@gmail.com", "phone": "(650) 253-0000", "domain": "https://www.Google.com/about", "company": "Google LLC" } } }, "FieldCleanResponse": { "properties": { "results": { "additionalProperties": { "$ref": "#/components/schemas/FieldCleanResult" }, "type": "object", "title": "Results", "description": "Map of field names to cleaning results" } }, "type": "object", "required": [ "results" ], "title": "FieldCleanResponse", "description": "Response model for batch field cleaning." }, "FieldCleanResult": { "properties": { "original": { "type": "string", "title": "Original", "description": "Original input value" }, "cleaned": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Cleaned", "description": "Cleaned/normalized value" }, "normalized": { "type": "boolean", "title": "Normalized", "description": "Whether normalization was applied" } }, "type": "object", "required": [ "original", "cleaned", "normalized" ], "title": "FieldCleanResult", "description": "Result for a single cleaned field." }, "LanguageResponse": { "properties": { "cleaned": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cleaned" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] }, "proficiency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Proficiency" } }, "type": "object", "title": "LanguageResponse", "description": "Language response." }, "LocationResponse": { "properties": { "street_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street Address" }, "address_line_2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line 2" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code" }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continent" }, "continent_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continent Code" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code" }, "postal_code_4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code 4" }, "geo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Geo" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "title": "LocationResponse", "description": "Location response." }, "MatchMetadata": { "properties": { "matched_on": { "items": { "type": "string" }, "type": "array", "title": "Matched On", "description": "Fields that matched between request and person" }, "match_type": { "type": "string", "title": "Match Type", "description": "Type of match: exact, fuzzy, or partial" }, "match_confidence": { "type": "string", "title": "Match Confidence", "description": "Match confidence level: high, moderate, or low" } }, "type": "object", "required": [ "match_type", "match_confidence" ], "title": "MatchMetadata", "description": "Metadata about the match." }, "PersonMatchResponse": { "properties": { "person": { "$ref": "#/components/schemas/PersonResponse" }, "match_metadata": { "anyOf": [ { "$ref": "#/components/schemas/MatchMetadata" }, { "type": "null" } ] } }, "type": "object", "required": [ "person" ], "title": "PersonMatchResponse", "description": "Person response with optional match metadata." }, "PersonMatchesResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/PersonMatchResponse" }, "type": "array", "title": "Matches", "description": "List of matches sorted by confidence (descending). Capped at the request's `limit`." }, "total": { "type": "integer", "title": "Total", "description": "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`)." } }, "type": "object", "required": [ "matches", "total" ], "title": "PersonMatchesResponse", "description": "Multiple person matches response." }, "PersonDiscoverResponse": { "allOf": [ { "$ref": "#/components/schemas/PersonMatchesResponse" }, { "type": "object", "required": [ "generated_query" ], "properties": { "generated_query": { "type": "string", "title": "Generated Query", "description": "SQL query generated from the natural language input" } } } ], "title": "PersonDiscoverResponse", "description": "Person discover response with generated query." }, "PersonResponse": { "properties": { "legion_id": { "type": "string", "title": "Legion Id" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "middle_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Middle Name" }, "middle_initial": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Middle Initial" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "last_initial": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Initial" }, "suffix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suffix" }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prefix" }, "sex": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sex" }, "birth_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Birth Date" }, "birth_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Birth Year" }, "birth_month": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Birth Month" }, "birth_day": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Birth Day" }, "age": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Age" }, "work_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Email" }, "mobile_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mobile Phone" }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url" }, "linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Id" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code" }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Title" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Name" }, "company_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Domain" }, "company_industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Industry" }, "company_size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Size" }, "company_legion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Legion Id" }, "company_linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Linkedin Url" }, "company_linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company Linkedin Id" }, "seniority_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Seniority Level" }, "job_function": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Job Function" }, "expense_category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expense Category" }, "is_decision_maker": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Decision Maker" }, "is_platform_worker": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Is Platform Worker" }, "years_of_experience": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Years Of Experience" }, "avg_tenure_months": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Avg Tenure Months" }, "highest_degree_level": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Highest Degree Level" }, "current_jobs_last_confirmed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Jobs Last Confirmed" }, "current_jobs_last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Jobs Last Updated" }, "current_location_last_confirmed": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Location Last Confirmed" }, "current_location_last_updated": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Current Location Last Updated" }, "linkedin_followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Followers" }, "linkedin_connections": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Connections" }, "headline": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "build_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Build Version" }, "phones": { "items": { "$ref": "#/components/schemas/PhoneResponse" }, "type": "array", "title": "Phones", "default": [] }, "emails": { "items": { "$ref": "#/components/schemas/EmailResponse" }, "type": "array", "title": "Emails", "default": [] }, "locations": { "items": { "$ref": "#/components/schemas/LocationResponse" }, "type": "array", "title": "Locations", "default": [] }, "experience": { "items": { "$ref": "#/components/schemas/ExperienceResponse" }, "type": "array", "title": "Experience", "default": [] }, "education": { "items": { "$ref": "#/components/schemas/EducationResponse" }, "type": "array", "title": "Education", "default": [] }, "certifications": { "items": { "$ref": "#/components/schemas/CertificationResponse" }, "type": "array", "title": "Certifications", "default": [] }, "socials": { "items": { "$ref": "#/components/schemas/SocialResponse" }, "type": "array", "title": "Socials", "default": [] }, "skills": { "items": { "$ref": "#/components/schemas/SkillResponse" }, "type": "array", "title": "Skills", "default": [] }, "languages": { "items": { "$ref": "#/components/schemas/LanguageResponse" }, "type": "array", "title": "Languages", "default": [] } }, "type": "object", "required": [ "legion_id" ], "title": "PersonResponse", "description": "Complete person enrichment response." }, "PhoneResponse": { "properties": { "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "number": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Number" }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" } }, "type": "object", "title": "PhoneResponse", "description": "Phone number response." }, "SearchRequest": { "properties": { "query": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Query", "description": "SQL query to execute (must not contain LIMIT clause). Must be a SELECT query only." }, "limit": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Limit", "description": "Maximum number of results to return, in place of a LIMIT in the query (default 1, max 100).", "default": 1 }, "offset": { "type": "integer", "maximum": 10000, "minimum": 0, "title": "Offset", "description": "Number of results to skip for pagination (0-10000). Stable within a build; ordering may change across builds.", "default": 0 }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "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.", "default": false }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "required": [ "query" ], "title": "SearchRequest", "description": "Request model for SQL query-based person search.", "example": { "query": "SELECT * FROM people WHERE city = 'San Francisco' ORDER BY last_seen DESC", "limit": 10, "titlecase": false } }, "SkillResponse": { "properties": { "cleaned": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cleaned" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] } }, "type": "object", "title": "SkillResponse", "description": "Skill response." }, "SocialResponse": { "properties": { "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current" }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confidence" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "title": "SocialResponse", "description": "Social response." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ValidationIssue": { "properties": { "field": { "type": "string", "title": "Field", "description": "Field name with error" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Invalid value" }, "error": { "type": "string", "title": "Error", "description": "Error message" }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suggestion", "description": "Suggestion for fixing the error" } }, "type": "object", "required": [ "field", "error" ], "title": "ValidationIssue", "description": "Validation error detail." }, "ValidationRequest": { "properties": { "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Email" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Phone" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "full_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "social_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Social Url" }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Company" }, "school": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "School" }, "birth_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Birth Date" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "ticker_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker Symbol" }, "linkedin_company_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "LinkedIn Company URL" } }, "type": "object", "title": "ValidationRequest", "description": "Request model for data validation.", "example": { "email": "John.Doe@gmial.com", "phone": "(650) 253-0000", "first_name": "John", "last_name": "Doe", "company": "Google LLC", "domain": "google.com" } }, "ValidationResponse": { "properties": { "valid": { "type": "boolean", "title": "Valid", "description": "Whether all data is valid" }, "errors": { "items": { "$ref": "#/components/schemas/ValidationIssue" }, "type": "array", "title": "Errors", "description": "List of validation errors" }, "warnings": { "items": { "$ref": "#/components/schemas/ValidationWarning" }, "type": "array", "title": "Warnings", "description": "List of validation warnings" }, "suggestions": { "items": { "$ref": "#/components/schemas/ValidationSuggestion" }, "type": "array", "title": "Suggestions", "description": "List of cleaning suggestions" }, "email_check": { "anyOf": [ { "$ref": "#/components/schemas/EmailDomainCheck" }, { "type": "null" } ], "description": "What the email's domain says about the address, when an email was sent and is well-formed. The mailbox itself is not checked." } }, "type": "object", "required": [ "valid" ], "title": "ValidationResponse", "description": "Response model for data validation." }, "ValidationSuggestion": { "properties": { "field": { "type": "string", "title": "Field", "description": "Field name" }, "cleaned": { "anyOf": [ { "type": "string" }, { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Cleaned", "description": "Suggested cleaned value" } }, "type": "object", "required": [ "field", "cleaned" ], "title": "ValidationSuggestion", "description": "Validation suggestion detail." }, "ValidationWarning": { "properties": { "field": { "type": "string", "title": "Field", "description": "Field name with warning" }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Value", "description": "Value that triggered warning" }, "warning": { "type": "string", "title": "Warning", "description": "Warning message" }, "suggestion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Suggestion", "description": "Suggestion for improvement" } }, "type": "object", "required": [ "field", "warning" ], "title": "ValidationWarning", "description": "Validation warning detail." }, "DiscoverRequest": { "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 1000, "title": "Query", "description": "Natural language description of who you're looking for" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "title": "Limit", "description": "Maximum number of results to return (default 1, max 100).", "default": 1 }, "offset": { "type": "integer", "maximum": 10000, "minimum": 0, "title": "Offset", "description": "Number of results to skip for pagination (0-10000). Stable within a build; ordering may change across builds.", "default": 0 }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "If true, format text fields in title case (names, company names, locations). Raw fields, IDs, URLs, codes, and confidence fields are excluded.", "default": false }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "required": [ "query" ], "title": "DiscoverRequest", "description": "Request model for natural language person discovery.", "example": { "query": "VP of Engineering at fintech companies in New York", "limit": 10 } }, "CompanyEnrichmentRequest": { "properties": { "legion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legion Id", "description": "Company Legion ID (exact match)" }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Company website domain (e.g., google.com)" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Company name (fuzzy matching)" }, "linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Id", "description": "LinkedIn company numeric ID" }, "social_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Social Url", "description": "Social profile URL (LinkedIn, Facebook, Crunchbase, X/Twitter, GitHub - will be normalized and detected)" }, "ticker_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ticker Symbol", "description": "Stock ticker symbol (e.g., GOOGL)" }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry", "description": "Industry filter (used with name matching for better accuracy)" }, "multiple_results": { "type": "boolean", "title": "Multiple Results", "description": "If true, return multiple matches sorted by confidence. Enterprise only: enabled per account (ask your account manager or support@datalegion.ai); without it the request answers 403 feature_not_available. Each match returned is billed.", "default": false }, "limit": { "type": "integer", "maximum": 10, "minimum": 1, "title": "Limit", "description": "Maximum results when multiple_results=true (default: 2, max: 10)", "default": 2 }, "min_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min Confidence", "description": "Minimum match confidence: 'high', 'moderate', or 'low'" }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "If true, format text fields in title case (names, company names, locations). Raw fields, IDs, URLs, codes, and confidence fields are excluded.", "default": false }, "required_fields": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Required Fields", "description": "Fields a match must have, else it is filtered out (and not billed). Supports top-level fields ('domain'), a non-empty list subfield ('socials.network'), or a subfield equal to a value ('type:public', 'socials.network:linkedin'). Combine them with AND, OR and parentheses: '(domain OR socials) AND industry'. Put a value holding the word \"and\" or \"or\", a comma or a parenthesis in double quotes: 'industry:\"oil and energy\"'." }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "title": "CompanyEnrichmentRequest", "description": "Request model for company enrichment.", "example": { "domain": "stripe.com" } }, "CompanySearchRequest": { "properties": { "query": { "type": "string", "maxLength": 10000, "minLength": 1, "title": "Query", "description": "SQL query against company data (must not contain LIMIT)" }, "limit": { "type": "integer", "maximum": 100, "minimum": 1, "title": "Limit", "description": "Maximum results to return (default 1, max 100).", "default": 1 }, "offset": { "type": "integer", "maximum": 10000, "minimum": 0, "title": "Offset", "description": "Number of results to skip for pagination (0-10000). Stable within a build; ordering may change across builds.", "default": 0 }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "If true, format text fields in title case (names, company names, locations). Raw fields, IDs, URLs, codes, and confidence fields are excluded.", "default": false }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "required": [ "query" ], "title": "CompanySearchRequest", "description": "Request model for SQL query-based company search.", "example": { "query": "SELECT * FROM companies WHERE industry ILIKE '%software%' AND size='1001-5000'", "limit": 10 } }, "CompanyDiscoverRequest": { "properties": { "query": { "type": "string", "minLength": 3, "maxLength": 1000, "title": "Query", "description": "Natural language description of companies you're looking for" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "title": "Limit", "default": 1, "description": "Maximum number of results to return (default 1, max 100)." }, "offset": { "type": "integer", "maximum": 10000, "minimum": 0, "title": "Offset", "description": "Number of results to skip for pagination (0-10000). Stable within a build; ordering may change across builds.", "default": 0 }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "If true, format text fields in title case (names, company names, locations). Raw fields, IDs, URLs, codes, and confidence fields are excluded.", "default": false }, "include_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Include Fields", "description": "Comma-separated list of fields to include in response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Comma-separated list of fields to exclude from response. Applied after include_fields filter." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print JSON response with indentation.", "default": false } }, "type": "object", "required": [ "query" ], "title": "CompanyDiscoverRequest", "description": "Request model for natural language company discovery.", "example": { "query": "AI companies with 100+ employees founded after 2015", "limit": 10 } }, "TimeBucketIntResponse": { "properties": { "1m": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "1m", "description": "Value over the last month" }, "3m": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "3m", "description": "Value over the last 3 months" }, "6m": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "6m", "description": "Value over the last 6 months" }, "12m": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "12m", "description": "Value over the last 12 months" } }, "type": "object", "title": "TimeBucketIntResponse", "description": "Time-bucketed integer values (1m, 3m, 6m, 12m)." }, "TimeBucketFloatResponse": { "properties": { "1m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "1m", "description": "Rate over the last month" }, "3m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "3m", "description": "Rate over the last 3 months" }, "6m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "6m", "description": "Rate over the last 6 months" }, "12m": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "12m", "description": "Rate over the last 12 months" } }, "type": "object", "title": "TimeBucketFloatResponse", "description": "Time-bucketed float values (1m, 3m, 6m, 12m)." }, "CompanyTickerResponse": { "properties": { "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Symbol" }, "exchange": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exchange" } }, "type": "object", "title": "CompanyTickerResponse" }, "CompanySocialResponse": { "properties": { "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Network", "description": "Social network name (e.g., x, github, facebook)" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Url", "description": "Profile URL" }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Username", "description": "Username or handle" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id", "description": "Account ID" } }, "type": "object", "title": "CompanySocialResponse", "description": "Company social media profile." }, "CompanyDomainResponse": { "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain", "description": "Associated company domain" } }, "type": "object", "title": "CompanyDomainResponse", "description": "Company alternative domain." }, "CompanyLocationResponse": { "properties": { "street_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Street Address" }, "address_line_2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line 2" }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "City" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State" }, "state_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "State Code" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Code" }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continent" }, "continent_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Continent Code" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code" }, "geo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Geo" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] }, "current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Current", "description": "The office is still operating." }, "primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Primary", "description": "The company's primary location. At most one entry per company." }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "last_seen": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Seen" } }, "type": "object", "title": "CompanyLocationResponse", "description": "Company location response. Entries run primary first, then current, then closed." }, "EmployeeCountByMonthResponse": { "properties": { "month": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Month", "description": "YYYY-MM format" }, "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Count" }, "net_change": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Net Change" }, "growth_rate": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Growth Rate" }, "hires": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Hires" }, "departures": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Departures" } }, "type": "object", "title": "EmployeeCountByMonthResponse" }, "CompanyNameResponse": { "properties": { "cleaned": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cleaned" }, "display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Display", "description": "Best-quality name with original casing preserved (premium tier)" }, "raw": { "items": { "type": "string" }, "type": "array", "title": "Raw", "default": [] } }, "type": "object", "title": "CompanyNameResponse", "description": "Company name structure with cleaned, display, and raw[] variants." }, "CompanyResponse": { "properties": { "legion_id": { "type": "string", "title": "Legion Id" }, "name": { "anyOf": [ { "$ref": "#/components/schemas/CompanyNameResponse" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "description": { "anyOf": [ { "$ref": "#/components/schemas/CleanedRawResponse" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Domain" }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Url" }, "linkedin_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Linkedin Id" }, "linkedin_followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Followers" }, "linkedin_employee_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Linkedin Employee Count" }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Industry" }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Type" }, "size": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Size" }, "founded": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Founded" }, "legion_employee_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Legion Employee Count" }, "legion_average_tenure": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Legion Average Tenure" }, "legion_new_hire_count": { "anyOf": [ { "$ref": "#/components/schemas/TimeBucketIntResponse" }, { "type": "null" } ] }, "legion_attrition_count": { "anyOf": [ { "$ref": "#/components/schemas/TimeBucketIntResponse" }, { "type": "null" } ] }, "legion_turnover_rate": { "anyOf": [ { "$ref": "#/components/schemas/TimeBucketFloatResponse" }, { "type": "null" } ] }, "legion_employee_growth_rate": { "anyOf": [ { "$ref": "#/components/schemas/TimeBucketFloatResponse" }, { "type": "null" } ] }, "legion_seniority_distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "null" } ], "title": "Seniority Distribution", "description": "Employee count by seniority level (c_level, owner, partner, vp, director, manager, senior, junior, training, intern)" }, "legion_job_function_distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "null" } ], "title": "Job Function Distribution", "description": "Employee count by job function (engineering, sales, marketing, etc.)" }, "legion_expense_category_distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "null" } ], "title": "Expense Category Distribution", "description": "Employee count by P&L expense category (general_and_administrative, research_and_development, sales_and_marketing, cost_of_services, not_applicable)" }, "legion_tenure_distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "null" } ], "title": "Tenure Distribution", "description": "Employee count by tenure bucket (<1yr, 1-2yr, 2-5yr, 5-10yr, 10+yr)" }, "legion_education_distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer" } }, { "type": "null" } ], "title": "Education Distribution", "description": "Employee count by education level (doctorate, masters, bachelors, associates, high_school)" }, "legion_seniority_growth_rate": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeBucketFloatResponse" } }, { "type": "null" } ], "title": "Seniority Growth Rate", "description": "Growth rate per seniority level with time buckets (1m, 3m, 6m, 12m)" }, "legion_job_function_growth_rate": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeBucketFloatResponse" } }, { "type": "null" } ], "title": "Job Function Growth Rate", "description": "Growth rate per job function with time buckets (1m, 3m, 6m, 12m)" }, "legion_expense_category_growth_rate": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeBucketFloatResponse" } }, { "type": "null" } ], "title": "Expense Category Growth Rate", "description": "Growth rate per expense category with time buckets (1m, 3m, 6m, 12m)" }, "tickers": { "items": { "$ref": "#/components/schemas/CompanyTickerResponse" }, "type": "array", "title": "Tickers", "default": [] }, "socials": { "items": { "$ref": "#/components/schemas/CompanySocialResponse" }, "type": "array", "title": "Socials", "default": [] }, "domains": { "items": { "$ref": "#/components/schemas/CompanyDomainResponse" }, "type": "array", "title": "Domains", "default": [] }, "locations": { "items": { "$ref": "#/components/schemas/CompanyLocationResponse" }, "type": "array", "title": "Locations", "default": [] }, "legion_employee_count_by_month": { "items": { "$ref": "#/components/schemas/EmployeeCountByMonthResponse" }, "type": "array", "title": "Legion Employee Count By Month", "default": [] }, "num_sources": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Num Sources" }, "last_seen": { "anyOf": [ { "type": "string", "description": "YYYY-MM format" }, { "type": "null" } ], "title": "Last Seen" }, "build_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Build Version" } }, "type": "object", "required": [ "legion_id" ], "title": "CompanyResponse", "description": "Complete company enrichment response." }, "CompanyMatchResponse": { "properties": { "company": { "$ref": "#/components/schemas/CompanyResponse" }, "match_metadata": { "anyOf": [ { "$ref": "#/components/schemas/MatchMetadata" }, { "type": "null" } ] } }, "type": "object", "required": [ "company" ], "title": "CompanyMatchResponse" }, "CompanyMatchesResponse": { "properties": { "matches": { "items": { "$ref": "#/components/schemas/CompanyMatchResponse" }, "type": "array", "title": "Matches", "description": "List of matches sorted by confidence (descending). Capped at the request's `limit`." }, "total": { "type": "integer", "title": "Total", "description": "For /company/search and /company/discover, the total number of rows matching the query's WHERE clause across the database (not just this page). For /company/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`)." } }, "type": "object", "required": [ "matches", "total" ], "title": "CompanyMatchesResponse" }, "CompanyDiscoverResponse": { "allOf": [ { "$ref": "#/components/schemas/CompanyMatchesResponse" }, { "type": "object", "required": [ "generated_query" ], "properties": { "generated_query": { "type": "string", "title": "Generated Query", "description": "SQL query generated from the natural language input" } } } ], "title": "CompanyDiscoverResponse", "description": "Company discover response with generated query." }, "DataIssueReportRequest": { "properties": { "legion_id": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Legion Id", "description": "The legion_id of the record being reported." }, "issue_type": { "type": "string", "enum": [ "incorrect", "outdated", "misattributed", "frankenstein", "not_a_real_person", "duplicate" ], "title": "Issue Type", "description": "What is wrong. 'frankenstein' = the record appears to merge multiple real people; 'not_a_real_person' = not a real individual (person reports only); 'misattributed' = a value belongs to a different person; 'incorrect' = a value is wrong; 'outdated' = a value is stale; 'duplicate' = a duplicated value or record." }, "issue_level": { "type": "string", "enum": [ "record", "group", "field" ], "title": "Issue Level", "description": "Scope of the issue. 'record' = the whole record; 'group' = a field group (e.g. experience); 'field' = a single field (e.g. job_title)." }, "field": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "Field", "description": "Target of the issue. Omit for 'record'. For 'group', a field-group slug (e.g. 'experience'). For 'field', a response field name (e.g. 'job_title')." }, "observed_value": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Observed Value", "description": "The value currently returned that is being disputed." }, "correct_value": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Correct Value", "description": "The value that would be correct, if known." }, "comment": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ], "title": "Comment", "description": "Free-text detail about the issue." } }, "type": "object", "required": [ "legion_id", "issue_type", "issue_level" ], "title": "DataIssueReportRequest", "description": "Request body for POST /utility/report/{person|company}.\n\nThe entity (person vs company) comes from the path, so it is not in the body." }, "DataIssueReportResponse": { "properties": { "report_id": { "type": "integer", "title": "Report Id" }, "status": { "type": "string", "title": "Status" }, "subject_type": { "type": "string", "title": "Subject Type" }, "legion_id": { "type": "string", "title": "Legion Id" }, "issue_type": { "type": "string", "title": "Issue Type" }, "issue_level": { "type": "string", "title": "Issue Level" }, "field": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Field" }, "created_at": { "type": "string", "format": "date-time", "title": "Created At" } }, "type": "object", "required": [ "report_id", "status", "subject_type", "legion_id", "issue_type", "issue_level", "created_at" ], "title": "DataIssueReportResponse", "description": "Confirmation returned after a report is recorded." } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "API-Key" } } }, "security": [ { "APIKeyHeader": [] } ] }