# ListKit API

> The public, customer-facing REST API for ListKit: search, orders, verification, campaigns, exclude lists and billing, over the same account data as the web app.

## Connect via MCP

AI clients (Claude, ChatGPT, Cursor) use the same account through the MCP server. How to connect one and sign in: [Connect via MCP](/docs/mcp).

## Guides
- [Quick start](https://developer.listkit.io/docs/guides/quickstart)
- [Authentication](https://developer.listkit.io/docs/guides/auth)
- [Rate limits](https://developer.listkit.io/docs/guides/limits)
- [Errors](https://developer.listkit.io/docs/guides/errors)
- [MCP server](https://developer.listkit.io/docs/guides/mcp)
- [Account, team and onboarding](https://developer.listkit.io/docs/guides/account)
- [Search](https://developer.listkit.io/docs/guides/search)
- [AI search](https://developer.listkit.io/docs/guides/ai-search)
- [Orders](https://developer.listkit.io/docs/guides/orders)
- [Exclusions (do-not-contact)](https://developer.listkit.io/docs/guides/exclusions)
- [Email verification](https://developer.listkit.io/docs/guides/verifications)
- [Enrichment](https://developer.listkit.io/docs/guides/enrichment)
- [Workflows](https://developer.listkit.io/docs/guides/workflows)
- [Campaigns](https://developer.listkit.io/docs/guides/campaigns)
- [Leads](https://developer.listkit.io/docs/guides/leads)
- [Mailboxes and domains](https://developer.listkit.io/docs/guides/mailboxes)
- [Master inbox](https://developer.listkit.io/docs/guides/inbox)
- [Webhooks](https://developer.listkit.io/docs/guides/webhooks)
- [Billing](https://developer.listkit.io/docs/guides/billing)

## Reference
- [OpenAPI spec](https://developer.listkit.io/openapi.json)
- [Interactive docs](https://developer.listkit.io/docs)

## Endpoints by resource

### Account
- [Full reference](https://developer.listkit.io/docs/account.md)
  - `GET /v1/me` — Get the current account
  - `GET /v1/team` — List team members
  - `POST /v1/team/invite` — Invite a team member
  - `DELETE /v1/team/invitations/{id}` — Cancel a team invitation
  - `DELETE /v1/team/{user_id}` — Remove a team member
  - `GET /v1/onboarding` — Get onboarding status

### AI Search
- [Full reference](https://developer.listkit.io/docs/ai-search.md)
  - `POST /v1/ai-search/audience` — Build an audience from a description
  - `POST /v1/ai-search/audience/refine` — Refine an audience
  - `POST /v1/ai-search/audience/from-domain` — Suggest an audience from a website
  - `POST /v1/ai-search/filters` — Turn a plain-English request into filters

### Billing
- [Full reference](https://developer.listkit.io/docs/billing.md)
  - `GET /v1/billing/summary` — Get the billing summary
  - `GET /v1/billing/subscriptions` — List subscriptions
  - `GET /v1/billing/credits/history` — List credit history
  - `GET /v1/billing/plans` — Get plan and top-up pricing
  - `GET /v1/billing/allowance` — Get this period's usage allowance
  - `POST /v1/billing/checkout/bundle-set` — Start a checkout for a bundle set
  - `POST /v1/billing/checkout/credit-topup` — Start a checkout for a credit top-up
  - `POST /v1/billing/portal` — Open a billing portal session

### Campaigns
- [Full reference](https://developer.listkit.io/docs/campaigns.md)
  - `GET /v1/campaigns` — List campaigns
  - `POST /v1/campaigns` — Create a campaign
  - `PUT /v1/campaigns/{id}` — Rename a campaign
  - `DELETE /v1/campaigns/{id}` — Delete a campaign
  - `POST /v1/campaigns/{id}/duplicate` — Duplicate a campaign
  - `GET /v1/campaigns/{id}/sequence` — Get a campaign's email sequence
  - `PUT /v1/campaigns/{id}/sequence` — Replace a campaign's email sequence
  - `POST /v1/campaigns/{id}/schedule` — Set a campaign's sending schedule
  - `POST /v1/campaigns/{id}/senders` — Set a campaign's sending mailboxes
  - `POST /v1/campaigns/{id}/status` — Start, pause or stop a campaign
  - `POST /v1/campaigns/{id}/settings` — Update a campaign's settings
  - `GET /v1/campaigns/{id}/credits-info` — Get a campaign's credit needs
  - `POST /v1/campaigns/{id}/ai/writer` — Write a campaign sequence with AI
  - `POST /v1/campaigns/{id}/ai/spintax` — Add spintax to a campaign sequence
  - `GET /v1/campaigns/{id}/analytics/overall` — Get a campaign's overall analytics
  - `GET /v1/campaigns/{id}/analytics/day-wise` — Get a campaign's daily analytics

### Enrichment
- [Full reference](https://developer.listkit.io/docs/enrichment.md)
  - `GET /v1/enrichment/jobs` — List enrichment jobs
  - `POST /v1/enrichment/jobs` — Upload a CSV as an enrichment job
  - `POST /v1/enrichment/jobs/{job_id}/start` — Start an enrichment job
  - `GET /v1/enrichment/jobs/{job_id}` — Get an enrichment job
  - `DELETE /v1/enrichment/jobs/{job_id}` — Delete an enrichment job
  - `GET /v1/enrichment/jobs/{job_id}/rows` — List an enrichment job's rows
  - `GET /v1/enrichment/jobs/{job_id}/rows/{row_index}` — Get one row of an enrichment job
  - `GET /v1/enrichment/jobs/{job_id}/download` — Download an enrichment job's CSV
  - `GET /v1/enrichment/jobs/{job_id}/download-link` — Get a download link for an enrichment job's CSV
  - `GET /v1/enrichment/prices` — Get enrichment prices per field

### Exclusions
- [Full reference](https://developer.listkit.io/docs/exclusions.md)
  - `GET /v1/exclusions` — List exclusions
  - `POST /v1/exclusions` — Add exclusions
  - `DELETE /v1/exclusions` — Remove exclusions
  - `POST /v1/exclusions/check` — Check contacts against the exclude list
  - `GET /v1/exclude-lists` — List exclude lists
  - `POST /v1/exclude-lists` — Create an exclude list
  - `GET /v1/exclude-lists/{id}` — Get an exclude list
  - `DELETE /v1/exclude-lists/{id}` — Delete an exclude list
  - `POST /v1/exclude-lists/{id}/import` — Import a CSV into an exclude list
  - `GET /v1/exclude-lists/{id}/export` — Export an exclude list as CSV

### Inbox
- [Full reference](https://developer.listkit.io/docs/inbox.md)
  - `GET /v1/inbox/folders` — List inbox folders
  - `GET /v1/inbox/threads` — List inbox threads
  - `GET /v1/inbox/threads/{thread_id}/messages` — List an inbox thread's messages
  - `POST /v1/inbox/threads/{thread_id}/reply` — Reply to an inbox thread
  - `POST /v1/inbox/threads/{thread_id}/forward` — Forward an inbox thread

### Keys
- [Full reference](https://developer.listkit.io/docs/keys.md)
  - `GET /v1/keys` — List API keys
  - `POST /v1/keys` — Create an API key
  - `GET /v1/keys/{id}` — Get an API key
  - `PATCH /v1/keys/{id}` — Rename an API key or change its scopes
  - `DELETE /v1/keys/{id}` — Revoke an API key
  - `POST /v1/keys/{id}/rotate` — Rotate an API key

### Leads
- [Full reference](https://developer.listkit.io/docs/leads.md)
  - `GET /v1/leads` — List leads
  - `DELETE /v1/leads` — Delete leads
  - `GET /v1/leads/categories` — List lead categories
  - `PUT /v1/leads/category` — Set the category of leads
  - `POST /v1/leads/export` — Export leads as CSV
  - `POST /v1/leads/import-from-orders` — Import an order's contacts as leads
  - `POST /v1/leads/campaigns/{campaign_id}/imports` — Import a CSV of leads into a campaign
  - `GET /v1/leads/imports/{file_id}` — Get a lead import's status

### Mailboxes
- [Full reference](https://developer.listkit.io/docs/mailboxes.md)
  - `GET /v1/mailboxes` — List connected mailboxes
  - `POST /v1/mailboxes` — Connect an SMTP/IMAP mailbox
  - `DELETE /v1/mailboxes/{id}` — Remove a mailbox
  - `POST /v1/mailboxes/import` — Import mailboxes from a CSV
  - `GET /v1/mailboxes/import/{id}` — Get a mailbox CSV import's status
  - `GET /v1/mailboxes/oauth/google` — Get a URL to connect a Gmail mailbox
  - `GET /v1/mailboxes/oauth/microsoft` — Get a URL to connect an Outlook mailbox
  - `POST /v1/mailboxes/warmup` — Turn warmup on or off for mailboxes
  - `POST /v1/mailboxes/signature` — Set the signature on mailboxes
  - `POST /v1/mailboxes/daily-limit` — Set the daily send limit on mailboxes
  - `POST /v1/mailboxes/restart-ramp` — Restart the warmup send ramp for mailboxes
  - `GET /v1/mailboxes/domains` — List purchased sending domains
  - `GET /v1/mailboxes/domains/stats` — Get domain and inbox counts
  - `GET /v1/mailboxes/domains/provisioning-status` — Get domain provisioning status
  - `GET /v1/mailboxes/domains/orders` — List domain and inbox purchase orders
  - `POST /v1/mailboxes/domains/orders` — Draft a branded domain order
  - `POST /v1/mailboxes/domains/search` — Search new domain names to buy
  - `POST /v1/mailboxes/domains/orders/{id}/confirm` — Confirm a branded domain order
  - `GET /v1/mailboxes/domains/pool/availability` — Check pre-warmed domain availability
  - `GET /v1/mailboxes/domains/pool/domains` — List pre-warmed domains to claim
  - `GET /v1/mailboxes/domains/pool/claims` — List pre-warmed domain claims
  - `POST /v1/mailboxes/domains/pool/claims` — Claim pre-warmed domains

### Orders
- [Full reference](https://developer.listkit.io/docs/orders.md)
  - `POST /v1/orders/estimate` — Estimate how many contacts an order can deliver
  - `GET /v1/orders` — List orders
  - `POST /v1/orders` — Create an order
  - `GET /v1/orders/pricing` — Get credit pricing per field
  - `POST /v1/orders/unlock` — Unlock fields on records already seen
  - `GET /v1/orders/{id}` — Get an order
  - `PATCH /v1/orders/{id}` — Rename an order
  - `POST /v1/orders/{id}/stop` — Stop an order
  - `GET /v1/orders/{id}/download` — Download an order's contacts as CSV
  - `GET /v1/orders/{id}/contacts` — List an order's delivered contacts

### Search
- [Full reference](https://developer.listkit.io/docs/search.md)
  - `POST /v1/search/people` — Search people
  - `POST /v1/search/companies` — Search companies
  - `POST /v1/search/counts` — Count people and companies matching filters
  - `POST /v1/search/analytics/{metric}` — Break down search matches by a facet
  - `GET /v1/search/filters` — List saved search filters
  - `POST /v1/search/filters` — Save a search filter
  - `DELETE /v1/search/filters/{id}` — Delete a saved search filter
  - `GET /v1/search/values` — Find filter values
  - `GET /v1/search/topics` — List intent topics
  - `POST /v1/search/topics/suggest` — Suggest intent topics
  - `POST /v1/search/job-titles/suggest` — Suggest job titles
  - `GET /v1/search/shares` — List shared filters
  - `POST /v1/search/shares` — Share a saved filter or an order’s filters
  - `POST /v1/search/shares/accept` — Accept a shared filter
  - `POST /v1/search/shares/{id}/email` — Email a share link
  - `DELETE /v1/search/shares/{id}` — Delete a share link

### Uploads
- [Full reference](https://developer.listkit.io/docs/uploads.md)
  - `POST /v1/uploads` — Create an upload link

### Usage
- [Full reference](https://developer.listkit.io/docs/usage.md)
  - `GET /v1/usage` — Get current rate-limit usage

### Verifications
- [Full reference](https://developer.listkit.io/docs/verifications.md)
  - `POST /v1/verifications` — Verify an email address
  - `POST /v1/verifications/lists` — Verify a list of email addresses
  - `GET /v1/verifications/files` — List verification files
  - `POST /v1/verifications/files` — Upload a file of emails to verify
  - `GET /v1/verifications/files/{file_id}` — Get a verification file
  - `DELETE /v1/verifications/files/{file_id}` — Delete a verification file
  - `GET /v1/verifications/files/{file_id}/download` — Download a verification file's results
  - `GET /v1/verifications/files/{file_id}/download-link` — Get a download link for a verification file's results

### Webhooks
- [Full reference](https://developer.listkit.io/docs/webhooks.md)
  - `GET /v1/webhooks/endpoints` — List webhook endpoints
  - `POST /v1/webhooks/endpoints` — Create a webhook endpoint
  - `PUT /v1/webhooks/endpoints/{endpoint_id}` — Update a webhook endpoint
  - `DELETE /v1/webhooks/endpoints/{endpoint_id}` — Delete a webhook endpoint
  - `POST /v1/webhooks/endpoints/{endpoint_id}/rotate-secret` — Rotate a webhook endpoint's signing secret
  - `POST /v1/webhooks/endpoints/{endpoint_id}/test` — Send a test webhook
  - `GET /v1/webhooks/endpoints/{endpoint_id}/deliveries` — List a webhook endpoint's deliveries
  - `POST /v1/webhooks/deliveries/{delivery_id}/retry` — Retry a webhook delivery

### Workflows
- [Full reference](https://developer.listkit.io/docs/workflows.md)
  - `GET /v1/workflows` — List workflows
  - `POST /v1/workflows` — Create a workflow
  - `GET /v1/workflows/{id}` — Get a workflow
  - `PUT /v1/workflows/{id}` — Replace a workflow
  - `DELETE /v1/workflows/{id}` — Delete a workflow
  - `POST /v1/workflows/{id}/pause` — Pause a workflow
  - `POST /v1/workflows/{id}/unpause` — Resume a paused workflow
  - `GET /v1/workflows/{id}/runs` — List a workflow's runs