Buy leads
buy_leadsBuy leads. THIS SPENDS MONEY AND CANNOT BE UNDONE. max_price_usd is required: nothing is bought if the price is higher. Paid from the account's credits (API key needed) it returns the leads at once: the first 25 inline and download links for the full set. Otherwise it returns a checkout link and an order id; a person pays on that page, then get_order returns the leads. Run quote_leads first.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"quantity": "<quantity>",
"max_price_usd": "<max_price_usd>"
},
"name": "buy_leads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | Email for the receipt and for recovering the order. | ||
| fresh | No | Skip leads this account already received for the same search (default true when an API key is used). | |
| filters | No | Search filters, all optional. Combine as needed; more filters means fewer leads. | |
| after_id | No | Continue after this lead id (use next_after_id from an earlier order to get new leads). | |
| quantity | Yes | How many leads (1 to 25,000). If fewer match, you get what matches. | |
| max_price_usd | Yes | REQUIRED spending cap in US dollars. Nothing is bought if the price is higher. | |
| payment_method | No | auto (default): account credits when enough, else a Shared Payment Token if given, else a checkout link. checkout: always return a link for a person to pay. | |
| idempotency_key | No | Optional. Send the same value when retrying after a timeout so you are never charged twice for one purchase. | |
| shared_payment_token | No | Stripe Shared Payment Token (spt_...), only with payment_method "stripe_spt". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| leads | Yes | At most 25 leads, only when fulfilled. Use the download links for the full set. | |
| notes | No | Plain sentences from the API about this order, for example that the same search already has an unpaid order. | |
| status | Yes | awaiting_payment, paid, fulfilled, expired, canceled, refunded or failed. | |
| matched | No | ||
| paid_at | No | ||
| currency | No | ||
| download | No | ||
| livemode | No | ||
| order_id | Yes | The order id. Keep it secret. | |
| quantity | No | ||
| delivered | No | ||
| next_step | Yes | What to do next, in plain words. | |
| price_usd | No | ||
| created_at | No | ||
| expires_at | No | ||
| leads_shown | Yes | ||
| leads_total | Yes | How many leads the order holds. | |
| price_cents | No | ||
| checkout_url | No | Open this page to pay (a person must do it). | |
| next_after_id | No | ||
| payment_method | No | ||
| leads_truncated | Yes | True when more leads exist than the 25 shown inline. | |
| url_elicitation | No | Whether the checkout link was also offered through URL-mode elicitation. | |
| unit_price_cents | No |