Quick Start¶

Create an enrichment order and fetch the delivered results.

Time required: About 5 minutes.

Prerequisites¶

An OpenProspect API key with orders:write, orders:read, companies:read, and prospects:read.
The API key stored as OPENPROSPECT_API_KEY.
One company you want to enrich.

Step 1: Validate Authentication¶

GET /api/v1/auth/validate

cURLPythonJavaScriptTypeScriptC#

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

import os

import httpx

api_key = os.environ["OPENPROSPECT_API_KEY"]

response = httpx.get(
    "https://api.openprospect.io/api/v1/auth/validate",
    headers={"Authorization": f"Bearer {api_key}"},
    timeout=30.0,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.openprospect.io/api/v1/auth/validate", {
  headers: { Authorization: `Bearer ${process.env.OPENPROSPECT_API_KEY}` },
});

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

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

interface AuthValidation {
  valid: boolean;
  scopes: string[];
}

const response = await fetch("https://api.openprospect.io/api/v1/auth/validate", {
  headers: { Authorization: `Bearer ${process.env.OPENPROSPECT_API_KEY}` },
});

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

const auth = (await response.json()) as AuthValidation;
console.log(auth.valid);

using System.Net.Http.Headers;

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 response = await client.GetAsync("https://api.openprospect.io/api/v1/auth/validate");
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Expected response:

{
  "valid": true,
  "scopes": ["orders:write", "orders:read", "companies:read", "prospects:read"]
}

Checkpoint: valid is true.

Step 2: Create a Search Profile¶

POST /api/v1/search-profile-creations

Profiles describe how OpenProspect should qualify and brief companies. Create one first, then reuse its profile_id for enrichment and discovery orders.

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: quickstart-profile-001" \
  -d '{
    "profile_name": "Quickstart 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"
  }'

Expected response:

{
  "profile_creation_id": "f7a5a926-4d42-4e30-9f40-61e5da52f7aa",
  "status": "PENDING",
  "profile_id": null,
  "error_code": null,
  "error_message": null,
  "created_at": "2026-06-30T10:00:00Z",
  "started_at": null,
  "finished_at": null,
  "message": "Search profile creation accepted. Poll this resource for status."
}

Poll until the request succeeds:

curl -sS \
  "https://api.openprospect.io/api/v1/search-profile-creations/${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: save the returned profile_id as OPENPROSPECT_PROFILE_ID.

Step 3: Create an Enrichment Order¶

POST /api/v1/orders

The API returns 202 Accepted. The order starts in RECEIVED while the OpenProspect team reviews and processes it.

cURLPythonJavaScriptTypeScriptC#

curl -sS https://api.openprospect.io/api/v1/orders \
  -H "Authorization: Bearer ${OPENPROSPECT_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-enrichment-001" \
  -d '{
    "order_type": "ENRICHMENT",
    "title": "Quickstart enrichment",
    "profile_id": "'"${OPENPROSPECT_PROFILE_ID}"'",
    "features": ["COMPANY_DATA", "CONTACTS"],
    "companies": [
      {
        "company_name": "Stripe",
        "external_id": "crm-1001",
        "website_url": "https://stripe.com"
      }
    ]
  }'

import os

import httpx

api_key = os.environ["OPENPROSPECT_API_KEY"]
profile_id = os.environ["OPENPROSPECT_PROFILE_ID"]
payload = {
    "order_type": "ENRICHMENT",
    "title": "Quickstart enrichment",
    "profile_id": profile_id,
    "features": ["COMPANY_DATA", "CONTACTS"],
    "companies": [
        {
            "company_name": "Stripe",
            "external_id": "crm-1001",
            "website_url": "https://stripe.com",
        }
    ],
}

response = httpx.post(
    "https://api.openprospect.io/api/v1/orders",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": "quickstart-enrichment-001",
    },
    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",
    "Idempotency-Key": "quickstart-enrichment-001",
  },
  body: JSON.stringify({
    order_type: "ENRICHMENT",
    title: "Quickstart enrichment",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    features: ["COMPANY_DATA", "CONTACTS"],
    companies: [
      {
        company_name: "Stripe",
        external_id: "crm-1001",
        website_url: "https://stripe.com",
      },
    ],
  }),
});

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

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

interface CreateOrderResponse {
  order_id: string;
  order_type: "DISCOVERY" | "ENRICHMENT";
  status: string;
  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": "quickstart-enrichment-001",
  },
  body: JSON.stringify({
    order_type: "ENRICHMENT",
    title: "Quickstart enrichment",
    profile_id: process.env.OPENPROSPECT_PROFILE_ID,
    features: ["COMPANY_DATA", "CONTACTS"],
    companies: [
      {
        company_name: "Stripe",
        external_id: "crm-1001",
        website_url: "https://stripe.com",
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Order creation 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);
client.DefaultRequestHeaders.Add("Idempotency-Key", "quickstart-enrichment-001");
var profileId = Environment.GetEnvironmentVariable("OPENPROSPECT_PROFILE_ID")
    ?? throw new InvalidOperationException("OPENPROSPECT_PROFILE_ID is not set.");

var payload = new
{
    order_type = "ENRICHMENT",
    title = "Quickstart enrichment",
    profile_id = profileId,
    features = new[] { "COMPANY_DATA", "CONTACTS" },
    companies = new[]
    {
        new
        {
            company_name = "Stripe",
            external_id = "crm-1001",
            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."
}

Checkpoint: save the order_id.

Step 4: Check Status¶

GET /api/v1/orders/{order_id}

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

Expected response:

{
  "order_id": "4f767705-03a2-4e91-a3e8-1ec3f9dea865",
  "order_type": "ENRICHMENT",
  "title": "Quickstart enrichment",
  "status": "COMPLETED",
  "priority": "NORMAL",
  "briefing_quantity": 1,
  "available_briefing_quantity": 1,
  "features": ["COMPANY_DATA", "CONTACTS"],
  "estimated_cost": null,
  "prospect_search_id": "42665897-b189-4e0f-8841-499351a30aff",
  "admin_notes": null,
  "webhook_url": null,
  "created_at": "2026-02-25T10:30:00Z",
  "accepted_at": "2026-02-25T10:45:00Z",
  "completed_at": "2026-02-25T12:00:00Z",
  "cancelled_at": null
}

Checkpoint: results are available when status is COMPLETED.

Step 5: Fetch Results¶

GET /api/v1/orders/{order_id}/results

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

Expected response:

{
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Stripe",
      "website_url": "https://stripe.com",
      "source_id": "crm-1001",
      "prospects": []
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Next steps:

Read Enrichment Order Guide for full request fields.
Read Discovery Quick Start for discovery orders.
Use Interactive API for schema details.