API reference.
The LeadVector REST API lives at https://api.leadvector.app/v1. Every request carries your access key in the x-api-key header, and every response is JSON. Data, campaigns, leads, mailboxes, and the inbox are all here.
Authentication
Create your access key under Account, API key in the app, where you can also see its usage analytics. Each user has one key. The raw key is shown once, on creation; LeadVector stores only a hash of it. Send it as the x-api-key header on every request.
One key per user, with usage analytics
Sent as the x-api-key header
Calls are isolated per key
GET
/v1/auth/me
Validate an access key and return the account it belongs to.
GET /v1/auth/me
cURL
curl https://api.leadvector.app/v1/auth/me \ -H "x-api-key: $LEADVECTOR_API_KEY"
Response · 200 OK
{ "success": true, "message": "SUCCESS", "data": { "authenticated": true, "userId": 42 } }
Rate limits and credits
Data lookups (find-email, find-mobile, verify-email, and reverse-email-lookup) allow 5 requests per second per access key, with short bursts of up to 20. Campaign, lead, inbox, and mailbox endpoints allow 120 requests per minute per key. Across all of an account’s keys, the total is capped at 10 requests per second. Limits use a token bucket that refills continuously. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Window headers, and a 429 response includes Retry-After, so a client can back off before it is refused.
Data endpoints use the same credit pool as the app and your team. A credit is used only when a valid result comes back. Lookups run live across multiple providers, and results are saved to the contact, so repeating a lookup does not cost another credit.
Data
The four finder and verification calls behave exactly as they do in the app. Results are found in real time, verified, saved to the contact, and only charged when valid.
POST
/v1/find-email
Find a verified work email from a full name and a company domain.
Body: fullName, domain
POST
/v1/find-mobile
Find a mobile number from a LinkedIn profile URL.
Body: linkedinUrl
POST
/v1/verify-email
Verify an email address against DNS and the mail server.
Body: email
POST
/v1/reverse-email-lookup
Resolve an email address to the LinkedIn profile of the person behind it.
Body: email
POST /v1/find-email
cURL
curl -X POST https://api.leadvector.app/v1/find-email \ -H "x-api-key: $LEADVECTOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "fullName": "Emily Turner", "domain": "lumenanalytics.com" }'
Response · 200 OK
{ "success": true, "message": "EMAIL_RESULT", "data": [{ "uuid": "3f6d2c1e-8b7a-4f0e-9c2d-1a5b7e9f4c21", "email": "emily@lumenanalytics.com", "firstName": "Emily", "lastName": "Turner", "domain": "lumenanalytics.com", "emailStatus": "valid" }] }
Campaigns
Create and manage campaigns and the sequence steps inside them. Campaigns are addressed by uuid.
GET
/v1/campaigns
List campaigns, newest first.
Query: page, limit, search, campaignStatus
POST
/v1/campaigns
Create a campaign.
Body: name
GET
/v1/campaigns/:uuid
Read one campaign with its settings and counts.
PATCH
/v1/campaigns/:uuid
Rename a campaign, or soft-delete it with status false.
Body: name, status
DELETE
/v1/campaigns/:uuid
Archive a campaign.
GET
/v1/campaigns/:uuid/sequences
List the sequence steps of a campaign.
POST
/v1/campaigns/:uuid/sequences
Add sequence steps, in order.
Body: steps[]
Leads
Leads belong to a campaign. Upsert one lead with its custom variables, or add many at once.
GET
/v1/leads/:uuid
List the leads of a campaign.
Query: page, limit, search
POST
/v1/leads/:uuid
Create or update one lead by email, with optional custom variables.
Body: email, firstName, lastName, companyName, pauseUntil, variables[]
POST
/v1/leads/:uuid/manual
Add a batch of leads, optionally skipping duplicates.
Body: leads[], skipDuplicates
POST /v1/leads/:uuid
cURL
curl -X POST https://api.leadvector.app/v1/leads/019e8eb2-a04a-76a8-8aed-37178d5786f5 \ -H "x-api-key: $LEADVECTOR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "emily@lumenanalytics.com", "firstName": "Emily", "lastName": "Turner", "companyName": "Lumen Analytics", "variables": [{ "name": "jobTitle", "value": "Head of Sales" }] }'
Response · 200 OK
{ "success": true, "message": "SUCCESS", "data": { ...the lead as stored } }
Email accounts
The mailboxes you have connected, their warmup settings, and their health. Mailboxes are addressed by numeric id.
GET
/v1/email-accounts
List connected mailboxes with warmup status and health.
GET
/v1/email-accounts/:mailboxId
Read one mailbox with its counters and health score.
PATCH
/v1/email-accounts/:mailboxId/settings
Update warmup settings.
Body: displayName, dailyLimit, hourlyLimit, warmupDay, status
PATCH
/v1/email-accounts/:mailboxId/pause
Pause warmup for a mailbox.
PATCH
/v1/email-accounts/:mailboxId/resume
Resume warmup for a mailbox.
DELETE
/v1/email-accounts/:mailboxId/disconnect
Disconnect a mailbox and keep its record.
DELETE
/v1/email-accounts/:mailboxId
Delete a mailbox.
Inbox
Everything Unibox shows: conversations across every connected mailbox, matched to their campaign and lead.
GET
/v1/inbox
List conversations.
Query: tab, mailbox, mailboxId, status, search, read, archived, campaignUuid
GET
/v1/inbox/:id
Read one conversation with its messages.
PATCH
/v1/inbox/:id
Update lead status, tab, read or archived state, reminder, or schedule.
Body: status, tab, archived, read, reminderAt, scheduled
POST
/v1/inbox/mailbox-sync/:id
Synchronise a mailbox now.
POST
/v1/inbox/messages/:id/forward
Forward a message with an optional note.
Body: toEmails[], ccEmails[], bccEmails[], note
Responses and errors
Every response is a JSON object with success, message, and data. Standard HTTP status codes tell you what went wrong: 400 for an invalid request, 401 for a missing or invalid access key, 403 with INSUFFICIENT_CREDITS when the account has run out of credits, 404 when the record does not exist, 429 when a rate limit is hit, and 5xx for a server-side problem.
The CLI is a client of this API and exposes the same actions with structured output. If something in this reference does not match what you see, email support@leadvector.app and we will fix it.