Enrichment Order Guide

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

Submitted companies are treated as prequalified source data, so OpenProspect delivers all submitted companies independent of final match score.

Request Model

POST /api/v1/orders

Field	Required	Description
order_type	Yes	Must be ENRICHMENT
title	Yes	Your label for the order
profile_id	Yes	Search profile returned by profile creation
companies	Yes	One or more companies to enrich
features	Yes	Briefing features to deliver
output_language	No	Defaults to en
briefing_quantity	No	Forbidden; derived from companies.length

Do not send profile_name, ideal_customer_profile, or other profile fields to POST /api/v1/orders.

Create Request

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-dach-saas-001" \
  -d '{
    "order_type": "ENRICHMENT",
    "title": "DACH SaaS enrichment",
    "profile_id": "'"${OPENPROSPECT_PROFILE_ID}"'",
    "features": ["COMPANY_DATA", "CONTACTS", "TECHNOLOGIES"],
    "companies": [
      {
        "company_name": "Grand Hotel Berlin",
        "external_id": "crm-1001",
        "website_url": "https://www.grandhotel-berlin.de",
        "city": "Berlin",
        "country": "Germany"
      },
      {
        "company_name": "Alpine Resort Innsbruck",
        "external_id": "crm-1002",
        "city": "Innsbruck",
        "country": "Austria"
      }
    ]
  }'

Expected 202 Accepted response:

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

Company Fields

Field	Required	Description
company_name	Yes	Company name
external_id	No	Your CRM/source ID; returned as source_id
website_url	No	Company website
postal_code	No	Postal or ZIP code
city	No	City
street	No	Street address
country	No	Country
email	No	Contact email
phone	No	Contact phone
employee_count	No	Number of employees
industry_code	No	SIC or industry code
industry_description	No	Industry description

Provide website_url when you have it. It improves matching and enrichment quality.

Lifecycle

Enrichment orders use the same statuses as discovery orders:

RECEIVED, ACCEPTED, IN_PROGRESS, COMPLETED, REJECTED, FAILED, and CANCELLED.

Results

Call GET /api/v1/orders/{order_id}/results only after the order is COMPLETED. Result source_id values match submitted external_id values when provided.

If results are not ready, the API returns ORDER_RESULTS_NOT_READY; continue polling GET /api/v1/orders/{order_id}.

Errors

Status	Cause	Resolution
409	Reused Idempotency-Key with a different order body	Use a new key
422	Missing companies, missing profile_id, or sent briefing_quantity	Correct the body
404	profile_id or order_id is not visible to your organization	Verify the ID and API key
404	ORDER_RESULTS_NOT_READY before COMPLETED	Poll order status