Discovery Quick Start

Create a discovery order when you want OpenProspect to find new companies that match an ideal customer profile.

Time required: About 5 minutes.

Prerequisites

• An API key with orders:write, orders:read, companies:read, prospects:read, blacklists:read, and blacklists:write.
• The API key stored as OPENPROSPECT_API_KEY.

Step 1: Create a Discovery Order

POST /api/v1/orders

cURLPythonJavaScriptTypeScriptC#

curl -sS https://api.openprospect.io/api/v1/orders \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "DISCOVERY",
    "title": "Boutique hotel discovery",
    "features": ["COMPANY_DATA", "CONTACTS"],
    "ideal_customer_profile": "Independent boutique hotels with 20-200 rooms",
    "seller_offering": "Guest messaging and upsell automation",
    "seller_industry": "Hospitality software",
    "target_countries": ["Germany"],
    "target_cities": ["Berlin", "Hamburg"],
    "contact_roles": ["General Manager", "Revenue Manager"],
    "output_language": "en"
  }'

import os

import httpx

api_key = os.environ["OPENPROSPECT_API_KEY"]
payload = {
    "order_type": "DISCOVERY",
    "title": "Boutique hotel discovery",
    "features": ["COMPANY_DATA", "CONTACTS"],
    "ideal_customer_profile": "Independent boutique hotels with 20-200 rooms",
    "seller_offering": "Guest messaging and upsell automation",
    "seller_industry": "Hospitality software",
    "target_countries": ["Germany"],
    "target_cities": ["Berlin", "Hamburg"],
    "contact_roles": ["General Manager", "Revenue Manager"],
    "output_language": "en",
}

response = httpx.post(
    "https://api.openprospect.io/api/v1/orders",
    headers={"Authorization": f"Bearer {api_key}"},
    json=payload,
    timeout=30.0,
)
response.raise_for_status()
print(response.json()["order_id"])

const response = await fetch("https://api.openprospect.io/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENPROSPECT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order_type: "DISCOVERY",
    title: "Boutique hotel discovery",
    features: ["COMPANY_DATA", "CONTACTS"],
    ideal_customer_profile: "Independent boutique hotels with 20-200 rooms",
    seller_offering: "Guest messaging and upsell automation",
    seller_industry: "Hospitality software",
    target_countries: ["Germany"],
    target_cities: ["Berlin", "Hamburg"],
    contact_roles: ["General Manager", "Revenue Manager"],
    output_language: "en",
  }),
});

if (!response.ok) {
  throw new Error(`Discovery order failed: ${response.status}`);
}

console.log((await response.json()).order_id);

interface CreateOrderResponse {
  order_id: string;
  status: string;
}

const response = await fetch("https://api.openprospect.io/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENPROSPECT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    order_type: "DISCOVERY",
    title: "Boutique hotel discovery",
    features: ["COMPANY_DATA", "CONTACTS"],
    ideal_customer_profile: "Independent boutique hotels with 20-200 rooms",
    seller_offering: "Guest messaging and upsell automation",
    seller_industry: "Hospitality software",
    target_countries: ["Germany"],
    target_cities: ["Berlin", "Hamburg"],
    contact_roles: ["General Manager", "Revenue Manager"],
    output_language: "en",
  }),
});

if (!response.ok) {
  throw new Error(`Discovery order failed: ${response.status}`);
}

const order = (await response.json()) as CreateOrderResponse;
console.log(order.order_id);

using System.Net.Http.Headers;
using System.Net.Http.Json;

var apiKey = Environment.GetEnvironmentVariable("OPENPROSPECT_API_KEY")
    ?? throw new InvalidOperationException("OPENPROSPECT_API_KEY is not set.");

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

var payload = new
{
    order_type = "DISCOVERY",
    title = "Boutique hotel discovery",
    features = new[] { "COMPANY_DATA", "CONTACTS" },
    ideal_customer_profile = "Independent boutique hotels with 20-200 rooms",
    seller_offering = "Guest messaging and upsell automation",
    seller_industry = "Hospitality software",
    target_countries = new[] { "Germany" },
    target_cities = new[] { "Berlin", "Hamburg" },
    contact_roles = new[] { "General Manager", "Revenue Manager" },
    output_language = "en"
};

var response = await client.PostAsJsonAsync("https://api.openprospect.io/api/v1/orders", payload);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Expected response:

{
  "order_id": "4f767705-03a2-4e91-a3e8-1ec3f9dea865",
  "order_type": "DISCOVERY",
  "status": "RECEIVED",
  "company_count": 0,
  "estimated_cost": null,
  "message": "Order received. Awaiting admin review."
}

Checkpoint: save the order_id.

Step 2: Check Discovery Status

GET /api/v1/orders/{order_id}

curl -sS "https://api.openprospect.io/api/v1/orders/${ORDER_ID}" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}"

Use GET /api/v1/orders/{order_id}/results after the order status is COMPLETED.

Step 3: Assign Blacklists

If a discovery order creates a prospect search profile, assign blacklists with:

PUT /api/v1/prospect-searches/{prospect_search_id}/blacklists

curl -sS -X PUT \
  "https://api.openprospect.io/api/v1/prospect-searches/${PROSPECT_SEARCH_ID}/blacklists" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"blacklist_ids": ["8f3d8f4e-3b7f-4c0e-a28d-1f40a8f0c111"]}'

Expected response: 204 No Content.