Skip to content

Discovery Quick Start

From zero to discovered companies in 5 steps.

This quick start walks you through the complete discovery flow: create a blacklist, add exclusions, submit a discovery order, track it, and retrieve results.

Before You Start

You need an API key with these scopes: orders:read, orders:write, blacklists:read, blacklists:write.

Create one in the OpenProspect dashboard under Settings > Developer > API Keys and select the Orders preset (or Custom with the scopes listed above).

Set your key:

export API_KEY="lnc_live_your_api_key_here"
export BASE_URL="https://api.openprospect.io/api/v1"

1. Create a Blacklist

Exclude companies you already know (existing customers, competitors).

curl -s -X POST "$BASE_URL/blacklists" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Existing Customers", "description": "Companies in our CRM"}' | jq .

{
  "id": "YOUR_BLACKLIST_ID",
  "name": "Existing Customers",
  "entry_count": 0
}

Save the id for the next step.

2. Add Entries to the Blacklist

Add companies to exclude. Provide website_url for best matching accuracy.

curl -s -X POST "$BASE_URL/blacklists/YOUR_BLACKLIST_ID/entries" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {"company_name": "Acme Corp", "website_url": "https://www.acme-corp.com"},
      {"company_name": "Global Industries GmbH", "city": "Munich", "country": "Germany"}
    ]
  }' | jq '. | length'

2

3. Create a Discovery Order

Describe your ideal customer and let OpenProspect find matching companies.

curl -s -X POST "$BASE_URL/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "DISCOVERY",
    "title": "DACH SaaS Discovery",
    "features": ["COMPANY_DATA", "CONTACTS", "ANALYSIS"],
    "ideal_customer_profile": "Mid-market B2B SaaS companies in DACH with 50-500 employees",
    "seller_offering": "AI-powered lead generation platform",
    "target_countries": ["Germany", "Austria", "Switzerland"],
    "blacklist_ids": ["YOUR_BLACKLIST_ID"],
    "profile_name": "DACH SaaS Discovery"
  }' | jq .

{
  "order_id": "YOUR_ORDER_ID",
  "order_type": "DISCOVERY",
  "status": "RECEIVED",
  "company_count": 0,
  "estimated_cost": null,
  "message": "Order received. Awaiting admin review."
}

Save the order_id for tracking.

4. Track Order Status

Poll until the status is COMPLETED:

curl -s -X GET "$BASE_URL/orders/YOUR_ORDER_ID" \
  -H "Authorization: Bearer $API_KEY" | jq '{status, company_count}'

{"status": "COMPLETED", "company_count": 47}

Use Webhooks

Instead of polling, add "webhook_url": "https://your-api.com/webhook" to the create order request. See Webhook Notifications.

5. Retrieve Results

Get the discovered companies with enriched data:

curl -s -X GET "$BASE_URL/orders/YOUR_ORDER_ID/results?limit=5" \
  -H "Authorization: Bearer $API_KEY" | jq '.items[] | {name, match_score, city, prospects: (.prospects | length)}'

{"name": "CloudOps Technologies GmbH", "match_score": 9, "city": "Berlin", "prospects": 3}
{"name": "DataFlow AG", "match_score": 8, "city": "Munich", "prospects": 2}
{"name": "SwissCloud Solutions", "match_score": 8, "city": "Zurich", "prospects": 4}

Page through all results with offset:

curl -s -X GET "$BASE_URL/orders/YOUR_ORDER_ID/results?limit=50&offset=0" \
  -H "Authorization: Bearer $API_KEY" | jq '.total, .has_more'

What's Next?