Skip to content

LeadMagic/leadmagic-openapi

BranchesTags

Repository files navigation

LeadMagic OpenAPI Snapshot

This repository contains a maintained OpenAPI snapshot, LLM-friendly docs, and a live API smoke-test script for LeadMagic. It should stay aligned with the current LeadMagic MCP positioning, but it is an API / REST snapshot repo—not a mirror of the full Cursor plugin bundle.

Pairing: For Cursor and hosted MCP (OAuth by default), use the official plugin repo: github.com/LeadMagic/leadmagic-cursor-plugin. That package follows the usual Cursor plugin layout (rules, skills, agent, commands, and MCP)—similar in shape to community examples such as encoredev/cursor-plugin, but with remote HTTP MCP to LeadMagic’s cloud instead of a local stdio server.

The authoritative product documentation is the public docs site:

Status

The public API docs now use versioned routes under /v1/... and expose more endpoints than this repo currently models. This repo currently focuses on the 19 core endpoints already represented in the local OpenAPI files, plus current route mappings and a cleaner validation script.

If you need the full current product surface, treat https://leadmagic.io/docs as the source of truth.

Companion surfaces

LeadMagic's developer surface spans a few aligned entry points:

Surface Repository / URL Use when
REST OpenAPI snapshot This repo — github.com/LeadMagic/leadmagic-openapi Integrating https://api.leadmagic.io, codegen, LLM context from llms.txt, or running test-api smoke tests
Cursor plugin + MCP config github.com/LeadMagic/leadmagic-cursor-plugin Installing LeadMagic in Cursor (marketplace or team marketplace), OAuth-default mcp.json, skills, rules, enrichment agent, and commands
MCP endpoint https://mcp.leadmagic.io/mcp Any MCP client (Cursor, AI SDK, etc.) after auth
Product docs leadmagic.io/docs, MCP setup Authoritative behavior, pricing, and tool reference

This repo should stay aligned with live API behavior, but leadmagic.io/docs remains the source of truth when the product moves ahead of the snapshot.

Hosted MCP tool surface (Cursor)

The public hosted MCP exposes 10 tools (a subset of the REST API), plus:

  • 1 shared docs resource: leadmagic://docs
  • 2 built-in prompts (for example account_research, contact_lookup)
MCP tool Typical REST backing (see docs / OpenAPI)
check_credit_balance GET /v1/credits
validate_work_email POST /v1/people/email-validation
find_work_email POST /v1/people/email-finder
find_mobile_number POST /v1/people/mobile-finder
linkedin_profile_to_work_email POST /v1/people/b2b-profile-email
detect_job_change Job-change detector endpoint (see product docs)
research_account Company search + funding (e.g. /v1/companies/...)
list_company_competitors Competitors endpoint
get_company_technographics Technographics endpoint
find_people_by_role POST /v1/people/role-finder

Important: This OpenAPI snapshot includes jobs and ads routes and other endpoints that are not exposed as MCP tools today. When updating copy here, keep that gap explicit and cross-check leadmagic-cursor-plugin and MCP tools docs.

Files

  • leadmagic-openapi-3.1.yaml: Local OpenAPI snapshot
  • leadmagic-openapi-3.1.json: JSON form of the local snapshot
  • .spectral.yml: OpenAPI lint configuration
  • llms.txt: Short, current LLM-oriented overview
  • llms-full.txt: Longer current LLM-oriented reference
  • test-api.ts: Live smoke-test script against current documented /v1/... routes

Authentication

All endpoints require an X-API-Key header.

curl 'https://api.leadmagic.io/v1/credits' \
  -H 'X-API-Key: YOUR_API_KEY'

Never commit API keys. Use LEADMAGIC_API_KEY or your own secrets manager.

Base URL

https://api.leadmagic.io

Current docs group routes under:

  • /v1/credits
  • /v1/people/*
  • /v1/companies/*
  • /v1/jobs/*
  • /v1/ads/*

Current Route Map

Legacy repo route Current documented route
POST /credits GET /v1/credits
POST /email-validate POST /v1/people/email-validation
POST /email-finder POST /v1/people/email-finder
POST /personal-email-finder POST /v1/people/personal-email-finder
POST /b2b-social-email POST /v1/people/b2b-profile-email
POST /b2b-profile POST /v1/people/b2b-profile
POST /mobile-finder POST /v1/people/mobile-finder
POST /profile-search POST /v1/people/profile-search
POST /role-finder POST /v1/people/role-finder
POST /employee-finder POST /v1/people/employee-finder
POST /company-search POST /v1/companies/company-search
POST /company-funding POST /v1/companies/company-funding
POST /jobs-finder POST /v1/jobs/jobs-finder
GET /job-country GET /v1/jobs/countries
GET /job-types GET /v1/jobs/job-types
POST /google/searchads POST /v1/ads/google-ads-search
POST /meta/searchads POST /v1/ads/meta-ads-search
POST /b2b/searchads POST /v1/ads/b2b-ads-search
POST /b2b/ad-details POST /v1/ads/b2b-ads-details

Credit Consumption

These values are aligned to the public docs as of this cleanup pass.

Endpoint Cost Notes
GET /v1/credits 0 Free, no rate limit called out
POST /v1/people/email-validation 0.25 4 validations per credit
POST /v1/people/email-finder 1 Free on null result
POST /v1/people/personal-email-finder 2 Free if not found
POST /v1/people/b2b-profile-email 5 Free if not found
POST /v1/people/b2b-profile 10 Free if not found
POST /v1/people/mobile-finder 5 Free if not found
POST /v1/people/profile-search 1 Docs currently show 100 req/min
POST /v1/people/role-finder 2 Free if no match
POST /v1/people/employee-finder 0.05 per employee 20 employees per credit
POST /v1/companies/company-search 1 Free if not found
POST /v1/companies/company-funding 4 Free if not found
POST /v1/jobs/jobs-finder 1 per job Free if no jobs found
GET /v1/jobs/countries 0 Metadata
GET /v1/jobs/job-types 0 Metadata
POST /v1/ads/google-ads-search 0.2 5 searches per credit
POST /v1/ads/meta-ads-search 0.2 5 searches per credit
POST /v1/ads/b2b-ads-search 0.2 5 searches per credit
POST /v1/ads/b2b-ads-details 2 Free if not found

Docs-only endpoints not yet represented in the local snapshot include analytics, job change detection, technographics, competitors search, job company types, job industries, job regions, and credits helper endpoints.

Use Case Examples

// Sales prospecting workflow
await fetch("https://api.leadmagic.io/v1/people/email-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/email-validation", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/companies/company-search", { /* ... */ });
// Recruiting workflow
await fetch("https://api.leadmagic.io/v1/people/role-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/employee-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/people/profile-search", { /* ... */ });
// Competitive intelligence workflow
await fetch("https://api.leadmagic.io/v1/companies/company-funding", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/jobs/jobs-finder", { /* ... */ });
await fetch("https://api.leadmagic.io/v1/ads/google-ads-search", { /* ... */ });

Testing & Validation

Set your API key or let the script prompt you securely at runtime:

export LEADMAGIC_API_KEY=your-api-key-here
npm install
npm run test:api

Or run the script without exporting the key first:

npm install
npm run test:api

The script will prompt for the key in an interactive terminal with hidden input, will not print the key back to the console, and uses the current documented /v1/... endpoints to print per-endpoint status, key fields, compact response previews, and a final pass/fail summary.

The default smoke-test fixtures now use live, overridable values instead of placeholder domains, because some endpoints reject placeholders such as example.com with validation errors. You can override them with LEADMAGIC_TEST_COMPANY_NAME, LEADMAGIC_TEST_COMPANY_DOMAIN, LEADMAGIC_TEST_WORK_EMAIL, LEADMAGIC_TEST_PROFILE_URL, and LEADMAGIC_TEST_AD_URL.

Useful flags:

# Only run one endpoint group
npm run test:api -- --group people

# Write a JSON report without storing the API key
npm run test:api -- --report reports/smoke-test.json

# Combine both
npm run test:api -- --group companies --report reports/companies.json

The report file includes status, summary fields, credits consumed, preview data, and pass/fail results. It does not include the API key or request headers.

Notes On Field Shapes

The current docs are no longer uniformly snake_case across every endpoint. Some responses remain snake_case while others use mixed or camelCase field names in examples. Do not assume a single naming convention across the entire API surface without checking the endpoint-specific docs.

OpenAPI 3.1 Notes

This snapshot now follows the key OpenAPI 3.1 and JSON Schema 2020-12 patterns recommended by Zuplo/OpenAPI migration guidance:

  • declares jsonSchemaDialect
  • uses JSON Schema union types like ["string", "null"] instead of nullable: true
  • uses examples arrays instead of legacy example
  • keeps YAML and JSON snapshots synchronized

Lint the spec with:

npm install
npm run lint:openapi

Cursor and MCP alignment

If you update route names, auth expectations, pricing notes, or endpoint coverage here, keep those changes consistent with:

Support

License

MIT

About

OpenAPI 3.1 snapshot and smoke tests for LeadMagic's public B2B enrichment API.

leadmagic.io/docs

Topics

api schema rest-api mcp api-documentation openapi email-validation b2b email-finder data-enrichment prospecting openapi-3 leadmagic

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 1

🎯 LeadMagic OpenAPI Specification v1.0.0 Latest
Jun 27, 2025

Packages

 
 
 

Contributors

Languages