Skip to content

API Changelog

The public API contract is versioned independently of the platform release. The current contract version appears as info.version in the OpenAPI document.

1.1.0

Orders became atomic and API-first: an order is COMPLETED only when its immutable result set is published, and GET /api/v1/orders/{order_id}/results is the primary delivery channel.

Breaking changes

  • Delivered-company prospect lists now contain only the delivered contacts. GET /api/v1/deliveries/{prospect_search_id}/companies and GET /api/v1/orders/{order_id}/results re-apply the search profile's delivery quality policy on read (qualification floor and per-company cap — the same selection that produced the delivery). Previously every prospect row linked to a delivered company was returned, including unqualified and unvalidated contacts that were never part of the delivery.
  • validation_confidence and bounce_risk_score were removed from delivered prospect responses. Both were derived from email_status and carried no independent signal, so ranking bounce risk by them was misleading. Use email_delivery_quality and email_client_deliverable instead.
  • estimated_cost was removed from the order create and order status responses. Pricing is agreed individually per client and is never derived from an automated estimate. Regenerate clients from the current OpenAPI document; previously generated clients that require this field will fail to parse order responses until regenerated.
  • delivered_since was removed from GET /orders/{order_id}/results. Results are now published once as one immutable set, so incremental delivery-time filtering no longer applies. Retrieve the full paginated set; each result item carries its own delivered_at.
  • admin_notes and webhook_url were removed from the customer order status response. Rejection follow-up goes through support; the webhook URL remains a write-only order-creation field for status notifications.
  • organization_id was removed from order list items. The authenticated API key already fixes the organization context.

Added

  • email_delivery_quality and email_delivery_quality_reason on delivered prospects: the authoritative email risk tier the delivery pipeline itself applies (for example client_deliverable, generic_company_tier, risky_internal_catchall), matching the columns CSV exports already ship.
  • GET /api/v1/deliveries/{prospect_search_id}/companies/{company_id}/website-markdown: verified website crawl ground truth for a delivered company — the aggregate optimized markdown that OpenProspect's own extraction and analysis consume, with crawl provenance (observed_at, URLs, content fingerprint).
  • results_published on order status and list responses: the readiness signal for result retrieval. A published zero-result order is valid.
  • Immutable order results: repeated retrieval always returns identical content, unaffected by later data changes.
  • Optional outputs (POST /api/v1/orders/{order_id}/outputs) projecting the published result set to CSV, XLSX, or Google Sheets, with durable receipts, idempotent replay, and the created flag distinguishing replays.

Changed

  • available_briefing_quantity now counts the immutable published result set rather than live delivery tracking rows.
  • Error responses for order results and exports now declare their complete status sets, including 409 and 500 invariant refusals. See Error Handling.

1.0.0

Initial public contract: orders, order results, profile companies, prospect searches, blacklists, and exports.