---
name: "prospects_prepare"
area: "prospects"
title: "Prepare a prospect search"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/prospects_prepare"
mcp_server: "https://api.conecto.chat/mcp/prospects"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/prospects/prospects_prepare"
---

# Prepare a prospect search (`prospects_prepare`)

The interview before a prospect search: up to three questions about the market and the kind of customer, or a ready brief with its price.

The interview before a prospect search. From what the person asked for and what you know about the business, Conecto either asks up to three questions with choices, about the market and the kind of customer (never job titles), or writes a ready brief. Ask the questions in your own chat, then call again with the same request and about_us and every answer so far, by question id. When the status is ready, show the person the summary, the count and what it can cost (count x $0.05), and start it with prospects_find once they agree. Only accounts that have topped up search.

Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing.

## Use it when

When the person asks for new customers to contact, before any search starts.

- For a company the person already named, use [lookup_company](https://conecto.chat/tools/lookups/lookup_company.md).

## Say this to your agent

> We want more restaurant kitchens as customers. Find us about 40 in Hamburg that might need a new dishwasher.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `request` | string | yes | What the person asked for, in their words: who, how many, where. 3 to 4,000 characters. |  |  |
| `about_us` | string | yes | What the business sells, to whom and where, and what it wants from these prospects, from what you know about it. The interview never asks the person this. 20 to 4,000 characters. |  |  |
| `website` | string | no | The business's website; the account's own when left out. Up to 500 characters. |  |  |
| `answers` | object | no | The answers so far, by question id: a choice's value, several values for a multiple choice, or the person's own words. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `prospects_prepare` on the MCP server `https://api.conecto.chat/mcp/prospects` with these arguments:

```json
{
  "request": "Find 40 restaurants and hotel kitchens in Hamburg that might need a new dishwasher or combi steamer.",
  "about_us": "Hansen & Voss sells, installs and services commercial kitchen equipment (dishwashers, combi steamers, refrigeration) for restaurants, hotels and canteens in northern Germany, from Hamburg. We want first meetings with kitchens that are growing or replacing old equipment.",
  "website": "https://hansenvoss.example"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/prospects_prepare \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request": "Find 40 restaurants and hotel kitchens in Hamburg that might need a new dishwasher or combi steamer.", "about_us": "Hansen & Voss sells, installs and services commercial kitchen equipment (dishwashers, combi steamers, refrigeration) for restaurants, hotels and canteens in northern Germany, from Hamburg. We want first meetings with kitchens that are growing or replacing old equipment.", "website": "https://hansenvoss.example"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "prospects_prepare",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "status": "needs_input",
    "summary": "Restaurant and hotel kitchens that could replace or add dishwashers and combi steamers.",
    "questions": [
      {
        "id": "market",
        "prompt": "Where should the search look?",
        "help": "Local searches find more named people with working emails.",
        "selection": "single",
        "allow_custom": true,
        "options": [
          {
            "label": "Hamburg",
            "description": "The city itself",
            "value": "Hamburg, Germany"
          },
          {
            "label": "Northern Germany",
            "description": "Hamburg, Schleswig-Holstein and Lower Saxony",
            "value": "Northern Germany"
          }
        ]
      }
    ]
  }
}
```

`result`: status needs_input with a summary and up to three questions (id, prompt, help, single or multiple choice, options with a label, description and value, and whether the person may answer in their own words); or status ready with the summary, the brief (customers, industries, places, sizes, people, contact details, must have, leave out), the proposed count and a brief_token for prospects_find.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `payment_required` | 402 | The business never topped up, so its balance is free credit. | Top up once with POST /v1/topups, then call again. |
| `rate_limited` | 429 | The business ran 30 interviews in the last hour. | Wait, then call again with the same request and answers. |
| `unavailable` | 503 | The interview took too long, or the engine is busy. | Call again with the same request and answers. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [prospects_find](https://conecto.chat/tools/prospects/prospects_find.md): Start a prospect search from a ready brief: the businesses that fit and the people to reach there, with their work email checked. $0.05 per prospect found with a working email.
- [prospects_get](https://conecto.chat/tools/prospects/prospects_get.md): A prospect search by id: its status, progress, its question when it asks one, and the prospects found with their contact details. Free up to 1,000,000 reads a month.
- [prospects_answer](https://conecto.chat/tools/prospects/prospects_answer.md): Answer a prospect search that stopped finding new prospects and asks whether to widen it, so it carries on. Free.
- [prospects_stop](https://conecto.chat/tools/prospects/prospects_stop.md): Stop a prospect search; it ends with the prospects it found, and only those with a working email are charged. Free.
- [prospects_list](https://conecto.chat/tools/prospects/prospects_list.md): The business's prospect searches, newest first, with their status and how many each found. Free up to 1,000,000 reads a month.
- [prospects_save](https://conecto.chat/tools/prospects/prospects_save.md): Keep prospects in the CRM: each one's company, and a lead contact with their email, title and phone, tagged prospect. Free.