API reference / Watchlists

Create a watchlist

Written and maintained by The ProspectAPIs team

POST/v1/watchlists

POST /v1/watchlists is the ProspectAPIs operation createWatchlist, in the Watchlists group of the REST API. Save a set of funding filters plus an https webhook. New matches are pushed as signed funding_event.matched events. Free to create; each delivered record costs one record, charged only when your webhook answers 2xx. The signing secret is in this response and nowhere else. At most 20 active watchlists per account. Cost: free; $0.02 per delivered record. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the watchlists API, with worked examples, is in the watchlists guide.

Parameters

This operation takes no path or query parameters.

Request body

JSON (WatchlistRequest).

{
  "name": "Seed rounds in Germany",
  "filters": {
    "round": "seed",
    "country": "Germany"
  },
  "webhook_url": "https://hooks.example.com/funding"
}

Responses

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

201 response fields

The watchlist, including its signing secret (shown only here). The body is a WatchlistWithSecret.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl -X POST https://api.prospectapis.com/v1/watchlists \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Seed rounds in Germany", "filters": { "round": "seed", "country": "Germany" }, "webhook_url": "https://hooks.example.com/funding" }'

const res = await fetch("https://api.prospectapis.com/v1/watchlists", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Seed rounds in Germany",
    "filters": {
      "round": "seed",
      "country": "Germany"
    },
    "webhook_url": "https://hooks.example.com/funding"
  }),
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

import os, requests

res = requests.post(
    "https://api.prospectapis.com/v1/watchlists",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    json={
        "name": "Seed rounds in Germany",
        "filters": {
            "round": "seed",
            "country": "Germany",
        },
        "webhook_url": "https://hooks.example.com/funding",
    },
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

The call itself is free, and what it sets up is billed as it runs: $0.02 per delivered record. Metered spend on the same key is reported after each response in X-Credits-Remaining, and GET /v1/account shows the balance at any time.

Related

The watchlists guide covers this area end to end. Previous operation: List watchlists. Next operation: Read a watchlist. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values (this call acts for real, so use real inputs).