GetLeadz for developers

Get a key

Sign in to the dashboard → API & MCP and create a key. It looks like glz_… and is shown once. Keys are included with paid plans; you can have up to five, and revoke any of them instantly. A key can use your credits and your data — it cannot manage keys, buy credits or change the account.

Authentication

Authorization: Bearer glz_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Status	Code	Meaning
401	`NO_AUTH`	Missing, unknown or revoked key.
403	`UPGRADE_REQUIRED`	The key is valid but the account is no longer on a paid plan.
403	`SESSION_REQUIRED`	That route needs a dashboard sign-in, not a key (keys, checkout, phone, logout).
429	`RATE_LIMIT`	More than 40 requests in a minute. Wait and retry.

Reveal a contact

curl -X POST https://getleadz.tech/v1/enrich \
  -H "Authorization: Bearer glz_…" \
  -H "Content-Type: application/json" \
  -d '{"linkedinSlug":"priya-sharma","field":"both","headline":"CFO at Acme"}'

{
  "field": "both",
  "email": "priya@acme.com",      "emailMeta": "valid · verified",
  "phone": "+919876543210",       "phoneMeta": "direct · confirmed",
  "cached": false, "creditsCharged": 6, "creditsRemaining": 1444
}

linkedinSlug is the part after linkedin.com/in/. Send field as email, phone or both. Pass the headline when you have it: director and CXO phones are priced differently. Every successful reveal is saved to your contacts and fires contact.revealed.

Credits & limits

Field	Credits
Work email	1
Mobile number	5
Mobile number, director / CXO (from the headline)	7
Nothing found	0
Revealing the same person again	0 — forever

Credits never expire. 40 requests per minute per account; a 429 tells you to slow down and nothing is charged for it.

Contacts & lists

Everything you reveal lands in GET /v1/contacts with only the fields you unlocked. Group contacts into lists, tag them, and export CSV (UTF-8 with BOM; phones are written so Excel keeps the +).

POST /v1/lists                         {"name":"Q4 targets"}
POST /v1/lists/{id}/contacts           {"slugs":["priya-sharma","https://www.linkedin.com/in/bob-k"]}
GET  /v1/contacts?list={id}&q=acme
GET  /v1/contacts/export.csv?list={id}   → X-Total / X-Truncated headers
POST /v1/contacts/import-history        → pulls in everything you ever unlocked (idempotent)

Webhooks

Register an https:// URL on the dashboard (or via POST /v1/webhooks) and pick events. Up to five webhooks per account.

Event	When	`data`
`contact.revealed`	A reveal returned data — from the extension, the API or MCP	`slug, profileUrl, name, company, email, phone, creditsCharged, cached, source`
`list.contact_added`	A contact was added to a list	`listId, listName, slug, name, company, email, phone`
`credits.low`	Balance dropped below 10 (once, until it recovers)	`credits, threshold`
`api_key.used_first_time`	A new key authenticated for the first time	`keyId, keyName, prefix`
`ping`	You pressed Test	`message`

Delivery

POST {your url}
Content-Type: application/json
User-Agent: GetLeadz-Webhooks/1
X-GetLeadz-Event: contact.revealed
X-GetLeadz-Delivery: 6d2f0c1e-…        (unique per delivery; retries reuse it)
X-GetLeadz-Timestamp: 1759831200       (unix seconds)
X-GetLeadz-Signature: sha256=…         (see below)

{"id":"6d2f0c1e-…","event":"contact.revealed","createdAt":"2026-10-07T10:00:00.000Z","data":{…}}

Answer with any 2xx within 10 seconds. Anything else is retried after 30 seconds and again after 5 minutes. After 20 consecutive failures the webhook is disabled; re-enable it from the dashboard or with PATCH /v1/webhooks/{id} {"active":true}. Redirects are not followed. The last 20 deliveries, with status and error, are at GET /v1/webhooks/{id}/deliveries; the dashboard shows the latest one.

Delivery is best-effort. The first attempt is made while your request is being served; retries run in the background and can be lost if the server instance restarts in between. Treat webhooks as a nudge, not a ledger: keep the delivery id to de-duplicate, and reconcile against GET /v1/contacts or the deliveries endpoint when it matters.

Verify the signature

The signature is HMAC-SHA256 over "<timestamp>.<raw body>" with the secret shown when you created the webhook. Compute it over the raw bytes, before JSON parsing, and reject timestamps older than a few minutes.

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(headers, rawBody, secret) {
  const ts = headers['x-getleadz-timestamp'];
  const sig = (headers['x-getleadz-signature'] || '').replace('sha256=', '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

# Python
import hmac, hashlib, time
def verify(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers.get("x-getleadz-timestamp", "")
    sig = headers.get("x-getleadz-signature", "").replace("sha256=", "")
    if abs(time.time() - float(ts or 0)) > 300: return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

n8n, Make and Zapier can all receive these: point a Webhook trigger at the URL, add the four headers to a "verify" step if you want the check, and map data.email / data.phone into your CRM.

MCP — use GetLeadz from Claude and Cursor

The hosted MCP server lives at https://getleadz.tech/mcp and authenticates with the same API key.

Claude Code

claude mcp add --transport http getleadz https://getleadz.tech/mcp --header "Authorization: Bearer glz_…"

Claude Desktop

Settings → Connectors → Add custom connector → URL https://getleadz.tech/mcp, then under request headers add Authorization = Bearer glz_….

Cursor (`.cursor/mcp.json`)

{ "mcpServers": { "getleadz": { "url": "https://getleadz.tech/mcp", "headers": { "Authorization": "Bearer glz_…" } } } }

Tools

Tool	What it does	Credits
`reveal_contact`	Reveal one profile. Dry-run by default: returns what is already unlocked and the price; the agent confirms with you, then calls again with `confirm_charge: true`.	as above
`reveal_many`	Up to 25 profiles in one call (URLs, or objects with name/company/headline), same dry-run rule. A dry run counts as one request; a confirmed run counts one per row. Stops cleanly at the rate limit or when credits run out and returns the rows still to do.	as above
`get_account`	Plan, credits, reveals in the last 30 days.	free
`list_reveals`	Your recent lookups.	free
`get_lists` · `create_list` · `add_to_list`	Manage your lists.	free
`search_contacts`	Search your own saved contacts by name, company, title or email. Not a people database.	free
`export_list`	A list (or all contacts) as CSV text, up to 500 rows; larger exports go through `/v1/contacts/export.csv`.	free
`manage_webhooks`	List, create or delete webhooks (the secret is returned once).	free

API reference

The full OpenAPI 3.1 description is at /openapi.json. Load it into Postman, Insomnia or your code generator, or browse it here.

Changelog

2026-10-07 — MCP v2: reveal_many, lists, search, CSV export and webhook tools (server 0.2.0).
2026-10-07 — Saved contacts and lists, CSV export, outbound webhooks, this page and /openapi.json.
2026-10-06 — API keys and the hosted MCP server (reveal_contact, get_account, list_reveals).

Privacy · Opt out of listing