From b24f228e7bc53eda0703efc3ad9d64c687b62dc1 Mon Sep 17 00:00:00 2001 From: Jesse Ouellette Date: Sun, 19 Apr 2026 15:15:59 -0400 Subject: [PATCH] feat(openapi): add shared error responses, externalDocs, and full rate-limit/server-error coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tighten the public OpenAPI 3.1 snapshot so every operation documents the complete error surface we already enforce at runtime, and give coding-agent tools and SDK generators everything they need to emit good retry logic. Structural additions - components.responses - BadRequest — 400, payload validation failures - Unauthorized — 401, missing/invalid/revoked X-API-Key - TooManyRequests — 429, rate limit exceeded; retry with jitter - InternalServerError — 500, unexpected failure; contact support Each response reuses the pre-existing components.schemas.Error shape, so there's now a single source of truth for every error body we return. - externalDocs at the spec root pointing at https://leadmagic.io/docs so docs renderers surface a "full documentation" link. - info.termsOfService = https://leadmagic.io/terms. Per-operation changes (applied uniformly across all 19 operations) - Replaced every inline 400 (17 ops) and 401 (19 ops) response with $ref to the shared components.responses so the copy, status description, and schema never drift again. - Added 429 and 500 $refs to every operation. Previously only /profile-search declared 429 and no operation declared 500 even though the runtime returns both. Downstream SDK generators (Speakeasy, OpenAPI Generator, Fern) will now emit retry and backoff handlers for rate limits and transient server errors. Info-level tidy - Rewrote info.description: platform-neutral, points to the README for credit costs / MCP sign-in, drops the old "public docs not fully uniform" caveat that had no place in rendered docs. - Reordered info.* into the canonical OpenAPI key sequence (title, summary, description, version, termsOfService, contact, license) for consistency with Redocly/Scalar output. Consistency guarantees - Regenerated leadmagic-openapi-3.1.json from the YAML source of truth. This incidentally fixed a pre-existing YAML/JSON drift: company_facebook_url / company_twitter_url were present in the /email-finder 200 response's YAML but missing from the JSON. The two files are now structurally identical. - All 19 operationIds, summaries, descriptions, tags, and property-level examples preserved byte-for-byte. - Response maps within each operation reordered by status code (2xx, 4xx, 5xx) so the generated docs read top-to-bottom. Verification - swagger-cli validate: both YAML and JSON pass. - spectral lint: zero errors. - tsc --noEmit: clean. - CI deprecated-example regex: no singular example: / "example": fields found. - README required sections still present. - No hardcoded credentials. Made-with: Cursor --- leadmagic-openapi-3.1.json | 5495 ++++++++++++++++++++---------------- leadmagic-openapi-3.1.yaml | 2034 +++++++------ 2 files changed, 4017 insertions(+), 3512 deletions(-) diff --git a/leadmagic-openapi-3.1.json b/leadmagic-openapi-3.1.json index efc8080..c07e4c4 100644 --- a/leadmagic-openapi-3.1.json +++ b/leadmagic-openapi-3.1.json @@ -1,2469 +1,3030 @@ { - "openapi": "3.1.0", - "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", - "info": { - "title": "LeadMagic API", - "version": "1.5.0", - "description": "A clean, consistent, and well-documented API to access LeadMagic's services, including email finding, validation, company and professional profile enrichment, and advertisement searching.\n\n**Important**: Current public docs are not fully uniform on field naming. Some endpoints use snake_case while others show mixed or camelCase response fields.\n", - "contact": { - "name": "LeadMagic API Support", - "url": "https://leadmagic.io", - "email": "support@leadmagic.io" - }, - "license": { - "name": "MIT", - "url": "https://opensource.org/licenses/MIT" - }, - "summary": "Complete API for LeadMagic data enrichment services" - }, - "servers": [ - { - "url": "https://api.leadmagic.io", - "description": "Production API Server" - } - ], - "components": { - "securitySchemes": { - "apiKey": { - "type": "apiKey", - "in": "header", - "name": "X-API-Key", - "description": "API key for authentication. Get your API key from your LeadMagic dashboard." - } - }, - "schemas": { - "Location": { - "type": "object", - "description": "Geographic location information", - "properties": { - "name": { - "type": "string", - "examples": ["boston, massachusetts, united states"] - }, - "locality": { - "type": "string", - "examples": ["boston"] - }, - "region": { - "type": "string", - "examples": ["massachusetts"] - }, - "metro": { - "type": "string", - "examples": ["boston, massachusetts"] - }, - "country": { - "type": "string", - "examples": ["united states"] - }, - "continent": { - "type": "string", - "examples": ["north america"] - }, - "street_address": { - "type": "string", - "examples": ["1 Seaport Lane"] - }, - "address_line_2": { - "type": ["string", "null"] - }, - "postal_code": { - "type": "string", - "examples": ["02210"] - }, - "geo": { - "type": "string", - "examples": ["42.35,-71.06"] - } - } - }, - "DetailedCompany": { - "type": "object", - "description": "Detailed company information from company search", - "properties": { - "company_name": { - "type": "string", - "examples": ["LeadMagic"] - }, - "company_id": { - "type": "integer", - "examples": [75153174] - }, - "locations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "country": { - "type": "string", - "examples": ["US"] - }, - "city": { - "type": "string", - "examples": ["Boston"] - }, - "geographic_area": { - "type": "string", - "examples": ["Massachusetts"] - }, - "postal_code": { - "type": "string", - "examples": ["02210"] - }, - "line1": { - "type": "string", - "examples": ["1 Seaport Ln"] - }, - "line2": { - "type": ["string", "null"] - }, - "description": { - "type": "string", - "examples": ["Headquarters"] - }, - "headquarter": { - "type": "boolean" - }, - "localized_name": { - "type": "string", - "examples": ["Boston"] - }, - "latitude": { - "type": "number", - "examples": [42.36041] - }, - "longitude": { - "type": "number", - "examples": [-71.05798] - } - } - } - }, - "employee_count": { - "type": "integer", - "examples": [9] - }, - "specialities": { - "type": "array", - "items": { - "type": "string" - }, - "examples": [["Sales", "Marketing", "ABM", "RevOps"]] - }, - "employee_count_range": { - "type": "object", - "properties": { - "start": { - "type": "integer", - "examples": [11] - }, - "end": { - "type": "integer", - "examples": [50] - } - } - }, - "tagline": { - "type": "string", - "examples": [ - "LeadMagic tells you who is interested in your products or services. Engage them and build more pipeline, win more deals" - ] - }, - "follower_count": { - "type": "integer", - "examples": [6096] - }, - "industry": { - "type": "string", - "examples": ["Internet"] - }, - "description": { - "type": "string", - "examples": [ - "LeadMagic tells you exactly what businesses are on your website and helps you enrich your contact and company data." - ] - }, - "website_url": { - "type": "string", - "examples": ["https://leadmagic.io"] - }, - "founded_on": { - "type": "object", - "properties": { - "month": { - "type": ["integer", "null"] - }, - "year": { - "type": "integer", - "examples": [2022] - }, - "day": { - "type": ["integer", "null"] - } - } - }, - "universal_name": { - "type": "string", - "examples": ["leadmagichq"] - }, - "hashtag": { - "type": "string", - "examples": ["#abm"] - }, - "industry_v2_taxonomy": { - "type": "string", - "examples": ["Internet Publishing"] - }, - "url": { - "type": "string", - "examples": ["https://profiles.example.com/company/leadmagichq/"] - }, - "credits_consumed": { - "type": "integer", - "examples": [1] - } - } - }, - "PersonProfile": { - "type": "object", - "description": "Personal profile information", - "properties": { - "profile_url": { - "type": "string", - "examples": ["https://profiles.example.com/williamhgates/"] - }, - "first_name": { - "type": "string", - "examples": ["Bill"] - }, - "last_name": { - "type": "string", - "examples": ["Gates"] - }, - "full_name": { - "type": "string", - "examples": ["Bill Gates"] - }, - "public_identifier": { - "type": "string", - "examples": ["williamhgates"] - }, - "headline": { - "type": "string", - "examples": [ - "Chair, Gates Foundation and Founder, Breakthrough Energy" - ] - }, - "company_name": { - "type": "string", - "examples": ["Gates Foundation"] - }, - "company_size": { - "type": "string", - "examples": ["1001-5000"] - }, - "company_industry": { - "type": "string", - "examples": ["investment management"] - }, - "company_linkedin_url": { - "type": "string", - "examples": [ - "profiles.example.com/company/bill-and-melinda-gates-foundation" - ] - }, - "company_website": { - "type": "string", - "examples": ["gatesfoundation.org"] - }, - "total_tenure_months": { - "type": "string", - "examples": ["305"] - }, - "total_tenure_days": { - "type": "string", - "examples": ["9150"] - }, - "total_tenure_years": { - "type": "string", - "examples": ["25.42"] - }, - "connections": { - "type": "integer", - "examples": [8] - }, - "followers": { - "type": "integer", - "examples": [37841613] - }, - "country": { - "type": "string", - "examples": ["United States"] - }, - "location": { - "type": "string", - "examples": ["Seattle, Washington, United States"] - }, - "about": { - "type": "string", - "examples": [ - "Chair of the Gates Foundation. Founder of Breakthrough Energy. Co-founder of Microsoft. Voracious reader. Avid traveler. Active blogger." - ] - }, - "experiences": { - "type": "array", - "items": { - "type": "object", - "properties": { - "company_id": { - "type": "string", - "examples": ["8736"] - }, - "title": { - "type": "string", - "examples": ["Co-chair"] - }, - "subtitle": { - "type": "string", - "examples": ["Gates Foundation"] - }, - "caption": { - "type": "string", - "examples": ["2000 - Present \u00b7 25 yrs 5 mos"] - } - } - } - }, - "educations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "title": { - "type": "string", - "examples": ["Harvard University"] - }, - "caption": { - "type": "string", - "examples": ["1973 - 1975"] - } - } - } - } - } - }, - "GoogleAd": { - "type": "object", - "description": "Google advertisement information", - "properties": { - "advertiser_id": { - "type": "string", - "examples": ["AR14106062795078369281"] - }, - "creative_id": { - "type": "string", - "examples": ["CR14003695067076755457"] - }, - "advertiser_name": { - "type": "string", - "examples": ["Gong.io Inc"] - }, - "format": { - "type": "string", - "examples": ["Text"] - }, - "start": { - "type": "string", - "format": "date", - "examples": ["2025-03-06"] - }, - "last_seen": { - "type": "string", - "format": "date", - "examples": ["2025-06-27"] - }, - "original_url": { - "type": "string", - "examples": [ - "https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457?region=anywhere" - ] - }, - "variants": { - "type": "array", - "items": { - "type": "object", - "properties": { - "content": { - "type": "string", - "description": "HTML content or JavaScript URL for the ad" - }, - "height": { - "type": ["integer", "null"] - }, - "width": { - "type": ["integer", "null"] - } - } - } - } - } - }, - "JobResult": { - "type": "object", - "description": "Job search result", - "properties": { - "company": { - "type": "object", - "properties": { - "name": { - "type": "string", - "examples": ["Microsoft"] - }, - "website_url": { - "type": "string", - "examples": ["https://www.microsoft.com/"] - }, - "linkedin_url": { - "type": "string", - "examples": ["https://profiles.example.com/company/microsoft/"] - }, - "twitter_handle": { - "type": "string", - "examples": ["Microsoft"] - }, - "github_url": { - "type": "string", - "examples": ["https://github.com/microsoft"] - }, - "is_agency": { - "type": "boolean", - "examples": [false] - } - } - }, - "title": { - "type": "string", - "examples": ["Technical Program Manager - Developer (AI)"] - }, - "location": { - "type": "string", - "examples": ["Redmond, Washington, United States"] - }, - "types": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "examples": [1] - }, - "name": { - "type": "string", - "examples": ["Full Time"] - } - } - } - }, - "cities": { - "type": "array", - "items": { - "type": "object", - "properties": { - "geonameid": { - "type": "integer", - "examples": [5808079] - }, - "asciiname": { - "type": "string", - "examples": ["Redmond"] - }, - "name": { - "type": "string", - "examples": ["Redmond"] - }, - "country": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "examples": [238] - }, - "code": { - "type": "string", - "examples": ["US"] - }, - "name": { - "type": "string", - "examples": ["United States"] - } - } - } - } - } - }, - "has_remote": { - "type": "boolean", - "examples": [false] - }, - "published": { - "type": "string", - "format": "date-time", - "examples": ["2025-06-25T20:36:00Z"] - }, - "expired": { - "type": ["string", "null"], - "format": "date-time" - }, - "application_url": { - "type": "string", - "examples": [ - "https://jobs.careers.microsoft.com/global/en/job/1833754/" - ] - }, - "language": { - "type": "string", - "examples": ["en"] - }, - "salary_min": { - "type": "string", - "examples": ["100600"] - }, - "salary_max": { - "type": "string", - "examples": ["215400"] - }, - "salary_currency": { - "type": "string", - "examples": ["USD"] - }, - "experience_level": { - "type": "string", - "examples": ["Mid Level"] - }, - "description": { - "type": "string", - "description": "Full job description text" - } - } - }, - "Error": { - "type": "object", - "properties": { - "error": { - "type": "string", - "examples": ["Bad Request"] - }, - "message": { - "type": "string", - "examples": ["API key is missing or invalid."] - } - } - } - } - }, - "security": [ - { - "apiKey": [] - } - ], - "paths": { - "/credits": { - "post": { - "summary": "Check Credits", - "description": "Check the number of available credits for the authenticated user.", - "operationId": "getCredits", - "tags": ["Credits"], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": {} - } - } - } - }, - "responses": { - "200": { - "description": "Successful credits retrieval.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits": { - "type": "number", - "description": "Available credits balance", - "examples": [7333.8] - }, - "is_frozen": { - "type": "boolean", - "description": "Whether the account's credits are currently frozen.", - "examples": [false] - }, - "credits_frozen": { - "type": "number", - "description": "Portion of credits currently frozen.", - "examples": [0] - }, - "credits_liquid": { - "type": "number", - "description": "Portion of credits currently available for use.", - "examples": [7333.8] - }, - "credit_freeze_message": { - "type": ["string", "null"], - "description": "Optional message describing the freeze state.", - "examples": [null] - }, - "credit_freeze_plan_hint": { - "type": ["string", "null"], - "description": "Optional plan or upgrade hint related to a credit freeze.", - "examples": [null] - } - }, - "required": ["credits"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/email-validate": { - "post": { - "summary": "Email Validation", - "description": "Validate an email address for deliverability and retrieve associated company information.", - "operationId": "validateEmail", - "tags": ["Email"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["email"], - "properties": { - "email": { - "type": "string", - "description": "Email address to validate.", - "examples": ["jesse@leadmagic.io"] - }, - "first_name": { - "type": "string", - "description": "First name of the person (optional).", - "examples": ["Jesse"] - }, - "last_name": { - "type": "string", - "description": "Last name of the person (optional).", - "examples": ["Ouellette"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful validation.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "examples": ["jesse@leadmagic.io"] - }, - "email_status": { - "type": "string", - "enum": [ - "valid", - "valid_catch_all", - "invalid", - "unknown", - "catch_all" - ], - "examples": ["valid"] - }, - "credits_consumed": { - "type": "number", - "examples": [0.05] - }, - "message": { - "type": "string", - "examples": ["Email is valid."] - }, - "is_domain_catch_all": { - "type": "boolean", - "examples": [false] - }, - "mx_record": { - "type": "string", - "examples": ["aspmx.l.google.com"] - }, - "mx_provider": { - "type": "string", - "examples": ["Google Workspace"] - }, - "mx_security_gateway": { - "type": "boolean", - "examples": [false] - }, - "company_name": { - "type": "string", - "examples": ["Leadmagic"] - }, - "company_industry": { - "type": "string", - "examples": ["Internet"] - }, - "company_size": { - "type": "string", - "examples": ["11-50"] - }, - "company_founded": { - "type": "integer", - "examples": [2022] - }, - "company_type": { - "type": "string", - "examples": ["private"] - }, - "company_linkedin_url": { - "type": "string", - "examples": ["profiles.example.com/company/leadmagichq"] - }, - "company_linkedin_id": { - "type": "string", - "examples": ["75153174"] - }, - "company_facebook_url": { - "type": ["string", "null"] - }, - "company_twitter_url": { - "type": ["string", "null"] - }, - "company_location": { - "$ref": "#/components/schemas/Location" - } - }, - "required": ["email", "email_status", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/email-finder": { - "post": { - "summary": "Email Finder", - "description": "Finds a verified email address based on a person's name and company.", - "operationId": "findEmail", - "tags": ["Email"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["first_name", "last_name"], - "properties": { - "first_name": { - "type": "string", - "description": "The person's first name.", - "examples": ["Bill"] - }, - "last_name": { - "type": "string", - "description": "The person's last name.", - "examples": ["Gates"] - }, - "domain": { - "type": "string", - "description": "The company's domain name.", - "examples": ["microsoft.com"] - }, - "company_name": { - "type": "string", - "description": "The company's name (used if domain is unknown).", - "examples": ["Microsoft"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful email discovery.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "email": { - "type": "string", - "examples": ["billg@microsoft.com"] - }, - "status": { - "type": "string", - "enum": ["valid", "valid_catch_all", "not_found"], - "examples": ["valid"] - }, - "credits_consumed": { - "type": "integer", - "examples": [1] - }, - "message": { - "type": "string", - "examples": ["Valid email found."] - }, - "first_name": { - "type": "string", - "examples": ["Bill"] - }, - "last_name": { - "type": "string", - "examples": ["Gates"] - }, - "domain": { - "type": "string", - "examples": ["microsoft.com"] - }, - "is_domain_catch_all": { - "type": "boolean", - "examples": [false] - }, - "mx_record": { - "type": "string", - "examples": ["microsoft-com.mail.protection.outlook.com"] - }, - "mx_provider": { - "type": "string", - "examples": ["Microsoft 365"] - }, - "mx_security_gateway": { - "type": "boolean", - "examples": [false] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "company_industry": { - "type": "string", - "examples": ["Computer Software"] - }, - "company_size": { - "type": "string", - "examples": ["10001+"] - }, - "company_founded": { - "type": "integer", - "examples": [1975] - }, - "company_type": { - "type": "string", - "examples": ["public"] - }, - "company_linkedin_url": { - "type": "string", - "examples": ["profiles.example.com/company/microsoft"] - }, - "company_linkedin_id": { - "type": "string", - "examples": ["1035"] - }, - "company_location": { - "$ref": "#/components/schemas/Location" - } - }, - "required": ["email", "status", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/profile-search": { - "post": { - "summary": "Profile Search", - "description": "Provide a B2B profile URL (for example, a professional social profile) to get full profile details. \nRate limit: 300 requests/minute.\n", - "operationId": "searchProfile", - "tags": ["Profiles"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["profile_url"], - "properties": { - "profile_url": { - "type": "string", - "description": "Full URL of the B2B profile.", - "examples": ["https://profiles.example.com/williamhgates/"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful retrieval of profile information.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits_consumed": { - "type": "number", - "examples": [1] - } - }, - "required": ["credits_consumed"], - "allOf": [ - { - "$ref": "#/components/schemas/PersonProfile" - } - ] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/company-search": { - "post": { - "summary": "Company Search", - "description": "Search for company details using its domain, name, or profile URL.", - "operationId": "searchCompany", - "tags": ["Companies"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Provide at least one of the following to find company details.", - "properties": { - "company_domain": { - "type": "string", - "examples": ["leadmagic.io"] - }, - "company_name": { - "type": "string", - "examples": ["Leadmagic"] - }, - "profile_url": { - "type": "string", - "examples": [ - "https://profiles.example.com/company/leadmagichq" - ] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful retrieval of company details.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits_consumed": { - "type": "integer", - "examples": [1] - } - }, - "required": ["credits_consumed"], - "allOf": [ - { - "$ref": "#/components/schemas/DetailedCompany" - } - ] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/jobs-finder": { - "post": { - "summary": "Jobs Finder", - "description": "Searches for job postings based on various criteria.", - "operationId": "findJobs", - "tags": ["Jobs"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "company_name": { - "type": "string", - "description": "Filter by company name.", - "examples": ["Microsoft"] - }, - "company_website": { - "type": "string", - "description": "Filter by company website.", - "examples": ["microsoft.com"] - }, - "job_title": { - "type": "string", - "description": "Filter by job title.", - "examples": ["Developer"] - }, - "location": { - "type": "string", - "description": "Filter by job location.", - "examples": ["New York"] - }, - "experience_level": { - "type": "string", - "description": "Required experience level.", - "enum": ["entry", "mid", "senior", "executive"], - "examples": ["senior"] - }, - "job_description": { - "type": "string", - "description": "Keywords from the job description.", - "examples": ["python \"software engineer\""] - }, - "country_id": { - "type": "string", - "description": "Filter jobs by country ID.", - "examples": ["US"] - }, - "page": { - "type": "integer", - "default": 1, - "minimum": 1, - "examples": [1] - }, - "per_page": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 50, - "description": "Number of results per page. Maximum of 50.", - "examples": [5] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful job search.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "total_count": { - "type": "integer", - "examples": [105] - }, - "page": { - "type": "integer", - "examples": [1] - }, - "per_page": { - "type": "integer", - "examples": [5] - }, - "total_pages": { - "type": "integer", - "examples": [21] - }, - "credits_consumed": { - "type": "integer", - "examples": [5] - }, - "results": { - "type": "array", - "items": { - "$ref": "#/components/schemas/JobResult" - } - } - }, - "required": [ - "total_count", - "page", - "per_page", - "total_pages", - "credits_consumed", - "results" - ] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/google/searchads": { - "post": { - "summary": "Google Ads Search", - "description": "Search for Google Ads based on a company's domain or name.", - "operationId": "searchGoogleAds", - "tags": ["Advertisements"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Provide a company name or domain to search for ads.", - "properties": { - "company_domain": { - "type": "string", - "examples": ["gong.io"] - }, - "company_name": { - "type": "string", - "examples": ["gong"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful retrieval of Google Ads.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits_consumed": { - "type": "number", - "examples": [8] - }, - "ads": { - "type": "array", - "items": { - "$ref": "#/components/schemas/GoogleAd" - } - } - }, - "required": ["credits_consumed", "ads"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/meta/searchads": { - "post": { - "summary": "Meta (Facebook/Instagram) Ads Search", - "description": "Search for Meta Ads based on a company's domain or name.", - "operationId": "searchMetaAds", - "tags": ["Advertisements"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Provide a company name or domain to search for ads.", - "properties": { - "company_domain": { - "type": "string", - "examples": ["gong.io"] - }, - "company_name": { - "type": "string", - "examples": ["gong"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful retrieval of Meta Ads.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits_consumed": { - "type": "number", - "examples": [2.6] - }, - "ads": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ad_archive_id": { - "type": "string", - "examples": ["618153827656899"] - }, - "page_id": { - "type": "string", - "examples": ["105549201674375"] - }, - "page_name": { - "type": "string", - "examples": ["Lykkedal Retreat"] - }, - "is_active": { - "type": "boolean" - }, - "publisher_platform": { - "type": "array", - "items": { - "type": "string" - }, - "examples": [["facebook", "instagram"]] - }, - "snapshot": { - "type": "object", - "properties": { - "body": { - "type": "object", - "properties": { - "markup": { - "type": "string" - } - } - }, - "title": { - "type": "string" - }, - "cta_text": { - "type": "string" - }, - "images": { - "type": "array", - "items": { - "type": "object", - "properties": { - "original_image_url": { - "type": "string", - "format": "uri" - } - } - } - }, - "videos": { - "type": "array", - "items": { - "type": "object", - "properties": { - "video_hd_url": { - "type": "string", - "format": "uri" - } - } - } - } - } - } - } - } - } - }, - "required": ["credits_consumed", "ads"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/mobile-finder": { - "post": { - "summary": "Mobile Finder", - "description": "Find mobile phone numbers using profile URL, work email, or personal email.", - "operationId": "findMobile", - "tags": ["Mobile"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Provide at least one of the following parameters.", - "properties": { - "profile_url": { - "type": "string", - "examples": ["https://profiles.example.com/williamhgates/"] - }, - "work_email": { - "type": "string", - "examples": ["jesse@leadmagic.io"] - }, - "personal_email": { - "type": "string", - "examples": ["jesse.ouellette@gmail.com"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Mobile search response.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "message": { - "type": "string", - "examples": ["mobile not found", "Mobile found"] - }, - "credits_consumed": { - "type": "number", - "examples": [0, 1] - }, - "mobile_number": { - "type": ["string", "null"], - "examples": ["+1234567890"] - } - }, - "required": ["message", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/b2b-profile": { - "post": { - "summary": "Email Address to B2B Profile", - "description": "Find B2B profile URL using work email address.", - "operationId": "emailToProfile", - "tags": ["Profiles"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["work_email"], - "properties": { - "work_email": { - "type": "string", - "examples": ["jesse@leadmagic.io"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Profile URL found.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "profile_url": { - "type": "string", - "examples": ["https://profiles.example.com/jesseouehwx"] - }, - "message": { - "type": "string", - "examples": ["Profile URL found"] - }, - "credits_consumed": { - "type": "integer", - "examples": [10] - } - }, - "required": ["message", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/role-finder": { - "post": { - "summary": "Role Finder", - "description": "Find specific roles/positions within a company.", - "operationId": "findRole", - "tags": ["People"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["job_title"], - "properties": { - "job_title": { - "type": "string", - "examples": ["Developer"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "company_domain": { - "type": "string", - "examples": ["microsoft.com"] - }, - "company_profile_url": { - "type": "string", - "examples": [ - "https://profiles.example.com/company/microsoft" - ] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Role search response.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "message": { - "type": "string", - "examples": ["Role not found.", "Role found."] - }, - "credits_consumed": { - "type": "integer", - "examples": [0, 1] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "company_website": { - "type": "string", - "examples": ["microsoft.com"] - } - }, - "required": ["message", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/employee-finder": { - "post": { - "summary": "Employee Finder", - "description": "Find employees of a specific company.", - "operationId": "findEmployees", - "tags": ["People"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["company_name"], - "properties": { - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "page": { - "type": "integer", - "default": 1, - "minimum": 1, - "examples": [1] - }, - "per_page": { - "type": "integer", - "default": 20, - "minimum": 1, - "maximum": 50, - "examples": [5] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Employee search results.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "message": { - "type": "string", - "examples": ["Data found for the given company."] - }, - "total_count": { - "type": "integer", - "examples": [5000] - }, - "returned_count": { - "type": "integer", - "examples": [20] - }, - "credits_consumed": { - "type": "integer", - "examples": [1] - }, - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "first_name": { - "type": "string", - "examples": ["John"] - }, - "last_name": { - "type": "string", - "examples": ["Doe"] - }, - "title": { - "type": "string", - "examples": ["Senior Software Engineer"] - }, - "website": { - "type": "string", - "examples": ["http://www.microsoft.com"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - } - } - } - } - }, - "required": ["message", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/company-funding": { - "post": { - "summary": "Company Funding", - "description": "Get comprehensive funding information, financials, competitors, and company insights.", - "operationId": "getCompanyFunding", - "tags": ["Companies"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "company_domain": { - "type": "string", - "examples": ["microsoft.com"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Comprehensive company funding and business information.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "basicInfo": { - "type": "object", - "properties": { - "companyName": { - "type": "string", - "examples": ["Microsoft Corp."] - }, - "description": { - "type": "string" - }, - "shortName": { - "type": "string", - "examples": ["Microsoft"] - }, - "founded": { - "type": "string", - "examples": ["1975"] - }, - "primaryDomain": { - "type": "string", - "examples": ["microsoft.com"] - }, - "phone": { - "type": "string", - "examples": ["1-124-415-8000"] - }, - "status": { - "type": "string", - "examples": ["NEW"] - }, - "followers": { - "type": "integer", - "examples": [181691] - }, - "ownership": { - "type": "string", - "examples": ["Public"] - } - } - }, - "financialInfo": { - "type": "object", - "properties": { - "revenue": { - "type": "integer", - "examples": [270010000000] - }, - "formattedRevenue": { - "type": "string", - "examples": ["270B"] - }, - "totalFunding": { - "type": "integer", - "examples": [61000000] - }, - "formattedFunding": { - "type": "string", - "examples": ["61M"] - } - } - }, - "companySize": { - "type": "object", - "properties": { - "employees": { - "type": "integer", - "examples": [221000] - }, - "employeeRange": { - "type": "string", - "examples": ["100,000 - 9,999,999"] - } - } - }, - "topCompetitors": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string", - "examples": ["IBM"] - }, - "revenue": { - "type": "string", - "examples": [""] - }, - "employees": { - "type": "string", - "examples": ["311,300"] - }, - "website": { - "type": "string", - "examples": ["https://www.ibm.com"] - } - } - } - }, - "credits_consumed": { - "type": "integer", - "examples": [4] - } - }, - "required": ["credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/job-country": { - "get": { - "summary": "Get Job Countries", - "description": "Retrieve list of available countries for job filtering.", - "operationId": "getJobCountries", - "tags": ["Jobs"], - "responses": { - "200": { - "description": "List of available countries.", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "examples": ["US", "CA", "UK"] - }, - "name": { - "type": "string", - "examples": [ - "United States", - "Canada", - "United Kingdom" - ] - } - } - } - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/job-types": { - "get": { - "summary": "Get Job Types", - "description": "Retrieve list of available job types for filtering.", - "operationId": "getJobTypes", - "tags": ["Jobs"], - "responses": { - "200": { - "description": "List of available job types.", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "examples": [1, 2, 3] - }, - "name": { - "type": "string", - "examples": ["Full Time", "Part Time", "Contract"] - } - } - } - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/personal-email-finder": { - "post": { - "summary": "Personal Email Finder", - "description": "Find personal email addresses from B2B profile URLs.", - "operationId": "findPersonalEmail", - "tags": ["Email"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["profile_url"], - "properties": { - "profile_url": { - "type": "string", - "description": "B2B profile URL (for example, a professional social profile)", - "examples": ["https://profiles.example.com/williamhgates/"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Personal email search response.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "personal_email": { - "type": ["string", "null"], - "examples": ["bill.gates@gmail.com"] - }, - "status": { - "type": "string", - "enum": ["found", "not_found"], - "examples": ["found"] - }, - "credits_consumed": { - "type": "integer", - "examples": [1] - }, - "message": { - "type": "string", - "examples": [ - "Personal email found", - "Personal email not found" - ] - } - }, - "required": ["status", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/b2b-social-email": { - "post": { - "summary": "B2B Social to Email", - "description": "Find work email addresses from B2B profile URLs.", - "operationId": "socialToWorkEmail", - "tags": ["Email"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["profile_url"], - "properties": { - "profile_url": { - "type": "string", - "description": "B2B profile URL (for example, a professional social profile)", - "examples": ["https://profiles.example.com/williamhgates/"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Work email search response.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "work_email": { - "type": ["string", "null"], - "examples": ["bill.gates@microsoft.com"] - }, - "status": { - "type": "string", - "enum": ["found", "not_found"], - "examples": ["found"] - }, - "credits_consumed": { - "type": "integer", - "examples": [1] - }, - "message": { - "type": "string", - "examples": ["Work email found", "Work email not found"] - } - }, - "required": ["status", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/b2b/searchads": { - "post": { - "summary": "B2B Ads Search", - "description": "Search for B2B Ads based on a company's domain or name.", - "operationId": "searchB2BAds", - "tags": ["Advertisements"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "description": "Provide a company name or domain to search for ads.", - "properties": { - "company_domain": { - "type": "string", - "examples": ["microsoft.com"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Successful retrieval of B2B Ads.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "credits_consumed": { - "type": "number", - "examples": [5] - }, - "ads": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ad_id": { - "type": "string", - "examples": ["12345"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "ad_title": { - "type": "string", - "examples": ["Microsoft Azure Cloud Services"] - }, - "ad_description": { - "type": "string" - }, - "ad_url": { - "type": "string", - "format": "uri" - } - } - } - } - }, - "required": ["credits_consumed", "ads"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/b2b/ad-details": { - "post": { - "summary": "B2B Ad Details", - "description": "Get detailed information about a specific B2B ad.", - "operationId": "getB2BAdDetails", - "tags": ["Advertisements"], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": ["ad_id"], - "properties": { - "ad_id": { - "type": "string", - "description": "B2B ad ID", - "examples": ["12345"] - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Detailed B2B ad information.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "ad_id": { - "type": "string", - "examples": ["12345"] - }, - "company_name": { - "type": "string", - "examples": ["Microsoft"] - }, - "ad_title": { - "type": "string", - "examples": ["Microsoft Azure Cloud Services"] - }, - "ad_description": { - "type": "string" - }, - "ad_url": { - "type": "string", - "format": "uri" - }, - "campaign_info": { - "type": "object", - "properties": { - "campaign_name": { - "type": "string" - }, - "start_date": { - "type": "string", - "format": "date" - }, - "end_date": { - "type": ["string", "null"], - "format": "date" - } - } - }, - "credits_consumed": { - "type": "integer", - "examples": [2] - } - }, - "required": ["ad_id", "credits_consumed"] - } - } - } - }, - "400": { - "description": "Bad Request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "401": { - "description": "Unauthorized - Invalid API key.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "tags": [ - { - "name": "Advertisements", - "description": "Advertisement intelligence" - }, - { - "name": "Companies", - "description": "Company information and enrichment" - }, - { - "name": "Credits", - "description": "Credit management operations" - }, - { - "name": "Email", - "description": "Email finding and validation" - }, - { - "name": "Jobs", - "description": "Job posting search" - }, - { - "name": "Mobile", - "description": "Mobile number finding" - }, - { - "name": "People", - "description": "People enrichment and search" - }, - { - "name": "Profiles", - "description": "Professional profile enrichment" - } - ] + "openapi": "3.1.0", + "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", + "info": { + "title": "LeadMagic API", + "summary": "Complete API for LeadMagic data enrichment services", + "description": "Official OpenAPI 3.1 snapshot for the LeadMagic B2B data API: email finding and validation, contact and company enrichment, profile and job enrichment, advertisement search, and credit management.\n\nAuthenticate every request with the `X-API-Key` header. Keys are issued from https://app.leadmagic.io. Rate limits, credit costs, and MCP sign-in are documented in the repository README.", + "version": "1.5.0", + "termsOfService": "https://leadmagic.io/terms", + "contact": { + "name": "LeadMagic API Support", + "url": "https://leadmagic.io", + "email": "support@leadmagic.io" + }, + "license": { + "name": "MIT", + "url": "https://opensource.org/licenses/MIT" + } + }, + "servers": [ + { + "url": "https://api.leadmagic.io", + "description": "Production API Server" + } + ], + "externalDocs": { + "description": "LeadMagic documentation", + "url": "https://leadmagic.io/docs" + }, + "security": [ + { + "apiKey": [] + } + ], + "tags": [ + { + "name": "Advertisements", + "description": "Advertisement intelligence" + }, + { + "name": "Companies", + "description": "Company information and enrichment" + }, + { + "name": "Credits", + "description": "Credit management operations" + }, + { + "name": "Email", + "description": "Email finding and validation" + }, + { + "name": "Jobs", + "description": "Job posting search" + }, + { + "name": "Mobile", + "description": "Mobile number finding" + }, + { + "name": "People", + "description": "People enrichment and search" + }, + { + "name": "Profiles", + "description": "Professional profile enrichment" + } + ], + "paths": { + "/credits": { + "post": { + "summary": "Check Credits", + "description": "Check the number of available credits for the authenticated user.", + "operationId": "getCredits", + "tags": [ + "Credits" + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": {} + } + } + } + }, + "responses": { + "200": { + "description": "Successful credits retrieval.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits": { + "type": "number", + "description": "Available credits balance", + "examples": [ + 7333.8 + ] + }, + "is_frozen": { + "type": "boolean", + "description": "Whether the account's credits are currently frozen.", + "examples": [ + false + ] + }, + "credits_frozen": { + "type": "number", + "description": "Portion of credits currently frozen.", + "examples": [ + 0 + ] + }, + "credits_liquid": { + "type": "number", + "description": "Portion of credits currently available for use.", + "examples": [ + 7333.8 + ] + }, + "credit_freeze_message": { + "type": [ + "string", + "null" + ], + "description": "Optional message describing the freeze state.", + "examples": [ + null + ] + }, + "credit_freeze_plan_hint": { + "type": [ + "string", + "null" + ], + "description": "Optional plan or upgrade hint related to a credit freeze.", + "examples": [ + null + ] + } + }, + "required": [ + "credits" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/email-validate": { + "post": { + "summary": "Email Validation", + "description": "Validate an email address for deliverability and retrieve associated company information.", + "operationId": "validateEmail", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "email": { + "type": "string", + "description": "Email address to validate.", + "examples": [ + "jesse@leadmagic.io" + ] + }, + "first_name": { + "type": "string", + "description": "First name of the person (optional).", + "examples": [ + "Jesse" + ] + }, + "last_name": { + "type": "string", + "description": "Last name of the person (optional).", + "examples": [ + "Ouellette" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful validation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "email": { + "type": "string", + "examples": [ + "jesse@leadmagic.io" + ] + }, + "email_status": { + "type": "string", + "enum": [ + "valid", + "valid_catch_all", + "invalid", + "unknown", + "catch_all" + ], + "examples": [ + "valid" + ] + }, + "credits_consumed": { + "type": "number", + "examples": [ + 0.05 + ] + }, + "message": { + "type": "string", + "examples": [ + "Email is valid." + ] + }, + "is_domain_catch_all": { + "type": "boolean", + "examples": [ + false + ] + }, + "mx_record": { + "type": "string", + "examples": [ + "aspmx.l.google.com" + ] + }, + "mx_provider": { + "type": "string", + "examples": [ + "Google Workspace" + ] + }, + "mx_security_gateway": { + "type": "boolean", + "examples": [ + false + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Leadmagic" + ] + }, + "company_industry": { + "type": "string", + "examples": [ + "Internet" + ] + }, + "company_size": { + "type": "string", + "examples": [ + "11-50" + ] + }, + "company_founded": { + "type": "integer", + "examples": [ + 2022 + ] + }, + "company_type": { + "type": "string", + "examples": [ + "private" + ] + }, + "company_linkedin_url": { + "type": "string", + "examples": [ + "profiles.example.com/company/leadmagichq" + ] + }, + "company_linkedin_id": { + "type": "string", + "examples": [ + "75153174" + ] + }, + "company_facebook_url": { + "type": [ + "string", + "null" + ] + }, + "company_twitter_url": { + "type": [ + "string", + "null" + ] + }, + "company_location": { + "$ref": "#/components/schemas/Location" + } + }, + "required": [ + "email", + "email_status", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/email-finder": { + "post": { + "summary": "Email Finder", + "description": "Finds a verified email address based on a person's name and company.", + "operationId": "findEmail", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "first_name", + "last_name" + ], + "properties": { + "first_name": { + "type": "string", + "description": "The person's first name.", + "examples": [ + "Bill" + ] + }, + "last_name": { + "type": "string", + "description": "The person's last name.", + "examples": [ + "Gates" + ] + }, + "domain": { + "type": "string", + "description": "The company's domain name.", + "examples": [ + "microsoft.com" + ] + }, + "company_name": { + "type": "string", + "description": "The company's name (used if domain is unknown).", + "examples": [ + "Microsoft" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful email discovery.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "email": { + "type": "string", + "examples": [ + "billg@microsoft.com" + ] + }, + "status": { + "type": "string", + "enum": [ + "valid", + "valid_catch_all", + "not_found" + ], + "examples": [ + "valid" + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + }, + "message": { + "type": "string", + "examples": [ + "Valid email found." + ] + }, + "first_name": { + "type": "string", + "examples": [ + "Bill" + ] + }, + "last_name": { + "type": "string", + "examples": [ + "Gates" + ] + }, + "domain": { + "type": "string", + "examples": [ + "microsoft.com" + ] + }, + "is_domain_catch_all": { + "type": "boolean", + "examples": [ + false + ] + }, + "mx_record": { + "type": "string", + "examples": [ + "microsoft-com.mail.protection.outlook.com" + ] + }, + "mx_provider": { + "type": "string", + "examples": [ + "Microsoft 365" + ] + }, + "mx_security_gateway": { + "type": "boolean", + "examples": [ + false + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "company_industry": { + "type": "string", + "examples": [ + "Computer Software" + ] + }, + "company_size": { + "type": "string", + "examples": [ + "10001+" + ] + }, + "company_founded": { + "type": "integer", + "examples": [ + 1975 + ] + }, + "company_type": { + "type": "string", + "examples": [ + "public" + ] + }, + "company_linkedin_url": { + "type": "string", + "examples": [ + "profiles.example.com/company/microsoft" + ] + }, + "company_linkedin_id": { + "type": "string", + "examples": [ + "1035" + ] + }, + "company_facebook_url": { + "type": "string", + "examples": [ + "facebook.com/microsoft" + ] + }, + "company_twitter_url": { + "type": "string", + "examples": [ + "twitter.com/microsoft" + ] + }, + "company_location": { + "$ref": "#/components/schemas/Location" + } + }, + "required": [ + "email", + "status", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/profile-search": { + "post": { + "summary": "Profile Search", + "description": "Provide a B2B profile URL (for example, a professional social profile) to get full profile details. \nRate limit: 300 requests/minute.\n", + "operationId": "searchProfile", + "tags": [ + "Profiles" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "profile_url" + ], + "properties": { + "profile_url": { + "type": "string", + "description": "Full URL of the B2B profile.", + "examples": [ + "https://profiles.example.com/williamhgates/" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful retrieval of profile information.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits_consumed": { + "type": "number", + "examples": [ + 1 + ] + } + }, + "required": [ + "credits_consumed" + ], + "allOf": [ + { + "$ref": "#/components/schemas/PersonProfile" + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/company-search": { + "post": { + "summary": "Company Search", + "description": "Search for company details using its domain, name, or profile URL.", + "operationId": "searchCompany", + "tags": [ + "Companies" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Provide at least one of the following to find company details.", + "properties": { + "company_domain": { + "type": "string", + "examples": [ + "leadmagic.io" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Leadmagic" + ] + }, + "profile_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/company/leadmagichq" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful retrieval of company details.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + } + }, + "required": [ + "credits_consumed" + ], + "allOf": [ + { + "$ref": "#/components/schemas/DetailedCompany" + } + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/jobs-finder": { + "post": { + "summary": "Jobs Finder", + "description": "Searches for job postings based on various criteria.", + "operationId": "findJobs", + "tags": [ + "Jobs" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "company_name": { + "type": "string", + "description": "Filter by company name.", + "examples": [ + "Microsoft" + ] + }, + "company_website": { + "type": "string", + "description": "Filter by company website.", + "examples": [ + "microsoft.com" + ] + }, + "job_title": { + "type": "string", + "description": "Filter by job title.", + "examples": [ + "Developer" + ] + }, + "location": { + "type": "string", + "description": "Filter by job location.", + "examples": [ + "New York" + ] + }, + "experience_level": { + "type": "string", + "description": "Required experience level.", + "enum": [ + "entry", + "mid", + "senior", + "executive" + ], + "examples": [ + "senior" + ] + }, + "job_description": { + "type": "string", + "description": "Keywords from the job description.", + "examples": [ + "python \"software engineer\"" + ] + }, + "country_id": { + "type": "string", + "description": "Filter jobs by country ID.", + "examples": [ + "US" + ] + }, + "page": { + "type": "integer", + "default": 1, + "minimum": 1, + "examples": [ + 1 + ] + }, + "per_page": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 50, + "description": "Number of results per page. Maximum of 50.", + "examples": [ + 5 + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful job search.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "total_count": { + "type": "integer", + "examples": [ + 105 + ] + }, + "page": { + "type": "integer", + "examples": [ + 1 + ] + }, + "per_page": { + "type": "integer", + "examples": [ + 5 + ] + }, + "total_pages": { + "type": "integer", + "examples": [ + 21 + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 5 + ] + }, + "results": { + "type": "array", + "items": { + "$ref": "#/components/schemas/JobResult" + } + } + }, + "required": [ + "total_count", + "page", + "per_page", + "total_pages", + "credits_consumed", + "results" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/google/searchads": { + "post": { + "summary": "Google Ads Search", + "description": "Search for Google Ads based on a company's domain or name.", + "operationId": "searchGoogleAds", + "tags": [ + "Advertisements" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Provide a company name or domain to search for ads.", + "properties": { + "company_domain": { + "type": "string", + "examples": [ + "gong.io" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "gong" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful retrieval of Google Ads.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits_consumed": { + "type": "number", + "examples": [ + 8 + ] + }, + "ads": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GoogleAd" + } + } + }, + "required": [ + "credits_consumed", + "ads" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/meta/searchads": { + "post": { + "summary": "Meta (Facebook/Instagram) Ads Search", + "description": "Search for Meta Ads based on a company's domain or name.", + "operationId": "searchMetaAds", + "tags": [ + "Advertisements" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Provide a company name or domain to search for ads.", + "properties": { + "company_domain": { + "type": "string", + "examples": [ + "gong.io" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "gong" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful retrieval of Meta Ads.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits_consumed": { + "type": "number", + "examples": [ + 2.6 + ] + }, + "ads": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ad_archive_id": { + "type": "string", + "examples": [ + "618153827656899" + ] + }, + "page_id": { + "type": "string", + "examples": [ + "105549201674375" + ] + }, + "page_name": { + "type": "string", + "examples": [ + "Lykkedal Retreat" + ] + }, + "is_active": { + "type": "boolean" + }, + "publisher_platform": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "facebook", + "instagram" + ] + ] + }, + "snapshot": { + "type": "object", + "properties": { + "body": { + "type": "object", + "properties": { + "markup": { + "type": "string" + } + } + }, + "title": { + "type": "string" + }, + "cta_text": { + "type": "string" + }, + "images": { + "type": "array", + "items": { + "type": "object", + "properties": { + "original_image_url": { + "type": "string", + "format": "uri" + } + } + } + }, + "videos": { + "type": "array", + "items": { + "type": "object", + "properties": { + "video_hd_url": { + "type": "string", + "format": "uri" + } + } + } + } + } + } + } + } + } + }, + "required": [ + "credits_consumed", + "ads" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/mobile-finder": { + "post": { + "summary": "Mobile Finder", + "description": "Find mobile phone numbers using profile URL, work email, or personal email.", + "operationId": "findMobile", + "tags": [ + "Mobile" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Provide at least one of the following parameters.", + "properties": { + "profile_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/williamhgates/" + ] + }, + "work_email": { + "type": "string", + "examples": [ + "jesse@leadmagic.io" + ] + }, + "personal_email": { + "type": "string", + "examples": [ + "jesse.ouellette@gmail.com" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Mobile search response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "examples": [ + "mobile not found", + "Mobile found" + ] + }, + "credits_consumed": { + "type": "number", + "examples": [ + 0, + 1 + ] + }, + "mobile_number": { + "type": [ + "string", + "null" + ], + "examples": [ + "+1234567890" + ] + } + }, + "required": [ + "message", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/b2b-profile": { + "post": { + "summary": "Email Address to B2B Profile", + "description": "Find B2B profile URL using work email address.", + "operationId": "emailToProfile", + "tags": [ + "Profiles" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "work_email" + ], + "properties": { + "work_email": { + "type": "string", + "examples": [ + "jesse@leadmagic.io" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Profile URL found.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "profile_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/jesseouehwx" + ] + }, + "message": { + "type": "string", + "examples": [ + "Profile URL found" + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 10 + ] + } + }, + "required": [ + "message", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/role-finder": { + "post": { + "summary": "Role Finder", + "description": "Find specific roles/positions within a company.", + "operationId": "findRole", + "tags": [ + "People" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "job_title" + ], + "properties": { + "job_title": { + "type": "string", + "examples": [ + "Developer" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "company_domain": { + "type": "string", + "examples": [ + "microsoft.com" + ] + }, + "company_profile_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/company/microsoft" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Role search response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "examples": [ + "Role not found.", + "Role found." + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 0, + 1 + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "company_website": { + "type": "string", + "examples": [ + "microsoft.com" + ] + } + }, + "required": [ + "message", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/employee-finder": { + "post": { + "summary": "Employee Finder", + "description": "Find employees of a specific company.", + "operationId": "findEmployees", + "tags": [ + "People" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "company_name" + ], + "properties": { + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "page": { + "type": "integer", + "default": 1, + "minimum": 1, + "examples": [ + 1 + ] + }, + "per_page": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 50, + "examples": [ + 5 + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Employee search results.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "examples": [ + "Data found for the given company." + ] + }, + "total_count": { + "type": "integer", + "examples": [ + 5000 + ] + }, + "returned_count": { + "type": "integer", + "examples": [ + 20 + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + }, + "data": { + "type": "array", + "items": { + "type": "object", + "properties": { + "first_name": { + "type": "string", + "examples": [ + "John" + ] + }, + "last_name": { + "type": "string", + "examples": [ + "Doe" + ] + }, + "title": { + "type": "string", + "examples": [ + "Senior Software Engineer" + ] + }, + "website": { + "type": "string", + "examples": [ + "http://www.microsoft.com" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + } + } + } + } + }, + "required": [ + "message", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/company-funding": { + "post": { + "summary": "Company Funding", + "description": "Get comprehensive funding information, financials, competitors, and company insights.", + "operationId": "getCompanyFunding", + "tags": [ + "Companies" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "company_domain": { + "type": "string", + "examples": [ + "microsoft.com" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Comprehensive company funding and business information.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "basicInfo": { + "type": "object", + "properties": { + "companyName": { + "type": "string", + "examples": [ + "Microsoft Corp." + ] + }, + "description": { + "type": "string" + }, + "shortName": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "founded": { + "type": "string", + "examples": [ + "1975" + ] + }, + "primaryDomain": { + "type": "string", + "examples": [ + "microsoft.com" + ] + }, + "phone": { + "type": "string", + "examples": [ + "1-124-415-8000" + ] + }, + "status": { + "type": "string", + "examples": [ + "NEW" + ] + }, + "followers": { + "type": "integer", + "examples": [ + 181691 + ] + }, + "ownership": { + "type": "string", + "examples": [ + "Public" + ] + } + } + }, + "financialInfo": { + "type": "object", + "properties": { + "revenue": { + "type": "integer", + "examples": [ + 270010000000 + ] + }, + "formattedRevenue": { + "type": "string", + "examples": [ + "270B" + ] + }, + "totalFunding": { + "type": "integer", + "examples": [ + 61000000 + ] + }, + "formattedFunding": { + "type": "string", + "examples": [ + "61M" + ] + } + } + }, + "companySize": { + "type": "object", + "properties": { + "employees": { + "type": "integer", + "examples": [ + 221000 + ] + }, + "employeeRange": { + "type": "string", + "examples": [ + "100,000 - 9,999,999" + ] + } + } + }, + "topCompetitors": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "examples": [ + "IBM" + ] + }, + "revenue": { + "type": "string", + "examples": [ + "" + ] + }, + "employees": { + "type": "string", + "examples": [ + "311,300" + ] + }, + "website": { + "type": "string", + "examples": [ + "https://www.ibm.com" + ] + } + } + } + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 4 + ] + } + }, + "required": [ + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/job-country": { + "get": { + "summary": "Get Job Countries", + "description": "Retrieve list of available countries for job filtering.", + "operationId": "getJobCountries", + "tags": [ + "Jobs" + ], + "responses": { + "200": { + "description": "List of available countries.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "examples": [ + "US", + "CA", + "UK" + ] + }, + "name": { + "type": "string", + "examples": [ + "United States", + "Canada", + "United Kingdom" + ] + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/job-types": { + "get": { + "summary": "Get Job Types", + "description": "Retrieve list of available job types for filtering.", + "operationId": "getJobTypes", + "tags": [ + "Jobs" + ], + "responses": { + "200": { + "description": "List of available job types.", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "examples": [ + 1, + 2, + 3 + ] + }, + "name": { + "type": "string", + "examples": [ + "Full Time", + "Part Time", + "Contract" + ] + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/personal-email-finder": { + "post": { + "summary": "Personal Email Finder", + "description": "Find personal email addresses from B2B profile URLs.", + "operationId": "findPersonalEmail", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "profile_url" + ], + "properties": { + "profile_url": { + "type": "string", + "description": "B2B profile URL (for example, a professional social profile)", + "examples": [ + "https://profiles.example.com/williamhgates/" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Personal email search response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "personal_email": { + "type": [ + "string", + "null" + ], + "examples": [ + "bill.gates@gmail.com" + ] + }, + "status": { + "type": "string", + "enum": [ + "found", + "not_found" + ], + "examples": [ + "found" + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + }, + "message": { + "type": "string", + "examples": [ + "Personal email found", + "Personal email not found" + ] + } + }, + "required": [ + "status", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/b2b-social-email": { + "post": { + "summary": "B2B Social to Email", + "description": "Find work email addresses from B2B profile URLs.", + "operationId": "socialToWorkEmail", + "tags": [ + "Email" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "profile_url" + ], + "properties": { + "profile_url": { + "type": "string", + "description": "B2B profile URL (for example, a professional social profile)", + "examples": [ + "https://profiles.example.com/williamhgates/" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Work email search response.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "work_email": { + "type": [ + "string", + "null" + ], + "examples": [ + "bill.gates@microsoft.com" + ] + }, + "status": { + "type": "string", + "enum": [ + "found", + "not_found" + ], + "examples": [ + "found" + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + }, + "message": { + "type": "string", + "examples": [ + "Work email found", + "Work email not found" + ] + } + }, + "required": [ + "status", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/b2b/searchads": { + "post": { + "summary": "B2B Ads Search", + "description": "Search for B2B Ads based on a company's domain or name.", + "operationId": "searchB2BAds", + "tags": [ + "Advertisements" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Provide a company name or domain to search for ads.", + "properties": { + "company_domain": { + "type": "string", + "examples": [ + "microsoft.com" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful retrieval of B2B Ads.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "credits_consumed": { + "type": "number", + "examples": [ + 5 + ] + }, + "ads": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ad_id": { + "type": "string", + "examples": [ + "12345" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "ad_title": { + "type": "string", + "examples": [ + "Microsoft Azure Cloud Services" + ] + }, + "ad_description": { + "type": "string" + }, + "ad_url": { + "type": "string", + "format": "uri" + } + } + } + } + }, + "required": [ + "credits_consumed", + "ads" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + }, + "/b2b/ad-details": { + "post": { + "summary": "B2B Ad Details", + "description": "Get detailed information about a specific B2B ad.", + "operationId": "getB2BAdDetails", + "tags": [ + "Advertisements" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ad_id" + ], + "properties": { + "ad_id": { + "type": "string", + "description": "B2B ad ID", + "examples": [ + "12345" + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Detailed B2B ad information.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ad_id": { + "type": "string", + "examples": [ + "12345" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "ad_title": { + "type": "string", + "examples": [ + "Microsoft Azure Cloud Services" + ] + }, + "ad_description": { + "type": "string" + }, + "ad_url": { + "type": "string", + "format": "uri" + }, + "campaign_info": { + "type": "object", + "properties": { + "campaign_name": { + "type": "string" + }, + "start_date": { + "type": "string", + "format": "date" + }, + "end_date": { + "type": [ + "string", + "null" + ], + "format": "date" + } + } + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 2 + ] + } + }, + "required": [ + "ad_id", + "credits_consumed" + ] + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest" + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests" + }, + "500": { + "$ref": "#/components/responses/InternalServerError" + } + } + } + } + }, + "components": { + "securitySchemes": { + "apiKey": { + "type": "apiKey", + "in": "header", + "name": "X-API-Key", + "description": "API key for authentication. Get your API key from your LeadMagic dashboard." + } + }, + "schemas": { + "Location": { + "type": "object", + "description": "Geographic location information", + "properties": { + "name": { + "type": "string", + "examples": [ + "boston, massachusetts, united states" + ] + }, + "locality": { + "type": "string", + "examples": [ + "boston" + ] + }, + "region": { + "type": "string", + "examples": [ + "massachusetts" + ] + }, + "metro": { + "type": "string", + "examples": [ + "boston, massachusetts" + ] + }, + "country": { + "type": "string", + "examples": [ + "united states" + ] + }, + "continent": { + "type": "string", + "examples": [ + "north america" + ] + }, + "street_address": { + "type": "string", + "examples": [ + "1 Seaport Lane" + ] + }, + "address_line_2": { + "type": [ + "string", + "null" + ] + }, + "postal_code": { + "type": "string", + "examples": [ + "02210" + ] + }, + "geo": { + "type": "string", + "examples": [ + "42.35,-71.06" + ] + } + } + }, + "DetailedCompany": { + "type": "object", + "description": "Detailed company information from company search", + "properties": { + "company_name": { + "type": "string", + "examples": [ + "LeadMagic" + ] + }, + "company_id": { + "type": "integer", + "examples": [ + 75153174 + ] + }, + "locations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "country": { + "type": "string", + "examples": [ + "US" + ] + }, + "city": { + "type": "string", + "examples": [ + "Boston" + ] + }, + "geographic_area": { + "type": "string", + "examples": [ + "Massachusetts" + ] + }, + "postal_code": { + "type": "string", + "examples": [ + "02210" + ] + }, + "line1": { + "type": "string", + "examples": [ + "1 Seaport Ln" + ] + }, + "line2": { + "type": [ + "string", + "null" + ] + }, + "description": { + "type": "string", + "examples": [ + "Headquarters" + ] + }, + "headquarter": { + "type": "boolean" + }, + "localized_name": { + "type": "string", + "examples": [ + "Boston" + ] + }, + "latitude": { + "type": "number", + "examples": [ + 42.36041 + ] + }, + "longitude": { + "type": "number", + "examples": [ + -71.05798 + ] + } + } + } + }, + "employee_count": { + "type": "integer", + "examples": [ + 9 + ] + }, + "specialities": { + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "Sales", + "Marketing", + "ABM", + "RevOps" + ] + ] + }, + "employee_count_range": { + "type": "object", + "properties": { + "start": { + "type": "integer", + "examples": [ + 11 + ] + }, + "end": { + "type": "integer", + "examples": [ + 50 + ] + } + } + }, + "tagline": { + "type": "string", + "examples": [ + "LeadMagic tells you who is interested in your products or services. Engage them and build more pipeline, win more deals" + ] + }, + "follower_count": { + "type": "integer", + "examples": [ + 6096 + ] + }, + "industry": { + "type": "string", + "examples": [ + "Internet" + ] + }, + "description": { + "type": "string", + "examples": [ + "LeadMagic tells you exactly what businesses are on your website and helps you enrich your contact and company data." + ] + }, + "website_url": { + "type": "string", + "examples": [ + "https://leadmagic.io" + ] + }, + "founded_on": { + "type": "object", + "properties": { + "month": { + "type": [ + "integer", + "null" + ] + }, + "year": { + "type": "integer", + "examples": [ + 2022 + ] + }, + "day": { + "type": [ + "integer", + "null" + ] + } + } + }, + "universal_name": { + "type": "string", + "examples": [ + "leadmagichq" + ] + }, + "hashtag": { + "type": "string", + "examples": [ + "#abm" + ] + }, + "industry_v2_taxonomy": { + "type": "string", + "examples": [ + "Internet Publishing" + ] + }, + "url": { + "type": "string", + "examples": [ + "https://profiles.example.com/company/leadmagichq/" + ] + }, + "credits_consumed": { + "type": "integer", + "examples": [ + 1 + ] + } + } + }, + "PersonProfile": { + "type": "object", + "description": "Personal profile information", + "properties": { + "profile_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/williamhgates/" + ] + }, + "first_name": { + "type": "string", + "examples": [ + "Bill" + ] + }, + "last_name": { + "type": "string", + "examples": [ + "Gates" + ] + }, + "full_name": { + "type": "string", + "examples": [ + "Bill Gates" + ] + }, + "public_identifier": { + "type": "string", + "examples": [ + "williamhgates" + ] + }, + "headline": { + "type": "string", + "examples": [ + "Chair, Gates Foundation and Founder, Breakthrough Energy" + ] + }, + "company_name": { + "type": "string", + "examples": [ + "Gates Foundation" + ] + }, + "company_size": { + "type": "string", + "examples": [ + "1001-5000" + ] + }, + "company_industry": { + "type": "string", + "examples": [ + "investment management" + ] + }, + "company_linkedin_url": { + "type": "string", + "examples": [ + "profiles.example.com/company/bill-and-melinda-gates-foundation" + ] + }, + "company_website": { + "type": "string", + "examples": [ + "gatesfoundation.org" + ] + }, + "total_tenure_months": { + "type": "string", + "examples": [ + "305" + ] + }, + "total_tenure_days": { + "type": "string", + "examples": [ + "9150" + ] + }, + "total_tenure_years": { + "type": "string", + "examples": [ + "25.42" + ] + }, + "connections": { + "type": "integer", + "examples": [ + 8 + ] + }, + "followers": { + "type": "integer", + "examples": [ + 37841613 + ] + }, + "country": { + "type": "string", + "examples": [ + "United States" + ] + }, + "location": { + "type": "string", + "examples": [ + "Seattle, Washington, United States" + ] + }, + "about": { + "type": "string", + "examples": [ + "Chair of the Gates Foundation. Founder of Breakthrough Energy. Co-founder of Microsoft. Voracious reader. Avid traveler. Active blogger." + ] + }, + "experiences": { + "type": "array", + "items": { + "type": "object", + "properties": { + "company_id": { + "type": "string", + "examples": [ + "8736" + ] + }, + "title": { + "type": "string", + "examples": [ + "Co-chair" + ] + }, + "subtitle": { + "type": "string", + "examples": [ + "Gates Foundation" + ] + }, + "caption": { + "type": "string", + "examples": [ + "2000 - Present \u00b7 25 yrs 5 mos" + ] + } + } + } + }, + "educations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "examples": [ + "Harvard University" + ] + }, + "caption": { + "type": "string", + "examples": [ + "1973 - 1975" + ] + } + } + } + } + } + }, + "GoogleAd": { + "type": "object", + "description": "Google advertisement information", + "properties": { + "advertiser_id": { + "type": "string", + "examples": [ + "AR14106062795078369281" + ] + }, + "creative_id": { + "type": "string", + "examples": [ + "CR14003695067076755457" + ] + }, + "advertiser_name": { + "type": "string", + "examples": [ + "Gong.io Inc" + ] + }, + "format": { + "type": "string", + "examples": [ + "Text" + ] + }, + "start": { + "type": "string", + "format": "date", + "examples": [ + "2025-03-06" + ] + }, + "last_seen": { + "type": "string", + "format": "date", + "examples": [ + "2025-06-27" + ] + }, + "original_url": { + "type": "string", + "examples": [ + "https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457?region=anywhere" + ] + }, + "variants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "HTML content or JavaScript URL for the ad" + }, + "height": { + "type": [ + "integer", + "null" + ] + }, + "width": { + "type": [ + "integer", + "null" + ] + } + } + } + } + } + }, + "JobResult": { + "type": "object", + "description": "Job search result", + "properties": { + "company": { + "type": "object", + "properties": { + "name": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "website_url": { + "type": "string", + "examples": [ + "https://www.microsoft.com/" + ] + }, + "linkedin_url": { + "type": "string", + "examples": [ + "https://profiles.example.com/company/microsoft/" + ] + }, + "twitter_handle": { + "type": "string", + "examples": [ + "Microsoft" + ] + }, + "github_url": { + "type": "string", + "examples": [ + "https://github.com/microsoft" + ] + }, + "is_agency": { + "type": "boolean", + "examples": [ + false + ] + } + } + }, + "title": { + "type": "string", + "examples": [ + "Technical Program Manager - Developer (AI)" + ] + }, + "location": { + "type": "string", + "examples": [ + "Redmond, Washington, United States" + ] + }, + "types": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "examples": [ + 1 + ] + }, + "name": { + "type": "string", + "examples": [ + "Full Time" + ] + } + } + } + }, + "cities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "geonameid": { + "type": "integer", + "examples": [ + 5808079 + ] + }, + "asciiname": { + "type": "string", + "examples": [ + "Redmond" + ] + }, + "name": { + "type": "string", + "examples": [ + "Redmond" + ] + }, + "country": { + "type": "object", + "properties": { + "id": { + "type": "integer", + "examples": [ + 238 + ] + }, + "code": { + "type": "string", + "examples": [ + "US" + ] + }, + "name": { + "type": "string", + "examples": [ + "United States" + ] + } + } + } + } + } + }, + "has_remote": { + "type": "boolean", + "examples": [ + false + ] + }, + "published": { + "type": "string", + "format": "date-time", + "examples": [ + "2025-06-25T20:36:00Z" + ] + }, + "expired": { + "type": [ + "string", + "null" + ], + "format": "date-time" + }, + "application_url": { + "type": "string", + "examples": [ + "https://jobs.careers.microsoft.com/global/en/job/1833754/" + ] + }, + "language": { + "type": "string", + "examples": [ + "en" + ] + }, + "salary_min": { + "type": "string", + "examples": [ + "100600" + ] + }, + "salary_max": { + "type": "string", + "examples": [ + "215400" + ] + }, + "salary_currency": { + "type": "string", + "examples": [ + "USD" + ] + }, + "experience_level": { + "type": "string", + "examples": [ + "Mid Level" + ] + }, + "description": { + "type": "string", + "description": "Full job description text" + } + } + }, + "Error": { + "type": "object", + "properties": { + "error": { + "type": "string", + "examples": [ + "Bad Request" + ] + }, + "message": { + "type": "string", + "examples": [ + "API key is missing or invalid." + ] + } + } + } + }, + "responses": { + "BadRequest": { + "description": "Bad Request. The request payload was malformed or failed validation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "Unauthorized": { + "description": "Unauthorized. The `X-API-Key` header is missing, invalid, or the key has been revoked.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "TooManyRequests": { + "description": "Too Many Requests. The rate limit for your API key has been exceeded. Back off and retry with exponential jitter.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "InternalServerError": { + "description": "Internal Server Error. An unexpected error occurred while processing the request. Retry with exponential backoff; if the problem persists, contact support@leadmagic.io with the correlation id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } } diff --git a/leadmagic-openapi-3.1.yaml b/leadmagic-openapi-3.1.yaml index b26f4fb..943a65e 100644 --- a/leadmagic-openapi-3.1.yaml +++ b/leadmagic-openapi-3.1.yaml @@ -2,16 +2,13 @@ openapi: 3.1.0 jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema info: title: LeadMagic API - version: 1.5.0 - description: 'A clean, consistent, and well-documented API to access LeadMagic''s - services, including email finding, validation, company and professional profile - enrichment, and advertisement searching. - - - **Important**: Current public docs are not fully uniform on field naming. Some - endpoints use snake_case while others show mixed or camelCase response fields. + summary: Complete API for LeadMagic data enrichment services + description: |- + Official OpenAPI 3.1 snapshot for the LeadMagic B2B data API: email finding and validation, contact and company enrichment, profile and job enrichment, advertisement search, and credit management. - ' + Authenticate every request with the `X-API-Key` header. Keys are issued from https://app.leadmagic.io. Rate limits, credit costs, and MCP sign-in are documented in the repository README. + version: 1.5.0 + termsOfService: https://leadmagic.io/terms contact: name: LeadMagic API Support url: https://leadmagic.io @@ -19,506 +16,31 @@ info: license: name: MIT url: https://opensource.org/licenses/MIT - summary: Complete API for LeadMagic data enrichment services servers: -- url: https://api.leadmagic.io - description: Production API Server -components: - securitySchemes: - apiKey: - type: apiKey - in: header - name: X-API-Key - description: API key for authentication. Get your API key from your LeadMagic - dashboard. - schemas: - Location: - type: object - description: Geographic location information - properties: - name: - type: string - examples: - - boston, massachusetts, united states - locality: - type: string - examples: - - boston - region: - type: string - examples: - - massachusetts - metro: - type: string - examples: - - boston, massachusetts - country: - type: string - examples: - - united states - continent: - type: string - examples: - - north america - street_address: - type: string - examples: - - 1 Seaport Lane - address_line_2: - type: - - string - - 'null' - postal_code: - type: string - examples: - - '02210' - geo: - type: string - examples: - - 42.35,-71.06 - DetailedCompany: - type: object - description: Detailed company information from company search - properties: - company_name: - type: string - examples: - - LeadMagic - company_id: - type: integer - examples: - - 75153174 - locations: - type: array - items: - type: object - properties: - country: - type: string - examples: - - US - city: - type: string - examples: - - Boston - geographic_area: - type: string - examples: - - Massachusetts - postal_code: - type: string - examples: - - '02210' - line1: - type: string - examples: - - 1 Seaport Ln - line2: - type: - - string - - 'null' - description: - type: string - examples: - - Headquarters - headquarter: - type: boolean - localized_name: - type: string - examples: - - Boston - latitude: - type: number - examples: - - 42.36041 - longitude: - type: number - examples: - - -71.05798 - employee_count: - type: integer - examples: - - 9 - specialities: - type: array - items: - type: string - examples: - - - Sales - - Marketing - - ABM - - RevOps - employee_count_range: - type: object - properties: - start: - type: integer - examples: - - 11 - end: - type: integer - examples: - - 50 - tagline: - type: string - examples: - - LeadMagic tells you who is interested in your products or services. Engage - them and build more pipeline, win more deals - follower_count: - type: integer - examples: - - 6096 - industry: - type: string - examples: - - Internet - description: - type: string - examples: - - LeadMagic tells you exactly what businesses are on your website and helps - you enrich your contact and company data. - website_url: - type: string - examples: - - https://leadmagic.io - founded_on: - type: object - properties: - month: - type: - - integer - - 'null' - year: - type: integer - examples: - - 2022 - day: - type: - - integer - - 'null' - universal_name: - type: string - examples: - - leadmagichq - hashtag: - type: string - examples: - - '#abm' - industry_v2_taxonomy: - type: string - examples: - - Internet Publishing - url: - type: string - examples: - - https://profiles.example.com/company/leadmagichq/ - credits_consumed: - type: integer - examples: - - 1 - PersonProfile: - type: object - description: Personal profile information - properties: - profile_url: - type: string - examples: - - https://profiles.example.com/williamhgates/ - first_name: - type: string - examples: - - Bill - last_name: - type: string - examples: - - Gates - full_name: - type: string - examples: - - Bill Gates - public_identifier: - type: string - examples: - - williamhgates - headline: - type: string - examples: - - Chair, Gates Foundation and Founder, Breakthrough Energy - company_name: - type: string - examples: - - Gates Foundation - company_size: - type: string - examples: - - 1001-5000 - company_industry: - type: string - examples: - - investment management - company_linkedin_url: - type: string - examples: - - profiles.example.com/company/bill-and-melinda-gates-foundation - company_website: - type: string - examples: - - gatesfoundation.org - total_tenure_months: - type: string - examples: - - '305' - total_tenure_days: - type: string - examples: - - '9150' - total_tenure_years: - type: string - examples: - - '25.42' - connections: - type: integer - examples: - - 8 - followers: - type: integer - examples: - - 37841613 - country: - type: string - examples: - - United States - location: - type: string - examples: - - Seattle, Washington, United States - about: - type: string - examples: - - Chair of the Gates Foundation. Founder of Breakthrough Energy. Co-founder - of Microsoft. Voracious reader. Avid traveler. Active blogger. - experiences: - type: array - items: - type: object - properties: - company_id: - type: string - examples: - - '8736' - title: - type: string - examples: - - Co-chair - subtitle: - type: string - examples: - - Gates Foundation - caption: - type: string - examples: - - "2000 - Present \xB7 25 yrs 5 mos" - educations: - type: array - items: - type: object - properties: - title: - type: string - examples: - - Harvard University - caption: - type: string - examples: - - 1973 - 1975 - GoogleAd: - type: object - description: Google advertisement information - properties: - advertiser_id: - type: string - examples: - - AR14106062795078369281 - creative_id: - type: string - examples: - - CR14003695067076755457 - advertiser_name: - type: string - examples: - - Gong.io Inc - format: - type: string - examples: - - Text - start: - type: string - format: date - examples: - - '2025-03-06' - last_seen: - type: string - format: date - examples: - - '2025-06-27' - original_url: - type: string - examples: - - https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457?region=anywhere - variants: - type: array - items: - type: object - properties: - content: - type: string - description: HTML content or JavaScript URL for the ad - height: - type: - - integer - - 'null' - width: - type: - - integer - - 'null' - JobResult: - type: object - description: Job search result - properties: - company: - type: object - properties: - name: - type: string - examples: - - Microsoft - website_url: - type: string - examples: - - https://www.microsoft.com/ - linkedin_url: - type: string - examples: - - https://profiles.example.com/company/microsoft/ - twitter_handle: - type: string - examples: - - Microsoft - github_url: - type: string - examples: - - https://github.com/microsoft - is_agency: - type: boolean - examples: - - false - title: - type: string - examples: - - Technical Program Manager - Developer (AI) - location: - type: string - examples: - - Redmond, Washington, United States - types: - type: array - items: - type: object - properties: - id: - type: integer - examples: - - 1 - name: - type: string - examples: - - Full Time - cities: - type: array - items: - type: object - properties: - geonameid: - type: integer - examples: - - 5808079 - asciiname: - type: string - examples: - - Redmond - name: - type: string - examples: - - Redmond - country: - type: object - properties: - id: - type: integer - examples: - - 238 - code: - type: string - examples: - - US - name: - type: string - examples: - - United States - has_remote: - type: boolean - examples: - - false - published: - type: string - format: date-time - examples: - - '2025-06-25T20:36:00Z' - expired: - type: - - string - - 'null' - format: date-time - application_url: - type: string - examples: - - https://jobs.careers.microsoft.com/global/en/job/1833754/ - language: - type: string - examples: - - en - salary_min: - type: string - examples: - - '100600' - salary_max: - type: string - examples: - - '215400' - salary_currency: - type: string - examples: - - USD - experience_level: - type: string - examples: - - Mid Level - description: - type: string - description: Full job description text - Error: - type: object - properties: - error: - type: string - examples: - - Bad Request - message: - type: string - examples: - - API key is missing or invalid. + - url: https://api.leadmagic.io + description: Production API Server +externalDocs: + description: LeadMagic documentation + url: https://leadmagic.io/docs security: -- apiKey: [] + - apiKey: [] +tags: + - name: Advertisements + description: Advertisement intelligence + - name: Companies + description: Company information and enrichment + - name: Credits + description: Credit management operations + - name: Email + description: Email finding and validation + - name: Jobs + description: Job posting search + - name: Mobile + description: Mobile number finding + - name: People + description: People enrichment and search + - name: Profiles + description: Professional profile enrichment paths: /credits: post: @@ -526,7 +48,7 @@ paths: description: Check the number of available credits for the authenticated user. operationId: getCredits tags: - - Credits + - Credits requestBody: required: false content: @@ -535,7 +57,7 @@ paths: type: object properties: {} responses: - '200': + "200": description: Successful credits retrieval. content: application/json: @@ -546,58 +68,53 @@ paths: type: number description: Available credits balance examples: - - 7333.8 + - 7333.8 is_frozen: type: boolean description: Whether the account's credits are currently frozen. examples: - - false + - false credits_frozen: type: number description: Portion of credits currently frozen. examples: - - 0 + - 0 credits_liquid: type: number description: Portion of credits currently available for use. examples: - - 7333.8 + - 7333.8 credit_freeze_message: type: - - string - - 'null' + - string + - "null" description: Optional message describing the freeze state. examples: - - null + - null credit_freeze_plan_hint: type: - - string - - 'null' + - string + - "null" description: Optional plan or upgrade hint related to a credit freeze. examples: - - null + - null required: - - credits - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - credits + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /email-validate: post: summary: Email Validation - description: Validate an email address for deliverability and retrieve associated - company information. + description: Validate an email address for deliverability and retrieve associated company information. operationId: validateEmail tags: - - Email + - Email requestBody: required: true content: @@ -605,25 +122,25 @@ paths: schema: type: object required: - - email + - email properties: email: type: string description: Email address to validate. examples: - - jesse@leadmagic.io + - jesse@leadmagic.io first_name: type: string description: First name of the person (optional). examples: - - Jesse + - Jesse last_name: type: string description: Last name of the person (optional). examples: - - Ouellette + - Ouellette responses: - '200': + "200": description: Successful validation. content: application/json: @@ -633,102 +150,98 @@ paths: email: type: string examples: - - jesse@leadmagic.io + - jesse@leadmagic.io email_status: type: string enum: - - valid - - valid_catch_all - - invalid - - unknown - - catch_all + - valid + - valid_catch_all + - invalid + - unknown + - catch_all examples: - - valid + - valid credits_consumed: type: number examples: - - 0.05 + - 0.05 message: type: string examples: - - Email is valid. + - Email is valid. is_domain_catch_all: type: boolean examples: - - false + - false mx_record: type: string examples: - - aspmx.l.google.com + - aspmx.l.google.com mx_provider: type: string examples: - - Google Workspace + - Google Workspace mx_security_gateway: type: boolean examples: - - false + - false company_name: type: string examples: - - Leadmagic + - Leadmagic company_industry: type: string examples: - - Internet + - Internet company_size: type: string examples: - - 11-50 + - 11-50 company_founded: type: integer examples: - - 2022 + - 2022 company_type: type: string examples: - - private + - private company_linkedin_url: type: string examples: - - profiles.example.com/company/leadmagichq + - profiles.example.com/company/leadmagichq company_linkedin_id: type: string examples: - - '75153174' + - "75153174" company_facebook_url: type: - - string - - 'null' + - string + - "null" company_twitter_url: type: - - string - - 'null' + - string + - "null" company_location: - $ref: '#/components/schemas/Location' + $ref: "#/components/schemas/Location" required: - - email - - email_status - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - email + - email_status + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /email-finder: post: summary: Email Finder description: Finds a verified email address based on a person's name and company. operationId: findEmail tags: - - Email + - Email requestBody: required: true content: @@ -736,31 +249,31 @@ paths: schema: type: object required: - - first_name - - last_name + - first_name + - last_name properties: first_name: type: string description: The person's first name. examples: - - Bill + - Bill last_name: type: string description: The person's last name. examples: - - Gates + - Gates domain: type: string description: The company's domain name. examples: - - microsoft.com + - microsoft.com company_name: type: string description: The company's name (used if domain is unknown). examples: - - Microsoft + - Microsoft responses: - '200': + "200": description: Successful email discovery. content: application/json: @@ -770,113 +283,110 @@ paths: email: type: string examples: - - billg@microsoft.com + - billg@microsoft.com status: type: string enum: - - valid - - valid_catch_all - - not_found + - valid + - valid_catch_all + - not_found examples: - - valid + - valid credits_consumed: type: integer examples: - - 1 + - 1 message: type: string examples: - - Valid email found. + - Valid email found. first_name: type: string examples: - - Bill + - Bill last_name: type: string examples: - - Gates + - Gates domain: type: string examples: - - microsoft.com + - microsoft.com is_domain_catch_all: type: boolean examples: - - false + - false mx_record: type: string examples: - - microsoft-com.mail.protection.outlook.com + - microsoft-com.mail.protection.outlook.com mx_provider: type: string examples: - - Microsoft 365 + - Microsoft 365 mx_security_gateway: type: boolean examples: - - false + - false company_name: type: string examples: - - Microsoft + - Microsoft company_industry: type: string examples: - - Computer Software + - Computer Software company_size: type: string examples: - - 10001+ + - 10001+ company_founded: type: integer examples: - - 1975 + - 1975 company_type: type: string examples: - - public + - public company_linkedin_url: type: string examples: - - profiles.example.com/company/microsoft + - profiles.example.com/company/microsoft company_linkedin_id: type: string examples: - - '1035' + - "1035" company_facebook_url: type: string examples: - - facebook.com/microsoft + - facebook.com/microsoft company_twitter_url: type: string examples: - - twitter.com/microsoft + - twitter.com/microsoft company_location: - $ref: '#/components/schemas/Location' + $ref: "#/components/schemas/Location" required: - - email - - status - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - email + - status + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /profile-search: post: summary: Profile Search - description: "Provide a B2B profile URL (for example, a professional social profile) to get full profile\ - \ details. \nRate limit: 300 requests/minute.\n" + description: | + Provide a B2B profile URL (for example, a professional social profile) to get full profile details. + Rate limit: 300 requests/minute. operationId: searchProfile tags: - - Profiles + - Profiles requestBody: required: true content: @@ -884,15 +394,15 @@ paths: schema: type: object required: - - profile_url + - profile_url properties: profile_url: type: string description: Full URL of the B2B profile. examples: - - https://profiles.example.com/williamhgates/ + - https://profiles.example.com/williamhgates/ responses: - '200': + "200": description: Successful retrieval of profile information. content: application/json: @@ -902,36 +412,26 @@ paths: credits_consumed: type: number examples: - - 1 + - 1 required: - - credits_consumed + - credits_consumed allOf: - - $ref: '#/components/schemas/PersonProfile' - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '429': - description: Rate limit exceeded. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - $ref: "#/components/schemas/PersonProfile" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /company-search: post: summary: Company Search description: Search for company details using its domain, name, or profile URL. operationId: searchCompany tags: - - Companies + - Companies requestBody: required: true content: @@ -943,17 +443,17 @@ paths: company_domain: type: string examples: - - leadmagic.io + - leadmagic.io company_name: type: string examples: - - Leadmagic + - Leadmagic profile_url: type: string examples: - - https://profiles.example.com/company/leadmagichq + - https://profiles.example.com/company/leadmagichq responses: - '200': + "200": description: Successful retrieval of company details. content: application/json: @@ -963,30 +463,26 @@ paths: credits_consumed: type: integer examples: - - 1 + - 1 required: - - credits_consumed + - credits_consumed allOf: - - $ref: '#/components/schemas/DetailedCompany' - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - $ref: "#/components/schemas/DetailedCompany" + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /jobs-finder: post: summary: Jobs Finder description: Searches for job postings based on various criteria. operationId: findJobs tags: - - Jobs + - Jobs requestBody: required: true content: @@ -998,48 +494,48 @@ paths: type: string description: Filter by company name. examples: - - Microsoft + - Microsoft company_website: type: string description: Filter by company website. examples: - - microsoft.com + - microsoft.com job_title: type: string description: Filter by job title. examples: - - Developer + - Developer location: type: string description: Filter by job location. examples: - - New York + - New York experience_level: type: string description: Required experience level. enum: - - entry - - mid - - senior - - executive + - entry + - mid + - senior + - executive examples: - - senior + - senior job_description: type: string description: Keywords from the job description. examples: - - python "software engineer" + - python "software engineer" country_id: type: string description: Filter jobs by country ID. examples: - - US + - US page: type: integer default: 1 minimum: 1 examples: - - 1 + - 1 per_page: type: integer default: 20 @@ -1047,9 +543,9 @@ paths: maximum: 50 description: Number of results per page. Maximum of 50. examples: - - 5 + - 5 responses: - '200': + "200": description: Successful job search. content: application/json: @@ -1059,53 +555,49 @@ paths: total_count: type: integer examples: - - 105 + - 105 page: type: integer examples: - - 1 + - 1 per_page: type: integer examples: - - 5 + - 5 total_pages: type: integer examples: - - 21 + - 21 credits_consumed: type: integer examples: - - 5 + - 5 results: type: array items: - $ref: '#/components/schemas/JobResult' + $ref: "#/components/schemas/JobResult" required: - - total_count - - page - - per_page - - total_pages - - credits_consumed - - results - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - total_count + - page + - per_page + - total_pages + - credits_consumed + - results + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /google/searchads: post: summary: Google Ads Search description: Search for Google Ads based on a company's domain or name. operationId: searchGoogleAds tags: - - Advertisements + - Advertisements requestBody: required: true content: @@ -1117,13 +609,13 @@ paths: company_domain: type: string examples: - - gong.io + - gong.io company_name: type: string examples: - - gong + - gong responses: - '200': + "200": description: Successful retrieval of Google Ads. content: application/json: @@ -1133,33 +625,29 @@ paths: credits_consumed: type: number examples: - - 8 + - 8 ads: type: array items: - $ref: '#/components/schemas/GoogleAd' + $ref: "#/components/schemas/GoogleAd" required: - - credits_consumed - - ads - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - credits_consumed + - ads + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /meta/searchads: post: summary: Meta (Facebook/Instagram) Ads Search description: Search for Meta Ads based on a company's domain or name. operationId: searchMetaAds tags: - - Advertisements + - Advertisements requestBody: required: true content: @@ -1171,13 +659,13 @@ paths: company_domain: type: string examples: - - gong.io + - gong.io company_name: type: string examples: - - gong + - gong responses: - '200': + "200": description: Successful retrieval of Meta Ads. content: application/json: @@ -1187,7 +675,7 @@ paths: credits_consumed: type: number examples: - - 2.6 + - 2.6 ads: type: array items: @@ -1196,15 +684,15 @@ paths: ad_archive_id: type: string examples: - - '618153827656899' + - "618153827656899" page_id: type: string examples: - - '105549201674375' + - "105549201674375" page_name: type: string examples: - - Lykkedal Retreat + - Lykkedal Retreat is_active: type: boolean publisher_platform: @@ -1212,8 +700,8 @@ paths: items: type: string examples: - - - facebook - - instagram + - - facebook + - instagram snapshot: type: object properties: @@ -1243,28 +731,23 @@ paths: type: string format: uri required: - - credits_consumed - - ads - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - credits_consumed + - ads + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /mobile-finder: post: summary: Mobile Finder - description: Find mobile phone numbers using profile URL, work email, or personal - email. + description: Find mobile phone numbers using profile URL, work email, or personal email. operationId: findMobile tags: - - Mobile + - Mobile requestBody: required: true content: @@ -1276,17 +759,17 @@ paths: profile_url: type: string examples: - - https://profiles.example.com/williamhgates/ + - https://profiles.example.com/williamhgates/ work_email: type: string examples: - - jesse@leadmagic.io + - jesse@leadmagic.io personal_email: type: string examples: - - jesse.ouellette@gmail.com + - jesse.ouellette@gmail.com responses: - '200': + "200": description: Mobile search response. content: application/json: @@ -1296,41 +779,37 @@ paths: message: type: string examples: - - mobile not found - - Mobile found + - mobile not found + - Mobile found credits_consumed: type: number examples: - - 0 - - 1 + - 0 + - 1 mobile_number: type: - - string - - 'null' + - string + - "null" examples: - - '+1234567890' + - "+1234567890" required: - - message - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - message + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /b2b-profile: post: summary: Email Address to B2B Profile description: Find B2B profile URL using work email address. operationId: emailToProfile tags: - - Profiles + - Profiles requestBody: required: true content: @@ -1338,14 +817,14 @@ paths: schema: type: object required: - - work_email + - work_email properties: work_email: type: string examples: - - jesse@leadmagic.io + - jesse@leadmagic.io responses: - '200': + "200": description: Profile URL found. content: application/json: @@ -1355,37 +834,33 @@ paths: profile_url: type: string examples: - - https://profiles.example.com/jesseouehwx + - https://profiles.example.com/jesseouehwx message: type: string examples: - - Profile URL found + - Profile URL found credits_consumed: type: integer examples: - - 10 + - 10 required: - - message - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - message + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /role-finder: post: summary: Role Finder description: Find specific roles/positions within a company. operationId: findRole tags: - - People + - People requestBody: required: true content: @@ -1393,26 +868,26 @@ paths: schema: type: object required: - - job_title + - job_title properties: job_title: type: string examples: - - Developer + - Developer company_name: type: string examples: - - Microsoft + - Microsoft company_domain: type: string examples: - - microsoft.com + - microsoft.com company_profile_url: type: string examples: - - https://profiles.example.com/company/microsoft + - https://profiles.example.com/company/microsoft responses: - '200': + "200": description: Role search response. content: application/json: @@ -1422,43 +897,39 @@ paths: message: type: string examples: - - Role not found. - - Role found. + - Role not found. + - Role found. credits_consumed: type: integer examples: - - 0 - - 1 + - 0 + - 1 company_name: type: string examples: - - Microsoft + - Microsoft company_website: type: string examples: - - microsoft.com + - microsoft.com required: - - message - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - message + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /employee-finder: post: summary: Employee Finder description: Find employees of a specific company. operationId: findEmployees tags: - - People + - People requestBody: required: true content: @@ -1466,27 +937,27 @@ paths: schema: type: object required: - - company_name + - company_name properties: company_name: type: string examples: - - Microsoft + - Microsoft page: type: integer default: 1 minimum: 1 examples: - - 1 + - 1 per_page: type: integer default: 20 minimum: 1 maximum: 50 examples: - - 5 + - 5 responses: - '200': + "200": description: Employee search results. content: application/json: @@ -1496,19 +967,19 @@ paths: message: type: string examples: - - Data found for the given company. + - Data found for the given company. total_count: type: integer examples: - - 5000 + - 5000 returned_count: type: integer examples: - - 20 + - 20 credits_consumed: type: integer examples: - - 1 + - 1 data: type: array items: @@ -1517,46 +988,41 @@ paths: first_name: type: string examples: - - John + - John last_name: type: string examples: - - Doe + - Doe title: type: string examples: - - Senior Software Engineer + - Senior Software Engineer website: type: string examples: - - http://www.microsoft.com + - http://www.microsoft.com company_name: type: string examples: - - Microsoft + - Microsoft required: - - message - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - message + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /company-funding: post: summary: Company Funding - description: Get comprehensive funding information, financials, competitors, - and company insights. + description: Get comprehensive funding information, financials, competitors, and company insights. operationId: getCompanyFunding tags: - - Companies + - Companies requestBody: required: true content: @@ -1567,13 +1033,13 @@ paths: company_domain: type: string examples: - - microsoft.com + - microsoft.com company_name: type: string examples: - - Microsoft + - Microsoft responses: - '200': + "200": description: Comprehensive company funding and business information. content: application/json: @@ -1586,67 +1052,67 @@ paths: companyName: type: string examples: - - Microsoft Corp. + - Microsoft Corp. description: type: string shortName: type: string examples: - - Microsoft + - Microsoft founded: type: string examples: - - '1975' + - "1975" primaryDomain: type: string examples: - - microsoft.com + - microsoft.com phone: type: string examples: - - 1-124-415-8000 + - 1-124-415-8000 status: type: string examples: - - NEW + - NEW followers: type: integer examples: - - 181691 + - 181691 ownership: type: string examples: - - Public + - Public financialInfo: type: object properties: revenue: type: integer examples: - - 270010000000 + - 270010000000 formattedRevenue: type: string examples: - - 270B + - 270B totalFunding: type: integer examples: - - 61000000 + - 61000000 formattedFunding: type: string examples: - - 61M + - 61M companySize: type: object properties: employees: type: integer examples: - - 221000 + - 221000 employeeRange: type: string examples: - - 100,000 - 9,999,999 + - 100,000 - 9,999,999 topCompetitors: type: array items: @@ -1655,46 +1121,42 @@ paths: name: type: string examples: - - IBM + - IBM revenue: type: string examples: - - '' + - "" employees: type: string examples: - - 311,300 + - 311,300 website: type: string examples: - - https://www.ibm.com + - https://www.ibm.com credits_consumed: type: integer examples: - - 4 + - 4 required: - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /job-country: get: summary: Get Job Countries description: Retrieve list of available countries for job filtering. operationId: getJobCountries tags: - - Jobs + - Jobs responses: - '200': + "200": description: List of available countries. content: application/json: @@ -1706,30 +1168,30 @@ paths: id: type: string examples: - - US - - CA - - UK + - US + - CA + - UK name: type: string examples: - - United States - - Canada - - United Kingdom - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - United States + - Canada + - United Kingdom + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /job-types: get: summary: Get Job Types description: Retrieve list of available job types for filtering. operationId: getJobTypes tags: - - Jobs + - Jobs responses: - '200': + "200": description: List of available job types. content: application/json: @@ -1741,28 +1203,28 @@ paths: id: type: integer examples: - - 1 - - 2 - - 3 + - 1 + - 2 + - 3 name: type: string examples: - - Full Time - - Part Time - - Contract - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - Full Time + - Part Time + - Contract + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /personal-email-finder: post: summary: Personal Email Finder description: Find personal email addresses from B2B profile URLs. operationId: findPersonalEmail tags: - - Email + - Email requestBody: required: true content: @@ -1770,15 +1232,15 @@ paths: schema: type: object required: - - profile_url + - profile_url properties: profile_url: type: string description: B2B profile URL (for example, a professional social profile) examples: - - https://profiles.example.com/williamhgates/ + - https://profiles.example.com/williamhgates/ responses: - '200': + "200": description: Personal email search response. content: application/json: @@ -1787,48 +1249,44 @@ paths: properties: personal_email: type: - - string - - 'null' + - string + - "null" examples: - - bill.gates@gmail.com + - bill.gates@gmail.com status: type: string enum: - - found - - not_found + - found + - not_found examples: - - found + - found credits_consumed: type: integer examples: - - 1 + - 1 message: type: string examples: - - Personal email found - - Personal email not found + - Personal email found + - Personal email not found required: - - status - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - status + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /b2b-social-email: post: summary: B2B Social to Email description: Find work email addresses from B2B profile URLs. operationId: socialToWorkEmail tags: - - Email + - Email requestBody: required: true content: @@ -1836,15 +1294,15 @@ paths: schema: type: object required: - - profile_url + - profile_url properties: profile_url: type: string description: B2B profile URL (for example, a professional social profile) examples: - - https://profiles.example.com/williamhgates/ + - https://profiles.example.com/williamhgates/ responses: - '200': + "200": description: Work email search response. content: application/json: @@ -1853,48 +1311,44 @@ paths: properties: work_email: type: - - string - - 'null' + - string + - "null" examples: - - bill.gates@microsoft.com + - bill.gates@microsoft.com status: type: string enum: - - found - - not_found + - found + - not_found examples: - - found + - found credits_consumed: type: integer examples: - - 1 + - 1 message: type: string examples: - - Work email found - - Work email not found + - Work email found + - Work email not found required: - - status - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - status + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /b2b/searchads: post: summary: B2B Ads Search description: Search for B2B Ads based on a company's domain or name. operationId: searchB2BAds tags: - - Advertisements + - Advertisements requestBody: required: true content: @@ -1906,13 +1360,13 @@ paths: company_domain: type: string examples: - - microsoft.com + - microsoft.com company_name: type: string examples: - - Microsoft + - Microsoft responses: - '200': + "200": description: Successful retrieval of B2B Ads. content: application/json: @@ -1922,7 +1376,7 @@ paths: credits_consumed: type: number examples: - - 5 + - 5 ads: type: array items: @@ -1931,42 +1385,38 @@ paths: ad_id: type: string examples: - - '12345' + - "12345" company_name: type: string examples: - - Microsoft + - Microsoft ad_title: type: string examples: - - Microsoft Azure Cloud Services + - Microsoft Azure Cloud Services ad_description: type: string ad_url: type: string format: uri required: - - credits_consumed - - ads - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + - credits_consumed + - ads + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" /b2b/ad-details: post: summary: B2B Ad Details description: Get detailed information about a specific B2B ad. operationId: getB2BAdDetails tags: - - Advertisements + - Advertisements requestBody: required: true content: @@ -1974,15 +1424,15 @@ paths: schema: type: object required: - - ad_id + - ad_id properties: ad_id: type: string description: B2B ad ID examples: - - '12345' + - "12345" responses: - '200': + "200": description: Detailed B2B ad information. content: application/json: @@ -1992,15 +1442,15 @@ paths: ad_id: type: string examples: - - '12345' + - "12345" company_name: type: string examples: - - Microsoft + - Microsoft ad_title: type: string examples: - - Microsoft Azure Cloud Services + - Microsoft Azure Cloud Services ad_description: type: string ad_url: @@ -2016,42 +1466,536 @@ paths: format: date end_date: type: - - string - - 'null' + - string + - "null" format: date credits_consumed: type: integer examples: - - 2 + - 2 required: - - ad_id - - credits_consumed - '400': - description: Bad Request. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '401': - description: Unauthorized - Invalid API key. - content: - application/json: - schema: - $ref: '#/components/schemas/Error' -tags: -- name: Advertisements - description: Advertisement intelligence -- name: Companies - description: Company information and enrichment -- name: Credits - description: Credit management operations -- name: Email - description: Email finding and validation -- name: Jobs - description: Job posting search -- name: Mobile - description: Mobile number finding -- name: People - description: People enrichment and search -- name: Profiles - description: Professional profile enrichment + - ad_id + - credits_consumed + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthorized" + "429": + $ref: "#/components/responses/TooManyRequests" + "500": + $ref: "#/components/responses/InternalServerError" +components: + securitySchemes: + apiKey: + type: apiKey + in: header + name: X-API-Key + description: API key for authentication. Get your API key from your LeadMagic dashboard. + schemas: + Location: + type: object + description: Geographic location information + properties: + name: + type: string + examples: + - boston, massachusetts, united states + locality: + type: string + examples: + - boston + region: + type: string + examples: + - massachusetts + metro: + type: string + examples: + - boston, massachusetts + country: + type: string + examples: + - united states + continent: + type: string + examples: + - north america + street_address: + type: string + examples: + - 1 Seaport Lane + address_line_2: + type: + - string + - "null" + postal_code: + type: string + examples: + - "02210" + geo: + type: string + examples: + - 42.35,-71.06 + DetailedCompany: + type: object + description: Detailed company information from company search + properties: + company_name: + type: string + examples: + - LeadMagic + company_id: + type: integer + examples: + - 75153174 + locations: + type: array + items: + type: object + properties: + country: + type: string + examples: + - US + city: + type: string + examples: + - Boston + geographic_area: + type: string + examples: + - Massachusetts + postal_code: + type: string + examples: + - "02210" + line1: + type: string + examples: + - 1 Seaport Ln + line2: + type: + - string + - "null" + description: + type: string + examples: + - Headquarters + headquarter: + type: boolean + localized_name: + type: string + examples: + - Boston + latitude: + type: number + examples: + - 42.36041 + longitude: + type: number + examples: + - -71.05798 + employee_count: + type: integer + examples: + - 9 + specialities: + type: array + items: + type: string + examples: + - - Sales + - Marketing + - ABM + - RevOps + employee_count_range: + type: object + properties: + start: + type: integer + examples: + - 11 + end: + type: integer + examples: + - 50 + tagline: + type: string + examples: + - LeadMagic tells you who is interested in your products or services. Engage them and build more pipeline, win more deals + follower_count: + type: integer + examples: + - 6096 + industry: + type: string + examples: + - Internet + description: + type: string + examples: + - LeadMagic tells you exactly what businesses are on your website and helps you enrich your contact and company data. + website_url: + type: string + examples: + - https://leadmagic.io + founded_on: + type: object + properties: + month: + type: + - integer + - "null" + year: + type: integer + examples: + - 2022 + day: + type: + - integer + - "null" + universal_name: + type: string + examples: + - leadmagichq + hashtag: + type: string + examples: + - "#abm" + industry_v2_taxonomy: + type: string + examples: + - Internet Publishing + url: + type: string + examples: + - https://profiles.example.com/company/leadmagichq/ + credits_consumed: + type: integer + examples: + - 1 + PersonProfile: + type: object + description: Personal profile information + properties: + profile_url: + type: string + examples: + - https://profiles.example.com/williamhgates/ + first_name: + type: string + examples: + - Bill + last_name: + type: string + examples: + - Gates + full_name: + type: string + examples: + - Bill Gates + public_identifier: + type: string + examples: + - williamhgates + headline: + type: string + examples: + - Chair, Gates Foundation and Founder, Breakthrough Energy + company_name: + type: string + examples: + - Gates Foundation + company_size: + type: string + examples: + - 1001-5000 + company_industry: + type: string + examples: + - investment management + company_linkedin_url: + type: string + examples: + - profiles.example.com/company/bill-and-melinda-gates-foundation + company_website: + type: string + examples: + - gatesfoundation.org + total_tenure_months: + type: string + examples: + - "305" + total_tenure_days: + type: string + examples: + - "9150" + total_tenure_years: + type: string + examples: + - "25.42" + connections: + type: integer + examples: + - 8 + followers: + type: integer + examples: + - 37841613 + country: + type: string + examples: + - United States + location: + type: string + examples: + - Seattle, Washington, United States + about: + type: string + examples: + - Chair of the Gates Foundation. Founder of Breakthrough Energy. Co-founder of Microsoft. Voracious reader. Avid traveler. Active blogger. + experiences: + type: array + items: + type: object + properties: + company_id: + type: string + examples: + - "8736" + title: + type: string + examples: + - Co-chair + subtitle: + type: string + examples: + - Gates Foundation + caption: + type: string + examples: + - 2000 - Present · 25 yrs 5 mos + educations: + type: array + items: + type: object + properties: + title: + type: string + examples: + - Harvard University + caption: + type: string + examples: + - 1973 - 1975 + GoogleAd: + type: object + description: Google advertisement information + properties: + advertiser_id: + type: string + examples: + - AR14106062795078369281 + creative_id: + type: string + examples: + - CR14003695067076755457 + advertiser_name: + type: string + examples: + - Gong.io Inc + format: + type: string + examples: + - Text + start: + type: string + format: date + examples: + - 2025-03-06 + last_seen: + type: string + format: date + examples: + - 2025-06-27 + original_url: + type: string + examples: + - https://adstransparency.google.com/advertiser/AR14106062795078369281/creative/CR14003695067076755457?region=anywhere + variants: + type: array + items: + type: object + properties: + content: + type: string + description: HTML content or JavaScript URL for the ad + height: + type: + - integer + - "null" + width: + type: + - integer + - "null" + JobResult: + type: object + description: Job search result + properties: + company: + type: object + properties: + name: + type: string + examples: + - Microsoft + website_url: + type: string + examples: + - https://www.microsoft.com/ + linkedin_url: + type: string + examples: + - https://profiles.example.com/company/microsoft/ + twitter_handle: + type: string + examples: + - Microsoft + github_url: + type: string + examples: + - https://github.com/microsoft + is_agency: + type: boolean + examples: + - false + title: + type: string + examples: + - Technical Program Manager - Developer (AI) + location: + type: string + examples: + - Redmond, Washington, United States + types: + type: array + items: + type: object + properties: + id: + type: integer + examples: + - 1 + name: + type: string + examples: + - Full Time + cities: + type: array + items: + type: object + properties: + geonameid: + type: integer + examples: + - 5808079 + asciiname: + type: string + examples: + - Redmond + name: + type: string + examples: + - Redmond + country: + type: object + properties: + id: + type: integer + examples: + - 238 + code: + type: string + examples: + - US + name: + type: string + examples: + - United States + has_remote: + type: boolean + examples: + - false + published: + type: string + format: date-time + examples: + - 2025-06-25T20:36:00Z + expired: + type: + - string + - "null" + format: date-time + application_url: + type: string + examples: + - https://jobs.careers.microsoft.com/global/en/job/1833754/ + language: + type: string + examples: + - en + salary_min: + type: string + examples: + - "100600" + salary_max: + type: string + examples: + - "215400" + salary_currency: + type: string + examples: + - USD + experience_level: + type: string + examples: + - Mid Level + description: + type: string + description: Full job description text + Error: + type: object + properties: + error: + type: string + examples: + - Bad Request + message: + type: string + examples: + - API key is missing or invalid. + responses: + BadRequest: + description: Bad Request. The request payload was malformed or failed validation. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + Unauthorized: + description: Unauthorized. The `X-API-Key` header is missing, invalid, or the key has been revoked. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + TooManyRequests: + description: Too Many Requests. The rate limit for your API key has been exceeded. Back off and retry with exponential jitter. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + InternalServerError: + description: Internal Server Error. An unexpected error occurred while processing the request. Retry with exponential backoff; if the problem persists, contact support@leadmagic.io with the correlation id. + content: + application/json: + schema: + $ref: "#/components/schemas/Error"