Enrichment Quick Start¶

Create an enrichment order when you already know the companies you want OpenProspect to enrich.

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¶

The profile describes how OpenProspect should qualify and brief the companies. You can use the same profile for enrichment and discovery.

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-enrichment-quickstart-001" \
  -d '{
    "profile_name": "Payments software buyers",
    "ideal_customer_profile": "B2B software companies that sell to finance teams",
    "seller_offering": "Payment operations software",
    "target_countries": ["US", "GB", "DE"],
    "contact_roles": ["CFO", "Head of Finance"],
    "output_language": "en"
  }'

Poll the returned profile_creation_id until it returns SUCCEEDED, then save the 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 an Enrichment Order¶

POST /api/v1/orders

Enrichment orders require:

order_type: "ENRICHMENT"
profile_id
companies
features
Idempotency-Key

Do not send briefing_quantity for enrichment. The API derives it from companies.length.

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: enrichment-order-quickstart-001" \
  -d '{
    "order_type": "ENRICHMENT",
    "title": "My first enrichment order",
    "profile_id": "'"${OPENPROSPECT_PROFILE_ID}"'",
    "features": ["COMPANY_DATA", "CONTACTS"],
    "companies": [
      {
        "company_name": "Stripe",
        "external_id": "crm-001",
        "website_url": "https://stripe.com"
      }
    ]
  }'

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": "enrichment-order-quickstart-001",
    },
    json={
        "order_type": "ENRICHMENT",
        "title": "My first enrichment order",
        "profile_id": profile_id,
        "features": ["COMPANY_DATA", "CONTACTS"],
        "companies": [
            {
                "company_name": "Stripe",
                "external_id": "crm-001",
                "website_url": "https://stripe.com",
            }
        ],
    },
    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": "enrichment-order-quickstart-001",
  },
  body: JSON.stringify({
    order_type: "ENRICHMENT",
    title: "My first enrichment order",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    features: ["COMPANY_DATA", "CONTACTS"],
    companies: [
      {
        company_name: "Stripe",
        external_id: "crm-001",
        website_url: "https://stripe.com",
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Enrichment 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": "enrichment-order-quickstart-001",
  },
  body: JSON.stringify({
    order_type: "ENRICHMENT",
    title: "My first enrichment order",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    features: ["COMPANY_DATA", "CONTACTS"],
    companies: [{ company_name: "Stripe", external_id: "crm-001", website_url: "https://stripe.com" }],
  }),
});

if (!response.ok) {
  throw new Error(`Enrichment 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", "enrichment-order-quickstart-001");

var payload = new
{
    order_type = "ENRICHMENT",
    title = "My first enrichment order",
    profile_id = profileId,
    features = new[] { "COMPANY_DATA", "CONTACTS" },
    companies = new[]
    {
        new
        {
            company_name = "Stripe",
            external_id = "crm-001",
            website_url = "https://stripe.com"
        }
    }
};

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": "ENRICHMENT",
  "status": "RECEIVED",
  "briefing_quantity": 1,
  "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}"

Wait for COMPLETED, then call:

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

The source_id in results matches your submitted external_id when you provide one.

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