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 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" \
  -d '{
    "order_type": "ENRICHMENT",
    "title": "Quickstart enrichment",
    "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"]
payload = {
    "order_type": "ENRICHMENT",
    "title": "Quickstart enrichment",
    "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}"},
    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: "ENRICHMENT",
    title: "Quickstart enrichment",
    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;
  status: string;
  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",
  },
  body: JSON.stringify({
    order_type: "ENRICHMENT",
    title: "Quickstart enrichment",
    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);

var payload = new
{
    order_type = "ENRICHMENT",
    title = "Quickstart enrichment",
    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",
  "company_count": 1,
  "estimated_cost": null,
  "message": "Order received. Awaiting admin review."
}

Checkpoint: save the order_id.

Step 3: 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",
  "company_count": 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 4: 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.