Enrichment Order Guide¶

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

Submitted companies are treated as the prequalified candidate population. OpenProspect evaluates that population against the search profile's delivery policy before publication, so the final available count can be lower than the submitted count. For example, 498 submitted companies can produce 413 published results when 85 do not meet the configured contactability or quality requirements.

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	Schema limit: between 1 and 10,000 JSON company objects
`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.

The item limit is independent of the HTTP request-body limit. Deployments accept at most 10 MB by default (10,485,760 bytes), so a field-heavy request can reach the byte limit before 10,000 companies. Serialize the JSON before submission and split it into smaller orders if it approaches 10 MB. An oversized request returns 413 with a detail message.

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,
  "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.

Prepare Company Data from CSV¶

The order endpoint accepts JSON. It does not accept CSV uploads. Convert each CSV row to one object in companies before submitting the order.

For example, map a source file with these common columns:

Source CSV column	Request field
`external_id`	`external_id`
`firm_name`	`company_name`
`website`	`website_url`
`city`	`city`
`plz`	`postal_code`

One mapped row has this shape:

{
  "external_id": "crm-1001",
  "company_name": "Example Manufacturing GmbH",
  "website_url": "https://example-manufacturing.de",
  "city": "Berlin",
  "postal_code": "10115"
}

Use a stable, unique external_id when you need to match enriched results back to your CRM. OpenProspect returns that value as the company-level source_id.

Idempotent Retries¶

Generate one Idempotency-Key for each logical order. If a network failure leaves the response uncertain, retry the identical body with the same key. Use a new key whenever you change the request body. Reusing a key with a different body returns 409.

Lifecycle¶

External clients submit an order, poll its status, and retrieve completed results. OpenProspect performs review and managed fulfillment internally. A requested feature describes the expected result; it is not a client-invoked processing step.

Status	Class	Meaning	Client action
`RECEIVED`	Active	The API accepted the order for review; enrichment is not complete	Poll again
`ACCEPTED`	Active	OpenProspect approved the order for managed fulfillment	Poll again
`IN_PROGRESS`	Active	OpenProspect is producing the requested results	Poll again
`COMPLETED`	Successful terminal	Managed fulfillment ended	Retrieve pages only when `results_published` is `true`; otherwise contact support
`REJECTED`	Unsuccessful terminal	The order was not approved	Stop polling and contact support with the order ID
`FAILED`	Unsuccessful terminal	Fulfillment failed	Stop polling and contact support with the order ID
`CANCELLED`	Unsuccessful terminal	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. The result resource is an immutable order snapshot; later profile changes do not rewrite it.

Every submitted row comes back as one item, in submitted order. Each item echoes your external_id, carries a status with reason_codes, and holds the enriched company (with embedded prospects) or null when the identity could not be resolved. The company-level source_id also matches the submitted external_id.

`status`	Meaning
`ENRICHED`	Resolved and policy-eligible; contacts selected by the profile policy
`PARTIAL`	Resolved, but the profile policy annotated the row (see `reason_codes`); company facts only
`UNRESOLVED`	No company matched the submitted identity; `company` is `null`
`DUPLICATE`	Resolved to the same company as `duplicate_of_input_position`
`BLOCKED`	Held for operator review

Query parameter	Type	Required	Description
`limit`	integer	No	Slots per page, from 1 to 100; default 50
`offset`	integer	No	Number of slots to skip; default 0

Continue requesting pages while has_more is true. Increase offset by the number of items returned on the current page. A 199-company order takes two requests at limit=100; a single request without pagination returns only the first 50 companies by default.

Each delivered prospect can include:

Field	Meaning
`email_status`	Validation status, such as `VERIFIED` or `UNVERIFIED`
`email_type`	Email category: `PERSONAL`, `GENERAL`, or `UNKNOWN`
`email_delivery_quality`	Authoritative risk tier, such as `client_deliverable` or `risky_internal_catchall`
`email_delivery_quality_reason`	Reason behind the `email_delivery_quality` decision
`email_client_deliverable`	OpenProspect's default-campaign safety decision

If your integration accepts only verified emails, keep prospects whose email_status == "VERIFIED". If you want OpenProspect's stricter default-campaign policy, also require email_client_deliverable == true. The boolean is a policy decision, not an alias for email_status.

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

Do not reconcile the order through GET /api/v1/deliveries/{prospect_search_id}/companies. That endpoint is legacy profile-wide CRM sync / drip and can include companies from other orders. The order-scoped result pages (GET /api/v1/orders/{order_id}/results) are the authoritative population for this order.

See the Enrichment Quick Start for lossless examples in all supported languages.

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

See Error Handling for authentication, authorization, validation, retry, and terminal-status recovery.