Adding prospects from outside the app

Anything outside Artisanly can add to your pipeline through an API key with the Prospects scope, issued under Settings → API keys. The case it was built for is an AI on your own desktop: you ask it for the cafés in a town nobody has called yet, and it puts them straight into Prospects with a note on each saying why it is worth a visit.

What arrives is always a lead that nobody owns. Nothing outside the app can claim a shop has agreed to stock you, and a shop an agent found has not been claimed by a salesperson — somebody takes it from the pipeline, and that is the moment it becomes theirs.

Every upload is recorded as one batch, listed under Pipeline → Uploads with what came in, what was already there, and what was turned away. An agent will sometimes be wrong, so removing a batch is one action rather than an afternoon: it deletes the shops nobody has claimed and keeps anything a person has already picked up.

A shop already on your books comes back as a duplicate rather than an error, so an agent asked the same question twice cannot create it twice. Towns are matched by name against your regions, and a name you do not use is the one reason a row is turned away — which is why the integration reads your region list first.

The setup is in the repository under tools/prospect-mcp for Claude on a desktop, and the full guide for anything else is at /docs/prospects-api.md.