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"