ShopLeads API and MCP
Search stores and the people who run them from your own code or from an AI agent. The REST API and the MCP server use the same keys, filters, credits and limits as the app. Create a key in the app under API & MCP.
Search is free. Credits only on unlock. search_stores, search_people, count_stores, get_store, search_products and preview_unlock never reveal a contact and never spend a credit: emails, phones and LinkedIn come back masked, with credits_used: 0 and a note on what can be unlocked. Only unlock_contacts spends credits, once per person and kind, and only when that contact exists. Run preview_unlock first to see the exact cost. Searches read the live database of AI-confirmed DTC stores; a filter with no live equivalent reads the sample index, and the answer says source: "sample".
curl -H "Authorization: Bearer sd_live_…" "https://api.shopleads.io/api/v1/stores?dtc=true&band=1M-10M&signals=product_launch&page_size=10"
claude mcp add --transport http shopleads https://api.shopleads.io/mcp --header "Authorization: Bearer sd_live_…"
Limits: 60 calls a minute and 600 an hour per account, shared by REST and MCP. Pages hold up to 50 rows; follow next_cursor. Unlocks are priced per kind: email 2 credits, phone 5, LinkedIn profile 2; anything you already unlocked is free. Signals come with every detail on Pro and Scale; other plans get counts per kind. A misspelt filter or a bad value is refused with the valid options.
search_stores
Free: never reveals a contact and never spends credits. Search AI-confirmed DTC stores in the live database. Returns one page and a next_cursor. sells= keeps stores with a product matching every word.
GET /api/v1/stores POST /api/v1/stores/search MCP tool search_stores
| Filter | Type | What it does |
|---|---|---|
q | string | Words in the name, domain, description, keywords, apps or tools |
domains | list | Exact store domains |
vertical | list | Any of these verticals apparel_accessories, arts_crafts_hobbies, auto_vehicles, baby_kids_toys, beauty_personal_care, electronics_tech, food_beverage, general_merchandise, gifts_party_flowers, health_wellness, home_garden, industrial_business, not_applicable, other_products, pets, sports_outdoors |
band | list | Monthly sales band 10k-100k, 100k-1M, 1M-10M, 10M+ |
min_sales | int | Monthly sales at least, USD |
max_sales | int | Monthly sales at most, USD |
platform | list | Any of these platforms 3dcart, bigcommerce, bvcommerce, centra, commerce7, commercev3, custom, demandware, drupal, dukaan, easydigital, ecbeing, ecwid, fbits, godaddy, hcl, idosell, ikas, lightspeed, magento, makeshop, miva, nop, orderport … |
country | list | Any of these countries (ISO code) AE, AT, AU, BE, BM, BR, CA, CH, CL, CN, CZ, DE, DK, DZ, EG, ES, FI, FR, GB, GG, HK, ID, IE, IN … |
dtc | bool | true: real DTC brands only; false: everything else |
own_stores | bool | Runs its own physical stores |
online_only | bool | Site scan worked and found no physical stores |
in_retailers | bool | Sold through other retailers (stockists, wholesale) |
tools | list | Every one of these apps or technologies is installed (exact names) |
gaps | list | Every one of these tech gaps no email/SMS platform, no SMS, no reviews app, no subscriptions, no loyalty, no helpdesk, no upsell |
signals | list | Has at least one signal of each kind (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
signals_any | list | Has a signal of at least one of these kinds (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
traits | list | Has every one of these standing store traits (open on every plan) affiliate_program, multi_market, press_mentions, subscription_offer, wholesale_program |
sells | string | Sells a product matching every one of these words (product title, type, tags or description) |
min_followers | int | Social followers at least, all networks together |
has_dm_email | bool | A decision-maker has a work email |
has_mobile | bool | Someone has a mobile number |
category | list | Store category, any of these (top-level e-commerce category, e.g. Apparel, Sports, Beauty & Fitness, Food & Drink, Home & Garden) |
socials | list | Has a profile on every one of these networks instagram, facebook, tiktok, youtube, pinterest, x, linkedin |
min_apps | int | Installed apps at least |
max_apps | int | Installed apps at most |
founder_found | bool | true: the owner or founder is among the people found |
price_tier | list | Price tier: any of these (brand profile) budget, mid, premium, luxury |
purchase_cycle | list | Purchase cycle: any of these (brand profile) one_time, occasional, replenishable |
audience_gender | list | Audience: any of these (brand profile) women, men, unisex, kids |
audience_life_stage | list | Life stage: any of these (brand profile) kids, teens, adults, parents, seniors, pets |
sales_model | list | Sales model: any of these (brand profile) subscription, bundles, made_to_order, personalized, wholesale, gifting |
channels | list | Channels: any of these (brand profile) own_store_only, amazon, retail_stockists, own_retail_stores, marketplaces |
regulated | list | Regulated: any of these (brand profile) alcohol, cbd_hemp, supplements, tobacco_vape, firearms, adult, none |
seasonality | list | Seasonality: any of these (brand profile) holiday_q4, summer, back_to_school, valentines, mothers_fathers_day, none |
best_fit_vendors | list | Best-fit vendors: any of these (brand profile) email_sms_agency, paid_social_agency, influencer_ugc, seo_content, cro_web, 3pl_fulfillment, subscription_app, reviews_ugc_app, wholesale_platform, packaging, product_photography, retail_distribution |
sort | string | sales (default), fit, signals or name. Sorting reads the sample index. sales, fit, signals, name |
source | string | live (default): the live database; sample: the sample index. Filters with no live equivalent read the sample and say so. live, sample |
page_size | int | Rows per page, 1-50 |
cursor | cursor | next_cursor from the previous page |
count_stores
Free: never reveals a contact and never spends credits. Count the stores that match, without returning rows: the live database's exact count when it finishes within about 25 seconds (exact: true), else its estimate (exact: false). Filters the live database cannot answer count the sample index instead (source: sample).
GET /api/v1/stores/count POST /api/v1/stores/count MCP tool count_stores
| Filter | Type | What it does |
|---|---|---|
q | string | Words in the name, domain, description, keywords, apps or tools |
domains | list | Exact store domains |
vertical | list | Any of these verticals apparel_accessories, arts_crafts_hobbies, auto_vehicles, baby_kids_toys, beauty_personal_care, electronics_tech, food_beverage, general_merchandise, gifts_party_flowers, health_wellness, home_garden, industrial_business, not_applicable, other_products, pets, sports_outdoors |
band | list | Monthly sales band 10k-100k, 100k-1M, 1M-10M, 10M+ |
min_sales | int | Monthly sales at least, USD |
max_sales | int | Monthly sales at most, USD |
platform | list | Any of these platforms 3dcart, bigcommerce, bvcommerce, centra, commerce7, commercev3, custom, demandware, drupal, dukaan, easydigital, ecbeing, ecwid, fbits, godaddy, hcl, idosell, ikas, lightspeed, magento, makeshop, miva, nop, orderport … |
country | list | Any of these countries (ISO code) AE, AT, AU, BE, BM, BR, CA, CH, CL, CN, CZ, DE, DK, DZ, EG, ES, FI, FR, GB, GG, HK, ID, IE, IN … |
dtc | bool | true: real DTC brands only; false: everything else |
own_stores | bool | Runs its own physical stores |
online_only | bool | Site scan worked and found no physical stores |
in_retailers | bool | Sold through other retailers (stockists, wholesale) |
tools | list | Every one of these apps or technologies is installed (exact names) |
gaps | list | Every one of these tech gaps no email/SMS platform, no SMS, no reviews app, no subscriptions, no loyalty, no helpdesk, no upsell |
signals | list | Has at least one signal of each kind (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
signals_any | list | Has a signal of at least one of these kinds (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
traits | list | Has every one of these standing store traits (open on every plan) affiliate_program, multi_market, press_mentions, subscription_offer, wholesale_program |
sells | string | Sells a product matching every one of these words (product title, type, tags or description) |
min_followers | int | Social followers at least, all networks together |
has_dm_email | bool | A decision-maker has a work email |
has_mobile | bool | Someone has a mobile number |
category | list | Store category, any of these (top-level e-commerce category, e.g. Apparel, Sports, Beauty & Fitness, Food & Drink, Home & Garden) |
socials | list | Has a profile on every one of these networks instagram, facebook, tiktok, youtube, pinterest, x, linkedin |
min_apps | int | Installed apps at least |
max_apps | int | Installed apps at most |
founder_found | bool | true: the owner or founder is among the people found |
price_tier | list | Price tier: any of these (brand profile) budget, mid, premium, luxury |
purchase_cycle | list | Purchase cycle: any of these (brand profile) one_time, occasional, replenishable |
audience_gender | list | Audience: any of these (brand profile) women, men, unisex, kids |
audience_life_stage | list | Life stage: any of these (brand profile) kids, teens, adults, parents, seniors, pets |
sales_model | list | Sales model: any of these (brand profile) subscription, bundles, made_to_order, personalized, wholesale, gifting |
channels | list | Channels: any of these (brand profile) own_store_only, amazon, retail_stockists, own_retail_stores, marketplaces |
regulated | list | Regulated: any of these (brand profile) alcohol, cbd_hemp, supplements, tobacco_vape, firearms, adult, none |
seasonality | list | Seasonality: any of these (brand profile) holiday_q4, summer, back_to_school, valentines, mothers_fathers_day, none |
best_fit_vendors | list | Best-fit vendors: any of these (brand profile) email_sms_agency, paid_social_agency, influencer_ugc, seo_content, cro_web, 3pl_fulfillment, subscription_app, reviews_ugc_app, wholesale_platform, packaging, product_photography, retail_distribution |
sort | string | sales (default), fit, signals or name. Sorting reads the sample index. sales, fit, signals, name |
source | string | live (default): the live database; sample: the sample index. Filters with no live equivalent read the sample and say so. live, sample |
page_size | int | Rows per page, 1-50 |
cursor | cursor | next_cursor from the previous page |
count_people
Free: never reveals a contact and never spends credits. Count the people that match, without returning rows: the live database's exact count when it finishes within about 25 seconds (exact: true). Broad searches may not finish; narrow them for an exact number.
GET /api/v1/people/count POST /api/v1/people/count MCP tool count_people
| Filter | Type | What it does |
|---|---|---|
q | string | Words in the name, title or store name |
domains | list | Store: exact store domains |
vertical | list | Store: any of these verticals apparel_accessories, arts_crafts_hobbies, auto_vehicles, baby_kids_toys, beauty_personal_care, electronics_tech, food_beverage, general_merchandise, gifts_party_flowers, health_wellness, home_garden, industrial_business, not_applicable, other_products, pets, sports_outdoors |
band | list | Store: monthly sales band 10k-100k, 100k-1M, 1M-10M, 10M+ |
min_sales | int | Store: monthly sales at least, USD |
max_sales | int | Store: monthly sales at most, USD |
platform | list | Store: any of these platforms 3dcart, bigcommerce, bvcommerce, centra, commerce7, commercev3, custom, demandware, drupal, dukaan, easydigital, ecbeing, ecwid, fbits, godaddy, hcl, idosell, ikas, lightspeed, magento, makeshop, miva, nop, orderport … |
country | list | Store: any of these countries (ISO code) AE, AT, AU, BE, BM, BR, CA, CH, CL, CN, CZ, DE, DK, DZ, EG, ES, FI, FR, GB, GG, HK, ID, IE, IN … |
dtc | bool | Store: true: real DTC brands only; false: everything else |
own_stores | bool | Store: runs its own physical stores |
online_only | bool | Store: site scan worked and found no physical stores |
in_retailers | bool | Store: sold through other retailers (stockists, wholesale) |
tools | list | Store: every one of these apps or technologies is installed (exact names) |
gaps | list | Store: every one of these tech gaps no email/SMS platform, no SMS, no reviews app, no subscriptions, no loyalty, no helpdesk, no upsell |
signals | list | Store: has at least one signal of each kind (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
signals_any | list | Store: has a signal of at least one of these kinds (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
traits | list | Store: has every one of these standing store traits (open on every plan) affiliate_program, multi_market, press_mentions, subscription_offer, wholesale_program |
sells | string | Store: sells a product matching every one of these words (product title, type, tags or description) |
min_followers | int | Store: social followers at least, all networks together |
category | list | Store: store category, any of these (top-level e-commerce category, e.g. Apparel, Sports, Beauty & Fitness, Food & Drink, Home & Garden) |
socials | list | Store: has a profile on every one of these networks instagram, facebook, tiktok, youtube, pinterest, x, linkedin |
min_apps | int | Store: installed apps at least |
max_apps | int | Store: installed apps at most |
founder_found | bool | Store: true: the owner or founder is among the people found |
price_tier | list | Store: price tier: any of these (brand profile) budget, mid, premium, luxury |
purchase_cycle | list | Store: purchase cycle: any of these (brand profile) one_time, occasional, replenishable |
audience_gender | list | Store: audience: any of these (brand profile) women, men, unisex, kids |
audience_life_stage | list | Store: life stage: any of these (brand profile) kids, teens, adults, parents, seniors, pets |
sales_model | list | Store: sales model: any of these (brand profile) subscription, bundles, made_to_order, personalized, wholesale, gifting |
channels | list | Store: channels: any of these (brand profile) own_store_only, amazon, retail_stockists, own_retail_stores, marketplaces |
regulated | list | Store: regulated: any of these (brand profile) alcohol, cbd_hemp, supplements, tobacco_vape, firearms, adult, none |
seasonality | list | Store: seasonality: any of these (brand profile) holiday_q4, summer, back_to_school, valentines, mothers_fathers_day, none |
best_fit_vendors | list | Store: best-fit vendors: any of these (brand profile) email_sms_agency, paid_social_agency, influencer_ugc, seo_content, cro_web, 3pl_fulfillment, subscription_app, reviews_ugc_app, wholesale_platform, packaging, product_photography, retail_distribution |
seniority | list | Any of these levels: owner_founder, c_suite, vp, head_director, manager, other owner_founder, c_suite, vp, head_director, manager, other |
department | list | Any of these departments (the broad list) executive, ecommerce, growth_performance, marketing, customer_experience, operations_supply_chain, sales_wholesale, product, creative_brand, technology, finance, people_hr, other |
departments | list | Any of these departments from the finer list of about 30 (sales apart from wholesale, founders and owners, ecommerce, retention …); the keys are in GET /api/v1 under departments |
title | string | Title holds every one of these words |
titles | list | Title holds any one of these phrases, e.g. founder, head of ecommerce, VP marketing (up to 25) |
exclude_titles | list | Leave out titles holding any of these phrases, e.g. assistant, intern (up to 25) |
location | string | Location holds this text (city, region or country) |
person_country | list | Where the person is, ISO code (US, GB, CA …) |
dm | bool | Decision-makers only |
has_email | bool | Has a work email |
email_tier | list | Email checked by a verifier (verified) or catch-all and not confirmed (unconfirmed) verified, unconfirmed |
has_mobile | bool | Has a mobile number |
has_direct | bool | Has a direct dial |
has_linkedin | bool | Has a LinkedIn profile |
started_within_days | int | Started the current role within this many days (Pro and Scale) |
sort | string | seniority (default), name, store or role_start (newest first). Sorting reads the sample index. seniority, name, store, role_start |
source | string | live (default): the live database; sample: the sample index. Filters with no live equivalent read the sample and say so. live, sample |
page_size | int | Rows per page, 1-50 |
cursor | cursor | next_cursor from the previous page |
get_store
Free: never reveals a contact and never spends credits. One store: details, socials, tools, personalization variables, people with contacts masked, and signals (Pro and Scale). Pass company_id from search_stores or search_people for the live record (REST: GET /api/v1/stores/<company_id>), or a domain.
GET /api/v1/stores/:domain MCP tool get_store
| Filter | Type | What it does |
|---|---|---|
domain | string | Store domain |
company_id | string | company_id from search_stores or search_people (live record) |
source | string | live (default): the live database; sample: the sample index. Filters with no live equivalent read the sample and say so. live, sample |
search_people
Free: never reveals a contact and never spends credits. Search people at AI-confirmed DTC stores in the live database: store filters plus seniority, department, titles (any of several, or leave some out), location, contact and role-start filters. Emails, phones and LinkedIn stay masked; each row says what can be unlocked.
POST /api/v1/people/search GET /api/v1/people GET /api/v1/people/search MCP tool search_people
| Filter | Type | What it does |
|---|---|---|
q | string | Words in the name, title or store name |
domains | list | Store: exact store domains |
vertical | list | Store: any of these verticals apparel_accessories, arts_crafts_hobbies, auto_vehicles, baby_kids_toys, beauty_personal_care, electronics_tech, food_beverage, general_merchandise, gifts_party_flowers, health_wellness, home_garden, industrial_business, not_applicable, other_products, pets, sports_outdoors |
band | list | Store: monthly sales band 10k-100k, 100k-1M, 1M-10M, 10M+ |
min_sales | int | Store: monthly sales at least, USD |
max_sales | int | Store: monthly sales at most, USD |
platform | list | Store: any of these platforms 3dcart, bigcommerce, bvcommerce, centra, commerce7, commercev3, custom, demandware, drupal, dukaan, easydigital, ecbeing, ecwid, fbits, godaddy, hcl, idosell, ikas, lightspeed, magento, makeshop, miva, nop, orderport … |
country | list | Store: any of these countries (ISO code) AE, AT, AU, BE, BM, BR, CA, CH, CL, CN, CZ, DE, DK, DZ, EG, ES, FI, FR, GB, GG, HK, ID, IE, IN … |
dtc | bool | Store: true: real DTC brands only; false: everything else |
own_stores | bool | Store: runs its own physical stores |
online_only | bool | Store: site scan worked and found no physical stores |
in_retailers | bool | Store: sold through other retailers (stockists, wholesale) |
tools | list | Store: every one of these apps or technologies is installed (exact names) |
gaps | list | Store: every one of these tech gaps no email/SMS platform, no SMS, no reviews app, no subscriptions, no loyalty, no helpdesk, no upsell |
signals | list | Store: has at least one signal of each kind (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
signals_any | list | Store: has a signal of at least one of these kinds (Pro and Scale) app_installed, tech_installed, product_launch, catalog_growth, plan_change, replatform, new_store, new_in_role, hiring, headcount_growth, google_ads, funding, sale_live, sale_timer, stale_promo, markdowns_live, free_shipping_offer, shipping_delay, bad_reviews, meta_ads_live, meta_ads_burst, meta_ads_stopped, meta_ads, new_advertiser … |
traits | list | Store: has every one of these standing store traits (open on every plan) affiliate_program, multi_market, press_mentions, subscription_offer, wholesale_program |
sells | string | Store: sells a product matching every one of these words (product title, type, tags or description) |
min_followers | int | Store: social followers at least, all networks together |
category | list | Store: store category, any of these (top-level e-commerce category, e.g. Apparel, Sports, Beauty & Fitness, Food & Drink, Home & Garden) |
socials | list | Store: has a profile on every one of these networks instagram, facebook, tiktok, youtube, pinterest, x, linkedin |
min_apps | int | Store: installed apps at least |
max_apps | int | Store: installed apps at most |
founder_found | bool | Store: true: the owner or founder is among the people found |
price_tier | list | Store: price tier: any of these (brand profile) budget, mid, premium, luxury |
purchase_cycle | list | Store: purchase cycle: any of these (brand profile) one_time, occasional, replenishable |
audience_gender | list | Store: audience: any of these (brand profile) women, men, unisex, kids |
audience_life_stage | list | Store: life stage: any of these (brand profile) kids, teens, adults, parents, seniors, pets |
sales_model | list | Store: sales model: any of these (brand profile) subscription, bundles, made_to_order, personalized, wholesale, gifting |
channels | list | Store: channels: any of these (brand profile) own_store_only, amazon, retail_stockists, own_retail_stores, marketplaces |
regulated | list | Store: regulated: any of these (brand profile) alcohol, cbd_hemp, supplements, tobacco_vape, firearms, adult, none |
seasonality | list | Store: seasonality: any of these (brand profile) holiday_q4, summer, back_to_school, valentines, mothers_fathers_day, none |
best_fit_vendors | list | Store: best-fit vendors: any of these (brand profile) email_sms_agency, paid_social_agency, influencer_ugc, seo_content, cro_web, 3pl_fulfillment, subscription_app, reviews_ugc_app, wholesale_platform, packaging, product_photography, retail_distribution |
seniority | list | Any of these levels: owner_founder, c_suite, vp, head_director, manager, other owner_founder, c_suite, vp, head_director, manager, other |
department | list | Any of these departments (the broad list) executive, ecommerce, growth_performance, marketing, customer_experience, operations_supply_chain, sales_wholesale, product, creative_brand, technology, finance, people_hr, other |
departments | list | Any of these departments from the finer list of about 30 (sales apart from wholesale, founders and owners, ecommerce, retention …); the keys are in GET /api/v1 under departments |
title | string | Title holds every one of these words |
titles | list | Title holds any one of these phrases, e.g. founder, head of ecommerce, VP marketing (up to 25) |
exclude_titles | list | Leave out titles holding any of these phrases, e.g. assistant, intern (up to 25) |
location | string | Location holds this text (city, region or country) |
person_country | list | Where the person is, ISO code (US, GB, CA …) |
dm | bool | Decision-makers only |
has_email | bool | Has a work email |
email_tier | list | Email checked by a verifier (verified) or catch-all and not confirmed (unconfirmed) verified, unconfirmed |
has_mobile | bool | Has a mobile number |
has_direct | bool | Has a direct dial |
has_linkedin | bool | Has a LinkedIn profile |
started_within_days | int | Started the current role within this many days (Pro and Scale) |
sort | string | seniority (default), name, store or role_start (newest first). Sorting reads the sample index. seniority, name, store, role_start |
source | string | live (default): the live database; sample: the sample index. Filters with no live equivalent read the sample and say so. live, sample |
page_size | int | Rows per page, 1-50 |
cursor | cursor | next_cursor from the previous page |
search_products
Free: never reveals a contact and never spends credits. Search the products stores sell: title, type, tags and description, every word must match. Public catalog data, open on every plan.
GET /api/v1/products/search POST /api/v1/products/search MCP tool search_products
| Filter | Type | What it does |
|---|---|---|
q | string | Every word appears in the product title, type, tags or description |
domain | list | Only these stores (exact domains) |
vertical | list | Store vertical apparel_accessories, arts_crafts_hobbies, auto_vehicles, baby_kids_toys, beauty_personal_care, electronics_tech, food_beverage, general_merchandise, gifts_party_flowers, health_wellness, home_garden, industrial_business, not_applicable, other_products, pets, sports_outdoors |
type | string | Product type, exact match ignoring case |
page_size | int | Rows per page, 1-50 |
cursor | cursor | next_cursor from the previous page |
preview_unlock
Free: never reveals a contact and never spends credits. Before you spend: for each person id, which of email, phone and LinkedIn exist, which you already own, and the exact credit cost to unlock each kind.
POST /api/v1/unlock/preview GET /api/v1/unlock/preview MCP tool preview_unlock
| Filter | Type | What it does |
|---|---|---|
ids | list | Person ids from search_people or get_store, e.g. live:2:1758252 |
kind | string | Only total this kind (optional) name, email, phone, profile, full |
include_linkedin_only | bool | Count people with a LinkedIn profile but no email in the email cost |
unlock_contacts
The only call that spends credits. Unlock each id: email (2 credits) reveals the work email and LinkedIn together; phone (5) reveals the mobile or direct dial with the email and LinkedIn, less anything already paid for that person; name (1) shows the full name of someone with no contact on file; full (10) is for signal-based leads (their store has recorded signals) and reveals every contact plus the store's dated signals, less anything already paid for that person. Every unlock shows the full name. Charged once per person, only when it applies; anything you already unlocked is free. kind=email skips people with a LinkedIn profile but no email, unless include_linkedin_only is true. Run preview_unlock first to see the cost.
POST /api/v1/unlock MCP tool unlock_contacts
| Filter | Type | What it does |
|---|---|---|
ids | list | Person ids from search_people or get_store, e.g. live:2:1758252 (up to 100) |
kind | string | What to unlock: email (with LinkedIn), phone (with email and LinkedIn), name, or full (signal-based leads: everything plus the store signals); profile is the email unlock name, email, phone, profile, full |
include_linkedin_only | bool | With kind=email, also pay to unlock people who have a LinkedIn profile but no email on file. Without it they are skipped and not charged. |
list_signals
Signals that fit your company. Pro and Scale get every dated signal with its store; other plans get counts per kind.
GET /api/v1/signals MCP tool list_signals
get_fit
Your company, the buyer type we read from your site, and how many stores and decision-makers fit.
GET /api/v1/fit MCP tool get_fit
export_unlocked
Every person this account has unlocked. Follow next_cursor when the answer says partial.
GET /api/v1/export MCP tool export_unlocked
| Filter | Type | What it does |
|---|---|---|
cursor | cursor | next_cursor from the previous answer |
account
Plan, credits and whether signals are open.
GET /api/v1/account MCP tool account
Errors
| 400 | unknown_filter | bad_value | bad_cursor | kind_required | ids_required | too_many_ids | mixed_ids | too_many_keys |
| 401 | invalid_api_key |
| 402 | insufficient_credits | trial_required |
| 403 | signals_need_pro |
| 404 | unknown_store | unknown_ids | not_found |
| 429 | rate_limited | live_busy (retry_after seconds) |
| 503 | live_unavailable |