{
  "openapi": "3.1.0",
  "info": {
    "title": "Leads Pro API",
    "description": "B2B contact and company data for work emails, phones, LinkedIn profiles, job titles, firmographics, and company records.",
    "version": "1.0.0",
    "contact": {
      "name": "Leads Pro Support",
      "email": "hello@prospectloom.dev",
      "url": "https://leads-pro.co"
    }
  },
  "servers": [
    {
      "url": "https://leads-pro.co",
      "description": "Production"
    }
  ],
  "security": [
    { "BearerAuth": [] }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Check if the API is up and running. No authentication required.",
        "security": [],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/enrich": {
      "post": {
        "operationId": "enrichContact",
        "summary": "Enrich a single contact",
        "description": "Look up a contact by email, or by name combined with company/domain. Returns LinkedIn-sourced profile data with a confidence score.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EnrichRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enrichment match found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EnrichResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/QuotaExceeded" },
          "404": { "$ref": "#/components/responses/NoMatch" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/enrich/batch": {
      "post": {
        "operationId": "enrichBatch",
        "summary": "Enrich multiple contacts",
        "description": "Enrich up to 100 contacts in a single request. Requires Pro or Team plan.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchEnrichRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchEnrichResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/QuotaExceeded" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "getApiKeyInfo",
        "summary": "Get API key info",
        "description": "Returns information about the current API key, its workspace, and subscription plan.",
        "responses": {
          "200": {
            "description": "API key details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MeResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Get usage stats",
        "description": "Returns current month's credit usage, remaining quota, and rate limit status for the API key's workspace.",
        "responses": {
          "200": {
            "description": "Usage statistics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UsageResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/v1/search/people": {
      "post": {
        "operationId": "searchPeople",
        "summary": "Search people",
        "description": "Search for contacts by job title, seniority, department, company, industry, location, or company size. At least one filter is required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SearchPeopleRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchPeopleResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/QuotaExceeded" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/v1/search/companies": {
      "post": {
        "operationId": "searchCompanies",
        "summary": "Search companies",
        "description": "Search for companies by name, industry, headcount band, or domain. At least one filter is required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SearchCompaniesRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchCompaniesResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/QuotaExceeded" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key as Bearer token. Get your key from the Leads Pro dashboard at /settings/api-keys"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key via x-api-key header (alternative to Bearer)"
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "status": { "type": "string" },
          "time": { "type": "string", "format": "date-time" }
        }
      },
      "EnrichRequest": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "description": "Email address to look up" },
          "phone": { "type": "string", "description": "Phone number for exact lookup" },
          "linkedin": { "type": "string", "description": "LinkedIn slug or full profile URL" },
          "name": { "type": "string", "description": "Full name of the contact" },
          "company": { "type": "string", "description": "Company name" },
          "domain": { "type": "string", "description": "Company domain (e.g. northpeak.io)" }
        },
        "description": "Provide `email`, `phone`, `linkedin`, OR `name` + (`company` or `domain`)."
      },
      "PersonData": {
        "type": "object",
        "properties": {
          "full_name": { "type": "string" },
          "first_name": { "type": "string" },
          "last_name": { "type": "string" },
          "email": { "type": "string" },
          "phone": { "type": "string" },
          "linkedin_slug": { "type": "string" },
          "job_title": { "type": "string" },
          "seniority": { "type": "string" },
          "management_level": { "type": "string" },
          "department": { "type": "string" },
          "skills": { "type": "array", "items": { "type": "string" } },
          "keywords": { "type": "array", "items": { "type": "string" } },
          "languages": { "type": "array", "items": { "type": "string" } },
          "location": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "country": { "type": "string" },
          "postal_code": { "type": "string" },
          "status": { "type": "string" },
          "match_confidence": { "type": "number", "minimum": 0, "maximum": 1 }
        }
      },
      "CompanyData": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "website": { "type": "string" },
          "phone": { "type": "string" },
          "industry": { "type": "string" },
          "headcount_band": { "type": "string" },
          "revenue": { "type": "string" },
          "founded_year": { "type": "integer" },
          "employees": { "type": "integer" },
          "keywords": { "type": "array", "items": { "type": "string" } },
          "technologies": { "type": "array", "items": { "type": "string" } },
          "description": { "type": "string" },
          "facebook_handle": { "type": "string" },
          "linkedin_handle": { "type": "string" },
          "x_handle": { "type": "string" },
          "city": { "type": "string" },
          "state": { "type": "string" },
          "country": { "type": "string" },
          "postal_code": { "type": "string" },
          "total_funding": { "type": "string" },
          "status": { "type": "string" }
        }
      },
      "EnrichResponse": {
        "type": "object",
        "properties": {
          "person": { "$ref": "#/components/schemas/PersonData" },
          "company": { "$ref": "#/components/schemas/CompanyData" },
          "meta": {
            "type": "object",
            "properties": {
              "request_id": { "type": "string" },
              "credits_used": { "type": "integer" },
              "matched_on": { "type": "array", "items": { "type": "string" } },
              "dataset_version": { "type": "string" }
            }
          }
        }
      },
      "BatchEnrichRequest": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "maxItems": 100,
            "items": { "$ref": "#/components/schemas/EnrichRequest" }
          }
        }
      },
      "BatchEnrichResponse": {
        "type": "object",
        "properties": {
          "items": { "type": "array", "items": { "type": "object" } },
          "meta": {
            "type": "object",
            "properties": {
              "request_id": { "type": "string" },
              "batch_size": { "type": "integer" },
              "successful_items": { "type": "integer" },
              "credits_used": { "type": "integer" }
            }
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "key": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "prefix": { "type": "string" },
              "label": { "type": "string" },
              "status": { "type": "string" },
              "created_at": { "type": "string", "format": "date-time" },
              "last_used_at": { "type": "string", "format": "date-time" }
            }
          },
          "workspace": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "name": { "type": "string" },
              "slug": { "type": "string" }
            }
          },
          "plan": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "display_name": { "type": "string" },
              "monthly_credits": { "type": "integer" },
              "rate_limit": { "type": "integer" },
              "batch_enabled": { "type": "boolean" },
              "max_batch_size": { "type": "integer" }
            }
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "properties": {
          "period": {
            "type": "object",
            "properties": {
              "start": { "type": "string", "format": "date-time" },
              "end": { "type": "string", "format": "date-time" }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "credits_used": { "type": "integer" },
              "credits_limit": { "type": "integer" },
              "credits_remaining": { "type": "integer" },
              "percentage_used": { "type": "number" }
            }
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "requests_per_minute": { "type": "integer" },
              "current_minute_count": { "type": "integer" }
            }
          },
          "plan": { "type": "string" }
        }
      },
      "SearchPeopleRequest": {
        "type": "object",
        "properties": {
          "job_title": { "type": "string", "description": "Filter by job title (partial match)" },
          "seniority": { "type": "string", "description": "Filter by seniority level" },
          "management_level": { "type": "string", "description": "Filter by management level" },
          "department": { "type": "string", "description": "Filter by department" },
          "company": { "type": "string", "description": "Filter by company name (partial match)" },
          "industry": { "type": "string", "description": "Filter by company industry (partial match)" },
          "location": { "type": "string", "description": "Filter by location (partial match)" },
          "state": { "type": "string", "description": "Filter by state" },
          "country": { "type": "string", "description": "Filter by country" },
          "headcount_band": { "type": "string", "description": "Filter by company size" },
          "skill": { "type": "string", "description": "Filter by exact skill tag" },
          "keyword": { "type": "string", "description": "Filter by exact keyword tag" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max results to return" },
          "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Results offset for pagination" }
        },
        "description": "At least one filter field is required."
      },
      "SearchPeopleResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "full_name": { "type": "string" },
                "first_name": { "type": "string" },
                "last_name": { "type": "string" },
                "job_title": { "type": "string" },
                "seniority": { "type": "string" },
                "management_level": { "type": "string" },
                "department": { "type": "string" },
                "email": { "type": "string" },
                "phone": { "type": "string" },
                "linkedin_slug": { "type": "string" },
                "location": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" },
                "country": { "type": "string" },
                "postal_code": { "type": "string" },
                "skills": { "type": "array", "items": { "type": "string" } },
                "keywords": { "type": "array", "items": { "type": "string" } },
                "languages": { "type": "array", "items": { "type": "string" } },
                "status": { "type": "string" },
                "company": { "$ref": "#/components/schemas/CompanyData" }
              }
            }
          },
          "total": { "type": "integer" },
          "credits_used": { "type": "integer" },
          "meta": {
            "type": "object",
            "properties": {
              "request_id": { "type": "string" }
            }
          }
        }
      },
      "SearchCompaniesRequest": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Company name (partial match)" },
          "industry": { "type": "string", "description": "Industry (partial match)" },
          "headcount_band": { "type": "string", "description": "Company size band" },
          "domain": { "type": "string", "description": "Company domain (partial match)" },
          "website": { "type": "string", "description": "Company website (partial match)" },
          "state": { "type": "string", "description": "Company state" },
          "country": { "type": "string", "description": "Company country" },
          "technology": { "type": "string", "description": "Exact technology tag" },
          "status": { "type": "string", "description": "Data status flag" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
          "offset": { "type": "integer", "minimum": 0, "default": 0 }
        },
        "description": "At least one filter field is required."
      },
      "SearchCompaniesResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CompanyData" }
          },
          "total": { "type": "integer" },
          "credits_used": { "type": "integer" },
          "meta": {
            "type": "object",
            "properties": {
              "request_id": { "type": "string" }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            },
            "required": ["code", "message"]
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "QuotaExceeded": {
        "description": "Monthly credit limit reached",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "NoMatch": {
        "description": "No enrichment match found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      }
    }
  }
}