Discovery Order Guide¶

Use a discovery order when you want OpenProspect to find new qualified companies for an existing search profile.

Request Model¶

POST /api/v1/orders

Field	Required	Description
`order_type`	Yes	Must be `DISCOVERY`
`title`	Yes	Your label for the order
`profile_id`	Yes	Search profile returned by profile creation
`briefing_quantity`	Yes	Desired number of qualified companies
`features`	Yes	Briefing features to deliver
`output_language`	No	Defaults to `en`
`companies`	No	Forbidden for discovery orders

Do not send profile_name, ideal_customer_profile, seller_offering, target_countries, 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: discovery-order-dach-saas-001" \
  -d '{
    "order_type": "DISCOVERY",
    "title": "DACH SaaS discovery",
    "profile_id": "'"${OPENPROSPECT_PROFILE_ID}"'",
    "briefing_quantity": 50,
    "features": ["COMPANY_DATA", "CONTACTS", "ANALYSIS"],
    "output_language": "en"
  }'

Expected 202 Accepted response:

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

Lifecycle¶

Status	Meaning	What to do
`RECEIVED`	The order is awaiting review	Poll again
`ACCEPTED`	The order is approved	Poll again
`IN_PROGRESS`	Fulfillment is running	Poll again
`COMPLETED`	Fulfillment ended	Fetch results when `results_published` is `true`
`REJECTED`	The order was not approved	Contact support with `order_id`
`FAILED`	Fulfillment failed	Contact support with `order_id`
`CANCELLED`	The order was cancelled	Stop polling

Results¶

Call GET /api/v1/orders/{order_id}/results only after the order is COMPLETED and results_published is true. Discovery results contain the system-discovered companies that passed the profile's qualification and delivery-policy rules. briefing_quantity is requested; the published available_briefing_quantity can be lower when fewer contactable, qualified companies are available.

Read every page with limit and offset: request up to 100 companies, advance offset by the number of returned items, and stop only when has_more is false. The pages form one immutable order snapshot.

Do not use GET /api/v1/deliveries/{prospect_search_id}/companies to reconcile this order. It is legacy profile-wide CRM sync / drip. Use GET /api/v1/orders/{order_id}/results.

If results are not ready, the API returns ORDER_RESULTS_NOT_READY. Continue polling while the order is active; for a historical COMPLETED order with results_published: false, contact support with the order ID.

Errors¶

Status	Cause	Resolution
`409`	Reused `Idempotency-Key` with a different order body	Use a new key
`422`	Missing `profile_id` or `briefing_quantity`, or included `companies`	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