Skip to content

Orders Overview

Use orders when you want OpenProspect to deliver company briefings. Every order starts from a search profile.

Mental Model

Concept Meaning
Search profile What to look for and how to qualify companies
Order What you want OpenProspect to deliver now
Discovery order Find new qualified companies for a profile
Enrichment order Enrich companies you already provide
briefing_quantity Requested delivered briefing count

Create the profile first, then place one or more orders from that profile.

Choose a Flow

You have Use Send companies? Send briefing_quantity?
An ICP and need new companies Discovery No Yes
A list of companies to enrich Enrichment Yes No

For discovery, briefing_quantity is the number of qualified companies you want delivered. For enrichment, the API derives briefing_quantity from companies.length because submitted companies are treated as prequalified.

Basic Flow

  1. Create a profile with POST /api/v1/search-profile-creations.
  2. Poll profile creation until it returns SUCCEEDED.
  3. Save the returned profile_id.
  4. Create an order with POST /api/v1/orders.
  5. Poll GET /api/v1/orders/{order_id} until the order reaches COMPLETED.
  6. Fetch results with GET /api/v1/orders/{order_id}/results.

Statuses

Profile creation has a small async lifecycle:

Status Meaning Next step
PENDING The request is queued Poll again
RUNNING The profile is being created Poll again
SUCCEEDED The profile is ready Create an order
FAILED Profile creation did not finish Retry with a new idempotency key

Orders use this lifecycle:

Status Meaning Next step
RECEIVED The order is awaiting review Poll again
ACCEPTED The order is approved Poll again
IN_PROGRESS Fulfillment is running Poll again
COMPLETED Results are ready Fetch results
REJECTED The order was not approved Check the message
FAILED Fulfillment failed Contact support with the order ID
CANCELLED The order was cancelled Stop polling

What to Store

Store these IDs in your system:

ID Why
profile_creation_id Poll profile creation and debug failed synthesis
profile_id Reuse the same profile for discovery and enrichment orders
order_id Poll order status and fetch delivered results
Your idempotency keys Retry safely without creating duplicates

If you send external_id for enrichment companies, store it too. Results return that value as source_id.

Reliability Rules

  • Send Idempotency-Key on profile creation and order creation.
  • Retry 429, 500, 502, 503, and 504 with backoff.
  • Retry POST requests with the same idempotency key only when the body is the same.
  • Use a new idempotency key when you intentionally change the request body.
  • Treat 409 as an idempotency conflict and create a new key for the changed request.
  • Do not fetch results until the order is COMPLETED.

Next Steps