{
  "openapi": "3.0.3",
  "info": {
    "title": "LeadSonar API",
    "version": "1.1.0",
    "description": "LeadSonar API: B2B lead search, reveal and export over a 168M-contact database; AI enrichment and ICP scoring grounded in each company's own website; domain scraping. Authenticate with the X-API-Key header (create a key in Settings > API Keys). Counting and browsing are free; reveals, exports, enrichment, ICP scores and scrapes spend credits. Human-readable docs: https://docs.leadsonar.io\n\n**Limits.** Requests are limited to about 10 per second per IP (burst 20); over that you get HTTP 503 \u2014 back off and retry. One export delivers at most 50,000 rows; browse pages hold at most 1,000.\n\n**Unknown filter values return 0, not an error.** Check `filters` in the /leads/search response, and use GET /api/v1/leads/filters?field=<name> for valid values.\n\n**Coverage.** Contact data is US-only in practice (68.6M US records with a country; every other country is under 30K). Revenue bands are derived from headcount, not reported revenue.",
    "contact": {
      "name": "LeadSonar Support",
      "email": "support@leadsonar.io",
      "url": "https://app.leadsonar.io/docs.html"
    }
  },
  "servers": [
    {
      "url": "https://app.leadsonar.io",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key starting with ls_live_"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "message": {
            "type": "string",
            "description": "Additional details"
          }
        }
      },
      "ContactInput": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "domain"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "example": "Doe"
          },
          "domain": {
            "type": "string",
            "example": "acme.com"
          },
          "linkedin_url": {
            "type": "string",
            "example": "https://linkedin.com/in/johndoe"
          },
          "company_name": {
            "type": "string",
            "example": "Acme Inc"
          }
        }
      },
      "EnrichRequest": {
        "type": "object",
        "required": [
          "contacts"
        ],
        "properties": {
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactInput"
            },
            "maxItems": 100,
            "description": "List of contacts to enrich (max 100)"
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "email",
                "phone"
              ]
            },
            "default": [
              "email"
            ],
            "description": "What to find: email, phone, or both"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "URL to POST results to when enrichment completes (coming soon)"
          }
        }
      },
      "EnrichResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Job ID \u2014 use this to poll for results"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing"
            ],
            "example": "processing"
          },
          "total_contacts": {
            "type": "integer",
            "example": 5
          },
          "estimated_seconds": {
            "type": "integer",
            "example": 15
          }
        }
      },
      "EnrichStatusResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "completed",
              "failed"
            ]
          },
          "progress": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "completed": {
                "type": "integer"
              },
              "emails_found": {
                "type": "integer"
              },
              "phones_found": {
                "type": "integer"
              }
            }
          },
          "contacts": {
            "type": "array",
            "description": "Only present when status is completed",
            "items": {
              "type": "object",
              "properties": {
                "first_name": {
                  "type": "string"
                },
                "last_name": {
                  "type": "string"
                },
                "domain": {
                  "type": "string"
                },
                "email": {
                  "type": "string",
                  "nullable": true
                },
                "email_confidence": {
                  "type": "number",
                  "nullable": true
                },
                "phone": {
                  "type": "string",
                  "nullable": true
                },
                "phone_type": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "description": "Only present when status is completed",
            "properties": {
              "duration_ms": {
                "type": "integer",
                "nullable": true
              }
            }
          }
        }
      },
      "FindEmailRequest": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "domain"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "example": "Doe"
          },
          "domain": {
            "type": "string",
            "example": "acme.com"
          },
          "linkedin_url": {
            "type": "string",
            "example": "https://linkedin.com/in/johndoe"
          }
        }
      },
      "FindEmailResponse": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "nullable": true,
            "example": "john.doe@acme.com"
          },
          "confidence": {
            "type": "number",
            "example": 0.95,
            "description": "0\u20131 confidence score from the LeadSonar engine"
          },
          "verified": {
            "type": "boolean",
            "example": true,
            "description": "Whether the email passed live deliverability checks"
          },
          "cost_credits": {
            "type": "number",
            "example": 2.5
          }
        }
      },
      "FindPhoneRequest": {
        "type": "object",
        "required": [
          "first_name",
          "last_name",
          "domain"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "example": "Doe"
          },
          "domain": {
            "type": "string",
            "example": "acme.com"
          },
          "linkedin_url": {
            "type": "string",
            "example": "https://linkedin.com/in/johndoe"
          }
        }
      },
      "FindPhoneResponse": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string",
            "nullable": true,
            "example": "+14155551234"
          },
          "phone_type": {
            "type": "string",
            "nullable": true,
            "example": "mobile",
            "enum": [
              "mobile",
              "direct",
              "office",
              null
            ]
          },
          "validated": {
            "type": "boolean",
            "example": true,
            "description": "Whether the number passed validation"
          },
          "cost_credits": {
            "type": "number",
            "example": 15
          }
        }
      },
      "CreditsResponse": {
        "type": "object",
        "properties": {
          "balance": {
            "type": "integer",
            "example": 450
          },
          "total_earned": {
            "type": "integer",
            "example": 500
          },
          "total_spent": {
            "type": "integer",
            "example": 50
          }
        }
      },
      "CreditCostsResponse": {
        "type": "object",
        "description": "Credit cost per operation, so agents can budget before calling.",
        "properties": {
          "find_email": {
            "type": "number",
            "example": 2.5
          },
          "find_phone": {
            "type": "number",
            "example": 15
          },
          "icp_score": {
            "type": "number",
            "example": 1
          },
          "outreach": {
            "type": "number",
            "example": 1
          }
        }
      },
      "IcpScoreRequest": {
        "type": "object",
        "required": [
          "target_icp"
        ],
        "description": "Provide either `email` or the full triplet of `first_name` + `last_name` + `domain`.",
        "properties": {
          "first_name": {
            "type": "string",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "example": "Doe"
          },
          "email": {
            "type": "string",
            "example": "john.doe@acme.com"
          },
          "domain": {
            "type": "string",
            "example": "acme.com"
          },
          "company": {
            "type": "string",
            "example": "Acme Inc"
          },
          "title": {
            "type": "string",
            "example": "VP of Engineering"
          },
          "industry": {
            "type": "string",
            "example": "fintech"
          },
          "target_icp": {
            "type": "string",
            "example": "Mid-market fintech companies in North America with 50-500 employees that need payment infrastructure.",
            "description": "1-2 sentence description of your ideal customer."
          }
        }
      },
      "IcpScoreResponse": {
        "type": "object",
        "properties": {
          "grade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D"
            ],
            "example": "A"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 87
          },
          "fit": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low"
            ],
            "example": "high"
          },
          "company_type": {
            "type": "string",
            "nullable": true,
            "example": "fintech infrastructure company"
          },
          "their_solution": {
            "type": "string",
            "nullable": true,
            "example": "payment processing and revenue growth"
          },
          "buyer_personas": {
            "type": "string",
            "nullable": true,
            "example": "CTOs, VPs of Engineering, fintech founders"
          },
          "analysis": {
            "type": "string",
            "nullable": true,
            "description": "Free-form reasoning behind the score"
          },
          "cost_credits": {
            "type": "number",
            "example": 1
          },
          "company_type_plural": {
            "type": "string",
            "example": "Payment Solutions Providers"
          },
          "industry_descriptor": {
            "type": "string",
            "example": "financial services and payment solutions"
          }
        }
      },
      "LeadSearchRequest": {
        "type": "object",
        "description": "Lead Finder filters. Singular and plural spellings are both accepted (industry / industryNames).",
        "properties": {
          "industry": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniority": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO country codes. The source is ~99.9% US."
          },
          "companySize": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "revenue": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "department": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free text, whole-word matched against the job title."
          },
          "includeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Matched against the company description, not the title."
          },
          "excludeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxPerCompany": {
            "type": "integer",
            "description": "Cap contacts per company."
          },
          "companyType": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "private",
                "government",
                "nonprofit",
                "education"
              ]
            },
            "description": "Company type, derived from each company's industry (the source has no ownership field). Values OR together. Public (listed) company filtering is not available yet; sending \"public\" or any other value returns 400 with code COMPANY_TYPE_NOT_AVAILABLE or UNKNOWN_COMPANY_TYPE."
          },
          "exactMatch": {
            "type": "boolean",
            "default": false,
            "description": "Match jobTitles (and keywords) as whole words. Without it titles match as substrings, so \"CFO\" can hit unrelated titles. The app always sends true; set it yourself."
          },
          "excludeTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Drop anyone whose job title contains any of these words, e.g. [\"intern\", \"assistant\"]."
          }
        }
      },
      "LeadSearchResponse": {
        "type": "object",
        "properties": {
          "firmographic_total": {
            "type": "integer",
            "description": "Structured filters only (industry, size, country, revenue), counted upstream."
          },
          "firmographic_is_exact": {
            "type": "boolean"
          },
          "estimated_total": {
            "type": "integer",
            "description": "After per-row matching (titles, keywords, department, seniority). PLAN EXPORTS AROUND THIS NUMBER."
          },
          "basis": {
            "type": "string",
            "enum": [
              "sampled",
              "exact"
            ]
          },
          "note": {
            "type": "string"
          },
          "narrowed_by": {
            "type": "string",
            "nullable": true,
            "description": "Which filter collapsed the result, when one did."
          },
          "keywords": {
            "type": "object",
            "nullable": true,
            "description": "What each include-keyword cost, per term."
          },
          "filters": {
            "type": "object",
            "additionalProperties": true,
            "description": "The filters as the server understood them \u2014 check this when a count looks wrong."
          }
        }
      },
      "LeadExportRequest": {
        "type": "object",
        "description": "Lead Finder filters. Singular and plural spellings are both accepted (industry / industryNames).",
        "properties": {
          "industry": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniority": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO country codes. The source is ~99.9% US."
          },
          "companySize": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "revenue": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "department": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free text, whole-word matched against the job title."
          },
          "includeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Matched against the company description, not the title."
          },
          "excludeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxPerCompany": {
            "type": "integer",
            "description": "Cap contacts per company."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50000,
            "description": "Required. Rows to export; requests above 50,000 are capped and report capped_to_max."
          },
          "companyType": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "private",
                "government",
                "nonprofit",
                "education"
              ]
            },
            "description": "Company type, derived from each company's industry (the source has no ownership field). Values OR together. Public (listed) company filtering is not available yet; sending \"public\" or any other value returns 400 with code COMPANY_TYPE_NOT_AVAILABLE or UNKNOWN_COMPANY_TYPE."
          },
          "exactMatch": {
            "type": "boolean",
            "default": false,
            "description": "Match jobTitles (and keywords) as whole words. Without it titles match as substrings, so \"CFO\" can hit unrelated titles. The app always sends true; set it yourself."
          },
          "excludeTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Drop anyone whose job title contains any of these words, e.g. [\"intern\", \"assistant\"]."
          }
        },
        "required": [
          "limit"
        ]
      },
      "LeadExportJob": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ]
          },
          "requestedLimit": {
            "type": "integer"
          },
          "progress": {
            "type": "integer"
          },
          "deliveredRows": {
            "type": "integer",
            "description": "Rows actually delivered and billed. Leads this account already revealed are skipped and not charged again, so a repeat of the same filters returns fewer rows \u2014 0 once the segment is exhausted."
          },
          "creditsCharged": {
            "type": "integer"
          },
          "capped": {
            "type": "boolean"
          },
          "filename": {
            "type": "string"
          },
          "note": {
            "type": "string",
            "nullable": true
          },
          "downloadable": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "LeadBrowseRequest": {
        "type": "object",
        "description": "Same filters as /leads/search, plus paging.",
        "properties": {
          "industry": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniority": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO country codes. The source is ~99.9% US."
          },
          "companySize": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "revenue": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "department": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free text, whole-word matched against the job title."
          },
          "includeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Matched against the company description, not the title."
          },
          "excludeKeywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "maxPerCompany": {
            "type": "integer",
            "description": "Cap contacts per company."
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "default": 1,
            "description": "Page in order. A cold jump to a deep page walks forward and is slower."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 25
          },
          "companyType": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "private",
                "government",
                "nonprofit",
                "education"
              ]
            },
            "description": "Company type, derived from each company's industry (the source has no ownership field). Values OR together. Public (listed) company filtering is not available yet; sending \"public\" or any other value returns 400 with code COMPANY_TYPE_NOT_AVAILABLE or UNKNOWN_COMPANY_TYPE."
          },
          "exactMatch": {
            "type": "boolean",
            "default": false,
            "description": "Match jobTitles (and keywords) as whole words. Without it titles match as substrings, so \"CFO\" can hit unrelated titles. The app always sends true; set it yourself."
          },
          "excludeTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Drop anyone whose job title contains any of these words, e.g. [\"intern\", \"assistant\"]."
          }
        }
      },
      "MaskedLead": {
        "type": "object",
        "description": "A lead as the app's browse page shows it. Email, last name, company domain and LinkedIn URL are withheld until the row is revealed.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Feed this to /leads/reveal."
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string",
            "description": "Masked, e.g. \"J.\""
          },
          "email": {
            "type": "string",
            "description": "Masked, e.g. \"\u2022\u2022\u2022@\u2022\u2022\u2022.org\""
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "description": "Masked."
          },
          "companyName": {
            "type": "string"
          },
          "companyDomain": {
            "type": "string",
            "nullable": true,
            "description": "null until revealed."
          },
          "jobTitle": {
            "type": "string"
          },
          "seniority": {
            "type": "string"
          },
          "department": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "countryCode": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "companySize": {
            "type": "string"
          },
          "linkedinUrl": {
            "type": "string",
            "nullable": true,
            "description": "null until revealed."
          },
          "industryName": {
            "type": "string"
          }
        }
      },
      "LeadRevealRequest": {
        "type": "object",
        "required": [
          "leadIds"
        ],
        "properties": {
          "leadIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "maxItems": 100000,
            "description": "Lead ids from /leads/browse. A malformed id rejects the whole batch \u2014 you are billed per row and must know what you paid for."
          }
        }
      },
      "LeadRevealResponse": {
        "type": "object",
        "properties": {
          "revealed": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Full rows: real email, domain and LinkedIn URL."
          },
          "credits_charged": {
            "type": "integer",
            "description": "REVEAL_COST per NEW lead. Leads this account already revealed are returned again and charged nothing."
          },
          "new_reveals": {
            "type": "integer"
          },
          "already_revealed": {
            "type": "integer"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/icp-score": {
      "post": {
        "summary": "Score ICP fit",
        "description": "**Cost:** 1 credit per contact\n\nReturns an A/B/C/D grade plus a 0-100 numeric score and a buyer-persona breakdown. Wraps LeadSonar's AI enrichment engine. Costs 1 credit per call. Provide either an `email` or the full triplet of `first_name` + `last_name` + `domain`. The `target_icp` field is required \u2014 describe your ideal customer in 1-2 sentences.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/icp-score \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"first_name\": \"Jordan\",\n    \"last_name\": \"Reyes\",\n    \"title\": \"Head of Sales\",\n    \"company\": \"Maildeck\",\n    \"domain\": \"maildeck.co\",\n    \"target_icp\": \"Agencies and B2B companies that run cold email outreach and need sending infrastructure\"\n  }'\n```",
        "operationId": "icpScore",
        "tags": [
          "AI Enrichment"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IcpScoreRequest"
              },
              "example": {
                "first_name": "Jordan",
                "last_name": "Reyes",
                "title": "Head of Sales",
                "company": "Maildeck",
                "domain": "maildeck.co",
                "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "ICP score result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IcpScoreResponse"
                },
                "example": {
                  "grade": "A",
                  "score": 81,
                  "fit": "high",
                  "company_type": "cold email infrastructure providers",
                  "company_type_plural": "cold email infrastructure providers",
                  "industry_descriptor": "cold email infrastructure",
                  "their_solution": "scalable cold email infrastructure",
                  "buyer_personas": null,
                  "analysis": null,
                  "cost_credits": 1
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "AI enrichment service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits": {
      "get": {
        "summary": "Get credit balance",
        "description": "**Cost:** Free\n\nReturns current credit balance, total earned, and total spent.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/credits \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "operationId": "getCredits",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Credit balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsResponse"
                },
                "example": {
                  "balance": 50277,
                  "total_earned": 50300,
                  "total_spent": 23
                }
              }
            }
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "summary": "Get the OpenAPI spec",
        "description": "**Cost:** Free, no key needed\n\nReturns this OpenAPI spec. Useful for AI agent discovery.",
        "operationId": "getOpenApiSpec",
        "tags": [
          "Meta"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.0 spec",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/leads/filters": {
      "get": {
        "summary": "List filters and values",
        "description": "**Cost:** Free\n\nFilter values must match the source's spelling exactly \u2014 a near-miss returns zero rather than an error, so read the list rather than guessing. jobTitles/includeKeywords/excludeKeywords are free text and have no fixed list.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/filters \\\n  -H \"X-API-Key: $LS_KEY\"\n```\n\nOne filter's values:\n\n```bash\ncurl \"https://app.leadsonar.io/api/v1/leads/filters?field=seniority\" \\\n  -H \"X-API-Key: $LS_KEY\"\n```\n\n```json\n{\n  \"field\": \"seniority\",\n  \"values\": [\n    {\n      \"value\": \"Staff\",\n      \"count\": \"46030856\"\n    },\n    {\n      \"value\": \"Manager\",\n      \"count\": \"13846020\"\n    },\n    {\n      \"value\": \"Cxo\",\n      \"count\": \"5565033\"\n    },\n    {\n      \"value\": \"Director\",\n      \"count\": \"3555477\"\n    },\n    {\n      \"value\": \"Vp\",\n      \"count\": \"2096093\"\n    }\n  ]\n}\n```",
        "operationId": "getLeadFilters",
        "tags": [
          "Leads"
        ],
        "parameters": [
          {
            "name": "field",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "industry",
                "seniority",
                "country",
                "department",
                "company_size",
                "revenue"
              ]
            },
            "description": "Omit to list the filter names; pass one to get that filter's values."
          }
        ],
        "responses": {
          "200": {
            "description": "Filter names, or the requested filter's values",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "filters": [
                    "industry",
                    "seniority",
                    "country",
                    "department",
                    "company_size",
                    "revenue",
                    "companyType"
                  ],
                  "note": "Call again with ?field=<name> for that filter's values. jobTitles, excludeTitles, includeKeywords and excludeKeywords are free text and have no fixed list."
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/leads/search": {
      "post": {
        "summary": "Count leads",
        "description": "**Cost:** Free\n\nReturns counts only and charges nothing. Two totals are reported because they measure different things: structured filters are counted upstream, while titles/keywords/department are applied per row and can only be sampled. Plan exports around estimated_total.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/search \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jobTitles\": [\"Head of Sales\"],\n    \"exactMatch\": true,\n    \"industry\": [\"Software Development\"],\n    \"companySize\": [\"51-200\"],\n    \"country\": [\"US\"]\n  }'\n```",
        "operationId": "searchLeads",
        "tags": [
          "Leads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadSearchRequest"
              },
              "example": {
                "jobTitles": [
                  "Head of Sales"
                ],
                "exactMatch": true,
                "industry": [
                  "Software Development"
                ],
                "companySize": [
                  "51-200"
                ],
                "country": [
                  "US"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Match counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadSearchResponse"
                },
                "example": {
                  "firmographic_total": 179984,
                  "firmographic_is_exact": true,
                  "estimated_total": 607,
                  "basis": "sampled",
                  "note": "estimated_total is sampled: keyword/role/department filters are applied per row and cannot be counted upstream. Plan exports around estimated_total.",
                  "narrowed_by": null,
                  "keywords": null,
                  "filters": {
                    "industryNames": [
                      "Software Development"
                    ],
                    "countryCodes": [
                      "US"
                    ],
                    "companySizes": [
                      "51-200"
                    ],
                    "jobTitles": [
                      "Head of Sales"
                    ],
                    "exactMatch": true,
                    "matchAny": false
                  }
                }
              }
            }
          },
          "502": {
            "description": "Lead source unavailable (LEADS_SOURCE_DOWN)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/leads/browse": {
      "post": {
        "summary": "Browse leads",
        "description": "**Cost:** Free \u2014 contact details are masked\n\nThe middle step between counts and a bulk export: look at the rows, pick the ones worth paying for, reveal those. Charges nothing, exactly like the app's finder. Leads this account has already revealed are dropped from the results.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/browse \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jobTitles\": [\"Head of Sales\"],\n    \"exactMatch\": true,\n    \"industry\": [\"Software Development\"],\n    \"companySize\": [\"51-200\"],\n    \"country\": [\"US\"],\n    \"page\": 1,\n    \"limit\": 2\n  }'\n```",
        "operationId": "browseLeads",
        "tags": [
          "Leads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadBrowseRequest"
              },
              "example": {
                "jobTitles": [
                  "Head of Sales"
                ],
                "exactMatch": true,
                "industry": [
                  "Software Development"
                ],
                "companySize": [
                  "51-200"
                ],
                "country": [
                  "US"
                ],
                "page": 1,
                "limit": 2
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A page of masked leads",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "returned": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer",
                      "nullable": true
                    },
                    "total_is_exact": {
                      "type": "boolean"
                    },
                    "total_is_estimate": {
                      "type": "boolean"
                    },
                    "next_page": {
                      "type": "integer",
                      "nullable": true,
                      "description": "null when the page came back short \u2014 that is the end."
                    },
                    "leads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MaskedLead"
                      }
                    },
                    "note": {
                      "type": "string",
                      "nullable": true,
                      "description": "Explains estimates or masking for this page, when relevant."
                    }
                  }
                },
                "example": {
                  "page": 1,
                  "limit": 2,
                  "returned": 2,
                  "total": 179984,
                  "total_is_exact": false,
                  "total_is_estimate": true,
                  "next_page": 2,
                  "leads": [
                    {
                      "id": "3f1c2a90-0000-4000-8000-000000000001",
                      "firstName": "Jordan",
                      "lastName": "Reyes",
                      "fullName": "Jordan Reyes",
                      "email": "\u2022\u2022\u2022@\u2022\u2022\u2022.com",
                      "phone": "+1512****10",
                      "companyName": "Example Software Inc.",
                      "companyDomain": null,
                      "jobTitle": "Head Of Sales Amer",
                      "seniority": "",
                      "department": "",
                      "country": "US",
                      "countryCode": "US",
                      "state": "TX",
                      "city": "Austin",
                      "companySize": "101 to 250",
                      "linkedinUrl": null,
                      "industryName": "Software Development",
                      "categoryName": null
                    },
                    {
                      "id": "3f1c2a90-0000-4000-8000-000000000002",
                      "firstName": "Priya",
                      "lastName": "Natarajan",
                      "fullName": "Priya Natarajan",
                      "email": "\u2022\u2022\u2022@\u2022\u2022\u2022.com",
                      "phone": null,
                      "companyName": "Northwind Analytics",
                      "companyDomain": null,
                      "jobTitle": "Head Of Discovery Sales/ Engagement Manager",
                      "seniority": "",
                      "department": "",
                      "country": "US",
                      "countryCode": "US",
                      "state": "",
                      "city": "",
                      "companySize": "101 to 250",
                      "linkedinUrl": null,
                      "industryName": "Software Development",
                      "categoryName": null
                    }
                  ],
                  "note": "Browsing is free and returns masked rows. Email, last name, company domain and LinkedIn URL unlock via POST /api/v1/leads/reveal, which charges credits per NEW lead exactly as the app does. Leads you have already revealed are dropped from these results."
                }
              }
            }
          },
          "502": {
            "description": "Lead source unavailable (LEADS_SOURCE_DOWN)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/leads/reveal": {
      "post": {
        "summary": "Reveal leads",
        "description": "**Cost:** 1 credit per lead not already revealed\n\nRuns the app's own reveal: one transaction, the same already-revealed dedup, the same ledger entries. All-or-nothing \u2014 an account that cannot pay for the whole batch reveals none of it.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/reveal \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"leadIds\": [\"3f1c2a90-0000-4000-8000-000000000001\"]\n  }'\n```",
        "operationId": "revealLeads",
        "tags": [
          "Leads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadRevealRequest"
              },
              "example": {
                "leadIds": [
                  "3f1c2a90-0000-4000-8000-000000000001"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revealed rows and what they cost",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadRevealResponse"
                },
                "example": {
                  "revealed": [
                    {
                      "id": "3f1c2a90-0000-4000-8000-000000000001",
                      "firstName": "Jordan",
                      "lastName": "Reyes",
                      "fullName": "Jordan Reyes",
                      "email": "jordan.reyes@example-software.com",
                      "emailStatus": "unknown",
                      "phone": "+15125550110",
                      "linkedinUrl": "linkedin.com/in/jordanreyes",
                      "companyName": "Example Software Inc.",
                      "companyDomain": "example-software.com",
                      "jobTitle": "Head Of Sales Amer",
                      "seniority": "",
                      "department": "",
                      "country": null,
                      "countryCode": "US",
                      "state": "TX",
                      "city": "Austin",
                      "companySize": "101 to 250",
                      "companyRevenue": null,
                      "companyFounded": null,
                      "companyLinkedin": null,
                      "industryName": null,
                      "categoryName": null,
                      "enrichmentStatus": "raw",
                      "confidenceScore": 0
                    }
                  ],
                  "credits_charged": 1,
                  "new_reveals": 1,
                  "already_revealed": 0
                }
              }
            }
          },
          "400": {
            "description": "LEAD_IDS_REQUIRED, TOO_MANY_LEADS or BAD_ID",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "leadIds is required \u2014 the ids of the leads to reveal, from /leads/browse",
                  "code": "LEAD_IDS_REQUIRED"
                }
              }
            }
          },
          "402": {
            "description": "INSUFFICIENT_CREDITS \u2014 nothing was revealed or charged",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/leads/exports": {
      "post": {
        "summary": "Start an export",
        "description": "**Cost:** 1 credit per lead delivered (max 50,000 per export)\n\nAlways asynchronous, at every size. Returns 202 with a job id to poll.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/exports \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jobTitles\": [\"Head of Sales\"],\n    \"exactMatch\": true,\n    \"industry\": [\"Software Development\"],\n    \"companySize\": [\"51-200\"],\n    \"country\": [\"US\"],\n    \"limit\": 3\n  }'\n```",
        "operationId": "createLeadExport",
        "tags": [
          "Leads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadExportRequest"
              },
              "example": {
                "jobTitles": [
                  "Head of Sales"
                ],
                "exactMatch": true,
                "industry": [
                  "Software Development"
                ],
                "companySize": [
                  "51-200"
                ],
                "country": [
                  "US"
                ],
                "limit": 3
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Export queued. Poll `poll` until `status` is `completed`, then GET `download`. Note: this response is snake_case (`job_id`); the status endpoint answers in camelCase (`id`).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Export id \u2014 use it in /exports/{id}"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running",
                        "completed",
                        "failed"
                      ],
                      "example": "queued"
                    },
                    "requested_limit": {
                      "type": "integer",
                      "example": 5000
                    },
                    "capped_to_max": {
                      "type": "integer",
                      "nullable": true,
                      "description": "Set to 50000 when you asked for more than the per-export maximum; otherwise null",
                      "example": null
                    },
                    "poll": {
                      "type": "string",
                      "example": "/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408"
                    },
                    "download": {
                      "type": "string",
                      "example": "/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408/csv"
                    }
                  },
                  "required": [
                    "job_id",
                    "status",
                    "poll",
                    "download"
                  ]
                },
                "example": {
                  "job_id": "4fad85cd-3e37-4797-ab77-07ed02d8f408",
                  "status": "queued",
                  "requested_limit": 3,
                  "capped_to_max": null,
                  "poll": "/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408",
                  "download": "/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408/csv"
                }
              }
            }
          },
          "400": {
            "description": "limit missing (LIMIT_REQUIRED) or export unavailable for this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List exports",
        "operationId": "listLeadExports",
        "tags": [
          "Leads"
        ],
        "responses": {
          "200": {
            "description": "Recent export jobs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "count": 1,
                  "exports": [
                    {
                      "id": "4fad85cd-3e37-4797-ab77-07ed02d8f408",
                      "status": "completed",
                      "requestedLimit": 3,
                      "progress": 100,
                      "deliveredRows": 3,
                      "creditsCharged": 3,
                      "capped": true,
                      "filename": "leadsonar-export-2026-10-06-3.csv",
                      "note": null,
                      "downloadable": true,
                      "createdAt": "2026-10-06T10:27:26.534Z",
                      "completedAt": "2026-10-06T10:27:27.463Z"
                    }
                  ]
                }
              }
            }
          }
        },
        "description": "**Cost:** Free\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/exports \\\n  -H \"X-API-Key: $LS_KEY\"\n```"
      }
    },
    "/api/v1/leads/exports/{id}": {
      "get": {
        "summary": "Get export status",
        "operationId": "getLeadExport",
        "tags": [
          "Leads"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadExportJob"
                },
                "example": {
                  "id": "4fad85cd-3e37-4797-ab77-07ed02d8f408",
                  "status": "completed",
                  "requestedLimit": 3,
                  "progress": 100,
                  "deliveredRows": 3,
                  "creditsCharged": 3,
                  "capped": true,
                  "filename": "leadsonar-export-2026-10-06-3.csv",
                  "note": null,
                  "downloadable": true,
                  "createdAt": "2026-10-06T10:27:26.534Z",
                  "completedAt": "2026-10-06T10:27:27.463Z"
                }
              }
            }
          },
          "404": {
            "description": "Unknown export on this account (EXPORT_NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Unknown export",
                  "code": "EXPORT_NOT_FOUND"
                }
              }
            }
          }
        },
        "description": "**Cost:** Free\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408 \\\n  -H \"X-API-Key: $LS_KEY\"\n```"
      }
    },
    "/api/v1/leads/exports/{id}/csv": {
      "get": {
        "summary": "Download an export",
        "description": "**Cost:** Free \u2014 you paid when it was created\n\nReturns the CSV with an X-Delivered-Rows header. 409 EXPORT_NOT_READY until the job completes.\n\n**Try it**\n\n```bash\ncurl -o result.csv https://app.leadsonar.io/api/v1/leads/exports/4fad85cd-3e37-4797-ab77-07ed02d8f408/csv \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "operationId": "downloadLeadExport",
        "tags": [
          "Leads"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "CSV file",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "First Name,Last Name,Email,Phone,Company,Domain,Job Title,Seniority,Department,Industry,Country,State,City,Company Size,LinkedIn\n\"Jordan\",\"Reyes\",\"jordan.reyes@example-software.com\",\"+15125550110\",\"Example Software Inc.\",\"example-software.com\",\"Head of Sales\",\"Director\",\"Sales\",\"Software Development\",\"US\",\"TX\",\"Austin\",\"101 to 250\",\"linkedin.com/in/jordanreyes\"\n\"Priya\",\"Natarajan\",\"priya.natarajan@northwind-analytics.com\",\"+15125550110\",\"Northwind Analytics\",\"northwind-analytics.com\",\"Head of Sales\",\"Director\",\"Sales\",\"Software Development\",\"US\",\"TX\",\"Austin\",\"101 to 250\",\"linkedin.com/in/priyanatarajan\"\n"
              }
            }
          },
          "409": {
            "description": "Not finished yet (EXPORT_NOT_READY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scrape/jobs": {
      "post": {
        "tags": [
          "Domain scrape"
        ],
        "summary": "Start a scrape job",
        "description": "**Cost:** 1 credit per domain, refunded if the site returns no text\n\nUp to 50,000 domains, URLs or emails per job. 1 credit per domain held; domains without text are refunded when the job completes.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/scrape/jobs \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"domains\": [\"leadsonar.io\", \"maildeck.co\", \"emailshield.co\"]\n  }'\n```",
        "responses": {
          "202": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "628b3626-5ec9-450d-a20d-ab45b55ba304",
                  "status": "queued",
                  "total": 3,
                  "done": 0,
                  "ok": 0,
                  "blocked": 0,
                  "no_content": 0,
                  "invalid": 0,
                  "progress_pct": 0,
                  "credits_charged": 3,
                  "credits_refunded": 0,
                  "created_at": "2026-10-06T10:27:28.777Z",
                  "completed_at": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domains"
                ],
                "properties": {
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 50000
                  }
                }
              },
              "example": {
                "domains": [
                  "leadsonar.io",
                  "maildeck.co",
                  "emailshield.co"
                ]
              }
            }
          }
        },
        "operationId": "createScrapeJob"
      },
      "get": {
        "tags": [
          "Domain scrape"
        ],
        "summary": "List scrape jobs",
        "description": "**Cost:** Free\n\nThe 50 most recent jobs for this account.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/scrape/jobs \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "jobs": [
                    {
                      "id": "628b3626-5ec9-450d-a20d-ab45b55ba304",
                      "status": "completed",
                      "total": 3,
                      "done": null,
                      "ok": 3,
                      "blocked": null,
                      "no_content": null,
                      "invalid": null,
                      "progress_pct": null,
                      "credits_charged": 3,
                      "credits_refunded": 0,
                      "created_at": "2026-10-06T10:27:28.777Z",
                      "completed_at": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "operationId": "listScrapeJobs"
      }
    },
    "/api/v1/scrape/jobs/{id}": {
      "get": {
        "tags": [
          "Domain scrape"
        ],
        "summary": "Get scrape job status",
        "description": "**Cost:** Free\n\nCounts by status: ok, blocked, no_content, invalid.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/scrape/jobs/628b3626-5ec9-450d-a20d-ab45b55ba304 \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "628b3626-5ec9-450d-a20d-ab45b55ba304",
                  "status": "completed",
                  "total": 3,
                  "done": 3,
                  "ok": 3,
                  "blocked": 0,
                  "no_content": 0,
                  "invalid": 0,
                  "progress_pct": 100,
                  "credits_charged": 3,
                  "credits_refunded": 0,
                  "created_at": "2026-10-06T10:27:28.777Z",
                  "completed_at": "2026-10-06T10:30:34.296128"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "operationId": "getScrapeJob"
      }
    },
    "/api/v1/scrape/jobs/{id}/results": {
      "get": {
        "tags": [
          "Domain scrape"
        ],
        "summary": "Get scrape results",
        "description": "**Cost:** Free\n\nWebsite text per domain, in completion order. Page with offset until next_offset is null.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/scrape/jobs/628b3626-5ec9-450d-a20d-ab45b55ba304/results \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "job_id": "628b3626-5ec9-450d-a20d-ab45b55ba304",
                  "status": "completed",
                  "offset": 0,
                  "items": [
                    {
                      "domain": "emailshield.co",
                      "status": "ok",
                      "text": "--- title: \"EmailShield \u2014 Email Verification & List Cleaning | 99.8% Accuracy\" description: \"Email verification with 99.8% accuracy. Multi-port SMTP checks, catch-all detection, blacklist monitoring, and DMARC reporting. Plans from $19/mo for 10K verifications. 40K free credits to start.\" canonical:\u2026",
                      "chars": 2988,
                      "cached": false
                    },
                    {
                      "domain": "maildeck.co",
                      "status": "ok",
                      "text": "--- title: \"MailDeck | Scalable Cold Email Infrastructure\" description: \"The world's most scalable inbox architecture for cold email teams sending 100k+ monthly. Zero configuration. Total deliverability control.\" canonical: \"https://maildeck.co/\" last-updated: \"2026-10-03\" --- > The world's most sca\u2026",
                      "chars": 2891,
                      "cached": false
                    }
                  ],
                  "next_offset": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        },
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ok",
                "blocked",
                "no_content",
                "invalid"
              ]
            }
          }
        ],
        "operationId": "getScrapeJobResults"
      }
    },
    "/api/v1/enrich-csv": {
      "post": {
        "tags": [
          "AI Enrichment"
        ],
        "summary": "Start an enrichment job",
        "operationId": "submitEnrichment",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "description": "**Cost:** Per lead, by the fields you request \u2014 the response explains the charge\n\nMultipart upload. Every row needs a website/domain or an email; name/title/company columns are detected. Credits for all requested cells are held up front (standard fields 1/cell, custom_* 2/cell, full_email free); empty cells are refunded when the job settles. Copy is written from the company website; rows whose site could not be read are marked in \"Website Read\" and left blank.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/enrich-csv \\\n  -H \"X-API-Key: $LS_KEY\" \\\n  -F \"file=@leads.csv\" \\\n  -F \"fields=icp_grading,icp\" \\\n  -F \"target_icp=Agencies and B2B companies that run cold email outreach and need sending infrastructure\"\n```",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file",
                  "fields"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": ".csv file"
                  },
                  "fields": {
                    "type": "string",
                    "description": "Comma-separated field ids. Allowed: opener, icp_grading, icp, subject_lines, full_email, custom_simplified_job_title, custom_who_they_work_with, custom_recent_professional_achievement, custom_subject_line, custom_personalized_opener, custom_ps_line, custom_two_liner, custom_got_me_thinking, custom_full_email_v1, custom_full_email_v2, custom_company_type, custom_buyer_personas",
                    "example": "icp_grading,icp,opener,subject_lines"
                  },
                  "target_icp": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Who you sell to (1-2 sentences). Required with icp_grading."
                  },
                  "seller_offer": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "What you sell; used to write copy."
                  },
                  "user_tag": {
                    "type": "string",
                    "description": "Your own label, echoed on the job."
                  }
                }
              },
              "example": {
                "file": "(binary) leads.csv",
                "fields": "icp_grading,icp",
                "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Job created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string"
                    },
                    "total_rows": {
                      "type": "integer"
                    },
                    "credits_charged": {
                      "type": "number"
                    }
                  }
                },
                "example": {
                  "id": "540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
                  "backend_job_id": "ec-de1bef6b7c",
                  "status": "queued",
                  "total_rows": 2,
                  "fields": [
                    "icp_grading",
                    "icp"
                  ],
                  "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure",
                  "seller_offer_set": false,
                  "user_tag": null,
                  "credits_charged": 4,
                  "cost_explained": "2 rows \u00d7 2 enrichment types = 4 credits",
                  "estimated_seconds": 5,
                  "created_at": "2026-10-06T10:30:37.328Z",
                  "poll_url": "/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
                  "download_url_when_done": "/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11/csv"
                }
              }
            }
          },
          "400": {
            "description": "Invalid fields, missing target_icp, or rows without website/email (response lists the row numbers)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "402": {
            "description": "Insufficient credits; nothing charged"
          },
          "502": {
            "description": "AI service unavailable; hold refunded"
          }
        }
      }
    },
    "/api/v1/enrich-csv/jobs": {
      "get": {
        "tags": [
          "AI Enrichment"
        ],
        "summary": "List enrichment jobs",
        "operationId": "listEnrichmentJobs",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "jobs": [
                    {
                      "id": "540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
                      "status": "queued",
                      "original_filename": "ls-capture.csv",
                      "total_rows": 2,
                      "completed_rows": 0,
                      "fields": [
                        "icp_grading",
                        "icp"
                      ],
                      "target_icp": "Agencies and B2B companies that run cold email outreach and need sending infrastructure",
                      "user_tag": null,
                      "credits_charged": 4,
                      "credits_refunded": 0,
                      "credits_net": 4,
                      "error": null,
                      "created_at": "2026-10-06T10:30:37.328Z",
                      "completed_at": null,
                      "poll_url": "/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
                      "download_url": null
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          }
        },
        "description": "**Cost:** Free\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/enrich-csv/jobs \\\n  -H \"X-API-Key: $LS_KEY\"\n```"
      }
    },
    "/api/v1/enrich-csv/jobs/{id}": {
      "get": {
        "tags": [
          "AI Enrichment"
        ],
        "summary": "Get enrichment job status",
        "operationId": "getEnrichmentJob",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "description": "**Cost:** Free\n\nstatus (queued|running|completed|failed), completed_rows, progress_pct, ETA range (eta_low_seconds/eta_high_seconds), credits_charged, credits_refunded, field_report, download_url when completed. Poll to completion: refunds settle on poll.\n\n**Try it**\n\n```bash\ncurl https://app.leadsonar.io/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11 \\\n  -H \"X-API-Key: $LS_KEY\"\n```",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "id": "540894a7-8fb6-44b6-91ba-d0a56a8f5c11",
                  "status": "queued",
                  "original_filename": "ls-capture.csv",
                  "total_rows": 2,
                  "completed_rows": 0,
                  "progress_pct": 0,
                  "fields": [
                    "icp_grading",
                    "icp"
                  ],
                  "user_tag": null,
                  "credits_charged": 4,
                  "credits_refunded": 0,
                  "elapsed_seconds": null,
                  "rate_per_second": null,
                  "eta_seconds": null,
                  "eta_low_seconds": null,
                  "eta_high_seconds": null,
                  "stage": "queued",
                  "stage_done": 0,
                  "stage_total": 0,
                  "field_report": null,
                  "error": null,
                  "created_at": "2026-10-06T10:30:37.328Z",
                  "download_url": null
                }
              }
            }
          },
          "400": {
            "description": "Malformed id (BAD_ID)"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "No such job on your account"
          }
        }
      }
    },
    "/api/v1/enrich-csv/jobs/{id}/csv": {
      "get": {
        "tags": [
          "AI Enrichment"
        ],
        "summary": "Download enriched CSV",
        "operationId": "downloadEnrichment",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "headers",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "snake"
              ]
            },
            "description": "snake = snake_case column names"
          }
        ],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {}
            }
          },
          "400": {
            "description": "Malformed id (BAD_ID)",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "example": "{\"error\":\"Job status: queued. CSV available only when completed.\"}\n"
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "404": {
            "description": "No such job on your account"
          },
          "409": {
            "description": "Not completed yet"
          }
        },
        "description": "**Cost:** Free\n\n**Try it**\n\n```bash\ncurl -o result.csv https://app.leadsonar.io/api/v1/enrich-csv/jobs/540894a7-8fb6-44b6-91ba-d0a56a8f5c11/csv \\\n  -H \"X-API-Key: $LS_KEY\"\n```"
      }
    }
  },
  "tags": [
    {
      "name": "Leads",
      "description": "Count, browse, reveal and export leads"
    },
    {
      "name": "AI Enrichment",
      "description": "AI-powered ICP scoring and persona analysis"
    },
    {
      "name": "Account",
      "description": "Credits and account info"
    },
    {
      "name": "Meta",
      "description": "API metadata and discovery"
    },
    {
      "name": "Domain scrape",
      "description": "Company website text"
    }
  ]
}