Docs · API & MCP
Contacts and verified emails for agents
Search B2B contacts by title, company, industry, headcount, country and technology, then reveal verified work emails, through an MCP server and a REST API. Same credits and suppression rules as the app, on every plan, including Free.
What's live
Each tool and endpoint below carries a badge. Live means you can call it today. Planned means the contract is published but calls return 404 with details.status: "not_implemented". The OpenAPI document marks the same thing with x-status and is always the source of truth.
Quickstart
Pick your tool and follow the steps; it takes about a minute. Claude signs you in, so it needs no key. Every other tool needs an API key from Settings → API & MCP. Keys start with lc_live_ and are shown once.
No API key needed. You sign in to Leadscart instead.
Open Claude's connectors page and click Add custom connector.
Fill in the two boxes:
NameLeadscartURLhttp://leadscart.io/api/mcpClick Add, then Connect. Sign in to Leadscart and click Allow.
Start a new chat and ask for people. That's it.
Works in the Claude desktop and mobile apps too. On a Team or Enterprise plan, a Claude owner adds it once under Organization settings → Connectors.
To disconnect later, revoke “Claude (connected)” under API keys in Settings → API & MCP.
Workflow recipes
In n8n and Clay every call is an HTTP request with the same Authorization header. Two common ones:
Node: HTTP Request
Method: POST
URL: http://leadscart.io/api/v1/people/search
Authentication: Generic → Header Auth
Name: Authorization
Value: Bearer lc_live_…
Body (JSON): {"filters": {"titles": ["VP Sales"], "countries": ["US"]}}Authentication
- Send
Authorization: Bearer lc_live_…on every request to/api/v1/*and/api/mcp. - Keys belong to a workspace and spend its credits. We store only a hash; a lost key can't be recovered, only replaced.
- Keys expire after 180 days and can be revoked at any time from Settings.
- Never put a key in browser code. Use it from servers, agents and workflow tools.
curl http://leadscart.io/api/v1/credits \ -H "Authorization: Bearer lc_live_…"
Rate limits
Each key may send 120 requests per minute (sliding window). Over the limit you get 429 rate_limited with a Retry-After header. Searches also count against a per-workspace daily page budget, which surfaces as 429 or 503 budget_exhausted.
Credits in every response
Successful JSON responses are wrapped in one envelope, so an agent always knows what a call cost. CSV exports carry the same numbers in X-Credits-Spent and X-Credits-Remaining headers. Errors include credits too (spent is 0).
{
"data": { … },
"credits": { "spent": 3, "remaining": 197 }
}Costs: searching and export are free; 1 per verified email (only when a verified address comes back). Every call shows its maximum cost before it spends anything.
MCP tools
Tool names are noun_verb. Inputs and outputs below are sketches; the MCP server's tool schemas are exact.
people_searchLiveSearch contacts by title, company, industry, headcount, country and technology.
- in
- { filters: { titles, countries, employee_ranges, … }, page? 1–5 }
- out
- ok { people, total } · too_broad / no_matches { suggestions }
- credits
- Free to search and export · 1 per verified email
email_findLiveFind verified work emails for leads already on a List.
- in
- { lead_ids: string[] ≤ 25, idempotency_key? }
- out
- { results: { lead_id, email, status }[] }
- credits
- 1 per deliverable email · misses free
list_createLiveCreate a List to collect leads.
- in
- { name }
- out
- { id, name }
- credits
- Free
list_addLiveAdd people (by LinkedIn URL) to a List. Suppressed people are skipped.
- in
- { list_id, people: { linkedin_url, … }[] ≤ 500 }
- out
- { added, already_in_list, suppressed, lead_ids }
- credits
- Free
list_exportLiveExport a List as JSON rows or CSV.
- in
- { list_id, include_emails? } (REST: ?format=json|csv)
- out
- { rows } or CSV
- credits
- Free to export
credits_balanceLiveCurrent balance and credits expiring soon.
- in
- {}
- out
- { balance, lists_equivalent, expiring_within_7_days, next_expiry }
- credits
- Free
REST endpoints
Base URL http://leadscart.io/api/v1. JSON in, JSON out. Full request and response schemas are in /api/v1/openapi.json. ChatGPT rejects action descriptions over 300 characters, so import /api/v1/openapi.json?for=chatgpt there: the same API, described more briefly.
GET/api/v1/creditsCredit balance· credits_balanceLivePOST/api/v1/people/searchSearch people· people_searchLivePOST/api/v1/emails/findFind verified work emails· email_findLiveGET/api/v1/listsList ListsLivePOST/api/v1/listsCreate a List· list_createLivePOST/api/v1/lists/{id}/itemsAdd people to a List· list_addLiveGET/api/v1/lists/{id}/exportExport a List· list_exportLiveErrors
Errors share one shape. message is safe to show to a user; retryable tells an agent whether to try again.
{
"error": {
"code": "insufficient_credits",
"message": "You don't have enough credits for this. Buy credits to continue.",
"retryable": false
},
"credits": { "spent": 0, "remaining": 12 }
}unauthorizedMissing, malformed, expired or revoked API key. Check the Authorization header; create a new key.insufficient_creditsThe balance can't cover the maximum cost of this call. Choose a bigger plan, or lower credit_budget.conflictA conflicting operation is already in progress, e.g. the same run or export. Wait for it to finish, then retry.provider_rejectedInput is valid JSON but can't be run: unknown filter values or an impossible query. Fix the filters named in details.rate_limitedMore than 120 requests per minute on this key. Wait Retry-After seconds.provider_unavailable · budget_exhaustedA data provider is down, or today's capacity is used up. Retry later; retryable is true.