Discovery Quick Start

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

Time required: About 5 minutes, excluding admin review and fulfillment.

Prerequisites

• An API key with orders:write, orders:read, companies:read, and prospects:read.
• The API key stored as OPENPROSPECT_API_KEY.
• A ready profile_id. Create one with Search Profile Creation.

Step 1: Create or Reuse a Profile

Create a search profile first:

curl -sS -X POST "https://api.openprospect.io/api/v1/search-profile-creations" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: profile-discovery-quickstart-001" \
  -d '{
    "profile_name": "Boutique hotels DACH",
    "ideal_customer_profile": "Independent boutique hotels with 20-200 rooms",
    "seller_offering": "Guest messaging and upsell automation",
    "target_countries": ["DE", "AT", "CH"],
    "contact_roles": ["General Manager", "Revenue Manager"],
    "output_language": "en"
  }'

Poll the returned profile_creation_id until the response has "status": "SUCCEEDED", then save the returned profile_id.

export OPENPROSPECT_PROFILE_CREATION_ID="f7a5a926-4d42-4e30-9f40-61e5da52f7aa"

curl -sS \
  "https://api.openprospect.io/api/v1/search-profile-creations/${OPENPROSPECT_PROFILE_CREATION_ID}" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}"

Successful profile creation returns a reusable profile ID:

{
  "profile_creation_id": "f7a5a926-4d42-4e30-9f40-61e5da52f7aa",
  "status": "SUCCEEDED",
  "profile_id": "8d6e39fd-6d73-4cc2-9612-6ffb41c84f29",
  "error_code": null,
  "error_message": null,
  "created_at": "2026-06-30T10:00:00Z",
  "started_at": "2026-06-30T10:00:01Z",
  "finished_at": "2026-06-30T10:00:08Z"
}

export OPENPROSPECT_PROFILE_ID="8d6e39fd-6d73-4cc2-9612-6ffb41c84f29"

Checkpoint: keep OPENPROSPECT_PROFILE_ID; every order references it.

Step 2: Create a Discovery Order

POST /api/v1/orders

Discovery orders require:

• order_type: "DISCOVERY"
• profile_id
• briefing_quantity
• features
• Idempotency-Key

cURLPythonJavaScriptTypeScriptC#

curl -sS -X POST "https://api.openprospect.io/api/v1/orders" \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: discovery-order-quickstart-001" \
  -d '{
    "order_type": "DISCOVERY",
    "title": "Boutique hotel discovery",
    "profile_id": "'"${OPENPROSPECT_PROFILE_ID}"'",
    "briefing_quantity": 25,
    "features": ["COMPANY_DATA", "CONTACTS"],
    "output_language": "en"
  }'

import os

import httpx

api_key = os.environ["OPENPROSPECT_API_KEY"]
profile_id = os.environ["OPENPROSPECT_PROFILE_ID"]

response = httpx.post(
    "https://api.openprospect.io/api/v1/orders",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": "discovery-order-quickstart-001",
    },
    json={
        "order_type": "DISCOVERY",
        "title": "Boutique hotel discovery",
        "profile_id": profile_id,
        "briefing_quantity": 25,
        "features": ["COMPANY_DATA", "CONTACTS"],
        "output_language": "en",
    },
    timeout=30.0,
)
response.raise_for_status()
print(response.json())

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",
    "Idempotency-Key": "discovery-order-quickstart-001",
  },
  body: JSON.stringify({
    order_type: "DISCOVERY",
    title: "Boutique hotel discovery",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    briefing_quantity: 25,
    features: ["COMPANY_DATA", "CONTACTS"],
    output_language: "en",
  }),
});

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

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

interface CreateOrderResponse {
  order_id: string;
  order_type: "DISCOVERY" | "ENRICHMENT";
  status: "RECEIVED";
  briefing_quantity: number;
  estimated_cost: { total: number; currency: string } | null;
  message: 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",
    "Idempotency-Key": "discovery-order-quickstart-001",
  },
  body: JSON.stringify({
    order_type: "DISCOVERY",
    title: "Boutique hotel discovery",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    briefing_quantity: 25,
    features: ["COMPANY_DATA", "CONTACTS"],
  }),
});

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

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.");
var profileId = Environment.GetEnvironmentVariable("OPENPROSPECT_PROFILE_ID")
    ?? throw new InvalidOperationException("OPENPROSPECT_PROFILE_ID is not set.");

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
client.DefaultRequestHeaders.Add("Idempotency-Key", "discovery-order-quickstart-001");

var payload = new
{
    order_type = "DISCOVERY",
    title = "Boutique hotel discovery",
    profile_id = profileId,
    briefing_quantity = 25,
    features = new[] { "COMPANY_DATA", "CONTACTS" },
    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",
  "briefing_quantity": 25,
  "estimated_cost": null,
  "message": "Order received. Awaiting admin review."
}

Save the order_id.

Checkpoint: keep the order_id; use it to poll status and fetch results.

Step 3: Check Order Status

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

The order moves through RECEIVED, ACCEPTED, IN_PROGRESS, and COMPLETED. It can also end as REJECTED, FAILED, or CANCELLED.

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

Checkpoint: stop polling when the order is COMPLETED, REJECTED, FAILED, or CANCELLED.