{ "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/bulk": { "post": { "tags": [ "person", "enrichment" ], "summary": "Bulk enrich persons", "description": "Enrich up to 50 persons in a single request. Each item is matched and billed independently, exactly like a standalone /person/enrich call. Top-level flags act as defaults; per-item flags override them. Results are returned in input order, and each item independently reports its matches or an error (a per-item failure does not fail the batch). Synchronous: all results are returned in one response (no polling). Default rate limit: 10 requests/min, each request up to 50 records.", "operationId": "bulk_enrich_person_person_enrich_bulk_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPersonEnrichRequest" } } } }, "responses": { "200": { "description": "Per-item results, in input order (each item is a match set or an error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPersonEnrichResponse" }, "example": { "results": [ { "matches": [ { "person": { "legion_id": "fdd85569-f0f0-53a9-bc60-089507193c28", "full_name": "jane marie doe", "work_email": "jane.doe@techcompany.com" }, "match_metadata": { "matched_on": [ "email" ], "match_type": "exact", "match_confidence": "high" } } ], "total": 1, "metadata": { "row": "1" } }, { "error": "No person found matching the provided parameters.", "metadata": { "row": "2" } } ] } } } }, "400": { "description": "Bad request - malformed batch (e.g. empty items or more than 50 items)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits for the maximum possible cost of the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - API key not permitted for this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds the 1 MB 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 (default 10 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" } } } } } } }, "/company/enrich/bulk": { "post": { "tags": [ "company", "enrichment" ], "summary": "Bulk enrich companies", "description": "Enrich up to 50 companies in a single request. Each item is matched and billed independently, exactly like a standalone /company/enrich call. Top-level flags act as defaults; per-item flags override them. Results are returned in input order, and each item independently reports its matches or an error (a per-item failure does not fail the batch). Synchronous: all results are returned in one response (no polling). Default rate limit: 10 requests/min, each request up to 50 records.", "operationId": "bulk_enrich_company_company_enrich_bulk_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCompanyEnrichRequest" } } } }, "responses": { "200": { "description": "Per-item results, in input order (each item is a match set or an error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCompanyEnrichResponse" }, "example": { "results": [ { "matches": [ { "company": { "legion_id": "c8a1b2c3-d4e5-6f7a-8b9c-0d1e2f3a4b5c", "company_name": "acme corp", "company_domain": "acme.com" }, "match_metadata": { "matched_on": [ "domain" ], "match_type": "exact", "match_confidence": "high" } } ], "total": 1, "metadata": { "crm_id": "abc-123" } }, { "error": "No company found matching the provided parameters.", "metadata": { "crm_id": "def-456" } } ] } } } }, "400": { "description": "Bad request - malformed batch (e.g. empty items or more than 50 items)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits for the maximum possible cost of the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - API key not permitted for this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds the 1 MB 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 (default 10 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" } } } } } } }, "/dynamic/person/enrich/bulk": { "post": { "tags": [ "person", "enrichment" ], "summary": "Dynamic bulk person enrichment (phones/emails)", "description": "Resolve up to 50 LinkedIn profile URLs and return ONLY the requested contact groups per item. A focused, high-throughput contact-enrichment surface. `fields` accepts only the `phones` and/or `emails` groups (`phones` returns phones + mobile_phone; `emails` returns emails + work_email): a concrete sub-field (mobile_phone/work_email) or any profile field is rejected with 400. Each item is resolved and billed independently to the credit pool that entitles its requested group(s); results are returned in input order, and a per-item no-match or error does not fail the batch. Synchronous: all results are returned in one response.", "operationId": "dynamic_bulk_enrich_person_dynamic_person_enrich_bulk_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicBulkEnrichRequest" } } } }, "responses": { "200": { "description": "Per-item results, in input order (only the requested phones/emails groups are populated; unmatched or errored items have a null legion_id)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DynamicBulkEnrichResponse" }, "example": { "results": [ { "metadata": { "row": "1" }, "legion_id": "fdd85569-f0f0-53a9-bc60-089507193c28", "phones": [ { "number": "+14255551234", "type": "mobile" } ], "mobile_phone": "+14255551234" }, { "metadata": { "row": "2" }, "legion_id": "a1b2c3d4-e5f6-5a7b-8c9d-0e1f2a3b4c5d", "phones": [ { "number": "+12065559999" } ], "mobile_phone": "+12065559999", "emails": [ { "address": "john.smith@example.com" } ], "work_email": "john.smith@example.com" }, { "metadata": { "row": "3" }, "legion_id": null, "error": "No contract entitles the requested fields." } ] } } } }, "400": { "description": "Bad request: malformed batch (empty or >50 items), or `fields` contains a token other than the 'phones'/'emails' groups (unsupported_fields)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Insufficient credits for the maximum possible cost of the batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - API key not permitted for this endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Payload too large - request body exceeds the 1 MB 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 (the limit is set per contract)", "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" } } } } } } } }, "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." }, "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 name + context (location, company, school, job_title, birth_date).", "example": { "city": "San Francisco", "company": "Acme Corp", "email": "john.doe@example.com", "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": "(555) 123-4567", "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 (replaces LIMIT in query)" }, "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", "limit" ], "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" }, "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@example.com", "phone": "+15551234567", "first_name": "John", "last_name": "Doe", "domain": "google.com", "company": "Google LLC" } }, "ValidationResponse": { "properties": { "valid": { "type": "boolean", "title": "Valid", "description": "Whether all data is valid" }, "errors": { "items": { "$ref": "#/components/schemas/ValidationError" }, "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" } }, "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" }, "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", "limit" ], "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" }, "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", "limit" ], "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" }, "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", "limit" ], "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" }, "BulkPersonItem": { "allOf": [ { "$ref": "#/components/schemas/EnrichmentRequest" }, { "type": "object", "properties": { "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Metadata", "description": "Optional key-value object (max 10 keys) echoed back unchanged on this item's result, for correlating results to your records. Values must be primitive (string, number, or boolean); nested objects and arrays are rejected." } } } ], "title": "BulkPersonItem", "description": "A single person enrichment request within a bulk call. Accepts every /person/enrich identifier and option, plus optional metadata. Per-item flags override the top-level defaults." }, "BulkPersonEnrichRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "title": "Items", "description": "List of enrichment requests (1-50 items).", "items": { "$ref": "#/components/schemas/BulkPersonItem" } }, "multiple_results": { "type": "boolean", "title": "Multiple Results", "description": "Default for all items: 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": "Default for all items: maximum number of results per item when multiple_results=true (default: 2, max: 10).", "default": 2 }, "min_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min Confidence", "description": "Default for all items: minimum match confidence level to include ('high', 'moderate', or 'low')." }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "Default for all items: if true, format text fields in title case.", "default": false }, "required_fields": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Required Fields", "description": "Default for all items. Fields a match must have, else it is filtered out (and not billed). Supports top-level fields ('work_email'), a non-empty list subfield ('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": "Default for all items: comma-separated list of fields to include in the response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Default for all items: comma-separated list of fields to exclude from the response. Applied after include_fields." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print the JSON response with indentation.", "default": false } }, "title": "BulkPersonEnrichRequest", "description": "Bulk person enrichment request. Top-level flags act as defaults applied to every item; per-item flags override them.", "example": { "items": [ { "email": "jane.doe@example.com", "metadata": { "row": "1" } }, { "phone": "+15551234567", "metadata": { "row": "2" } }, { "first_name": "John", "last_name": "Doe", "company": "Acme Corp", "metadata": { "row": "3" } } ] } }, "BulkPersonItemResult": { "type": "object", "properties": { "matches": { "type": "array", "title": "Matches", "description": "Matches for this item (present on success), capped at the item's limit.", "items": { "$ref": "#/components/schemas/PersonMatchResponse" } }, "total": { "type": "integer", "title": "Total", "description": "Number of matches found for this item." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message when this item could not be matched (e.g. no match or invalid input). Per-item failures are isolated; other items still succeed." }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Metadata", "description": "The metadata you supplied for this item, echoed back unchanged." } }, "title": "BulkPersonItemResult", "description": "Result for one item in a bulk person request. Each slot independently reports matches or an error, with your metadata echoed back." }, "BulkPersonEnrichResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "title": "Results", "description": "Per-item results, in the same order as the input items.", "items": { "$ref": "#/components/schemas/BulkPersonItemResult" } } }, "title": "BulkPersonEnrichResponse", "description": "Bulk person enrichment response." }, "BulkCompanyItem": { "allOf": [ { "$ref": "#/components/schemas/CompanyEnrichmentRequest" }, { "type": "object", "properties": { "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Metadata", "description": "Optional key-value object (max 10 keys) echoed back unchanged on this item's result, for correlating results to your records. Values must be primitive (string, number, or boolean); nested objects and arrays are rejected." } } } ], "title": "BulkCompanyItem", "description": "A single company enrichment request within a bulk call. Accepts every /company/enrich identifier and option, plus optional metadata. Per-item flags override the top-level defaults." }, "BulkCompanyEnrichRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "title": "Items", "description": "List of company enrichment requests (1-50 items).", "items": { "$ref": "#/components/schemas/BulkCompanyItem" } }, "multiple_results": { "type": "boolean", "title": "Multiple Results", "description": "Default for all items: 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": "Default for all items: maximum number of results per item when multiple_results=true (default: 2, max: 10).", "default": 2 }, "min_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Min Confidence", "description": "Default for all items: minimum match confidence level to include ('high', 'moderate', or 'low')." }, "titlecase": { "type": "boolean", "title": "Titlecase", "description": "Default for all items: if true, format text fields in title case.", "default": false }, "required_fields": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Required Fields", "description": "Default for all items. 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": "Default for all items: comma-separated list of fields to include in the response. If omitted, all fields are returned." }, "exclude_fields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclude Fields", "description": "Default for all items: comma-separated list of fields to exclude from the response. Applied after include_fields." }, "pretty_print": { "type": "boolean", "title": "Pretty Print", "description": "If true, pretty-print the JSON response with indentation.", "default": false } }, "title": "BulkCompanyEnrichRequest", "description": "Bulk company enrichment request. Top-level flags act as defaults applied to every item; per-item flags override them.", "example": { "items": [ { "domain": "acme.com", "metadata": { "crm_id": "abc-123" } }, { "company_name": "Globex", "metadata": { "crm_id": "def-456" } } ] } }, "BulkCompanyItemResult": { "type": "object", "properties": { "matches": { "type": "array", "title": "Matches", "description": "Matches for this item (present on success), capped at the item's limit.", "items": { "$ref": "#/components/schemas/CompanyMatchResponse" } }, "total": { "type": "integer", "title": "Total", "description": "Number of matches found for this item." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Error message when this item could not be matched (e.g. no match or invalid input). Per-item failures are isolated; other items still succeed." }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Metadata", "description": "The metadata you supplied for this item, echoed back unchanged." } }, "title": "BulkCompanyItemResult", "description": "Result for one item in a bulk company request. Each slot independently reports matches or an error, with your metadata echoed back." }, "BulkCompanyEnrichResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "title": "Results", "description": "Per-item results, in the same order as the input items.", "items": { "$ref": "#/components/schemas/BulkCompanyItemResult" } } }, "title": "BulkCompanyEnrichResponse", "description": "Bulk company enrichment response." }, "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." }, "DynamicBulkItem": { "type": "object", "required": [ "social_url", "fields" ], "properties": { "social_url": { "type": "string", "title": "Social Url", "description": "LinkedIn profile URL to resolve." }, "fields": { "type": "array", "minItems": 1, "title": "Fields", "description": "Contact groups to return. Only 'phones' and/or 'emails' are accepted (e.g. [\"phones\"], [\"emails\"], or [\"phones\",\"emails\"]). 'phones' returns phones + mobile_phone; 'emails' returns emails + work_email. No other fields are accepted on this endpoint.", "items": { "type": "string", "enum": [ "phones", "emails" ] } }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "Freeform metadata echoed back unchanged on this item's result (max 10 keys; string, number, or boolean values only)." } }, "title": "DynamicBulkItem", "description": "One dynamic bulk enrichment item: a LinkedIn URL plus the contact groups (phones/emails) to return." }, "DynamicBulkEnrichRequest": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 50, "title": "Items", "description": "List of items to enrich by LinkedIn URL (1-50).", "items": { "$ref": "#/components/schemas/DynamicBulkItem" } } }, "title": "DynamicBulkEnrichRequest", "description": "Dynamic bulk person enrichment request. Resolves each LinkedIn URL and returns only the requested contact groups (phones/emails).", "example": { "items": [ { "social_url": "https://www.linkedin.com/in/jane-doe", "fields": [ "phones" ], "metadata": { "row": "1" } }, { "social_url": "https://www.linkedin.com/in/john-smith", "fields": [ "phones", "emails" ], "metadata": { "row": "2" } } ] } }, "DynamicBulkItemResult": { "type": "object", "properties": { "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata", "description": "The item's metadata, echoed back unchanged." }, "legion_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Legion Id", "description": "The matched person's Legion ID, or null if the URL matched nobody or the item errored." }, "phones": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PhoneResponse" } }, { "type": "null" } ], "title": "Phones", "description": "Present only when 'phones' was requested and the person matched." }, "mobile_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Mobile Phone", "description": "Best mobile phone; present only when 'phones' was requested and the person matched." }, "emails": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EmailResponse" } }, { "type": "null" } ], "title": "Emails", "description": "Present only when 'emails' was requested and the person matched." }, "work_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Work Email", "description": "Best work email; present only when 'emails' was requested and the person matched." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error", "description": "Set when the item could not be served (e.g. no contract entitles the requested fields)." } }, "title": "DynamicBulkItemResult", "description": "One dynamic bulk enrichment result. Only the requested groups are populated; unmatched or errored items have a null legion_id." }, "DynamicBulkEnrichResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "title": "Results", "description": "Per-item results, in the same order as the input items.", "items": { "$ref": "#/components/schemas/DynamicBulkItemResult" } } }, "title": "DynamicBulkEnrichResponse", "description": "Dynamic bulk person enrichment response." } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "in": "header", "name": "API-Key" } } }, "security": [ { "APIKeyHeader": [] } ] }