API Overview

The OpenProspect external API lets you create reusable search profiles, place profile-based briefing orders, read order status, fetch delivered companies and prospects, and manage company blacklists.

All external requests use API-key bearer authentication. Internal Hanko frontend authentication is not part of the external developer API.

Base URL

https://api.openprospect.io

Endpoint Inventory

These endpoints are included in the public OpenAPI document.

Method	Endpoint	Required scope
GET	/api/v1/auth/validate	Any active API key
POST	/api/v1/search-profile-creations	orders:write
GET	/api/v1/search-profile-creations/{profile_creation_id}	orders:read
POST	/api/v1/orders	orders:write
GET	/api/v1/orders	orders:read
GET	/api/v1/orders/{order_id}	orders:read
GET	/api/v1/orders/{order_id}/results	orders:read
POST	/api/v1/orders/{order_id}/export	orders:read
POST	/api/v1/orders/{order_id}/outputs	orders:write
GET	/api/v1/orders/{order_id}/outputs	orders:read
GET	/api/v1/orders/{order_id}/outputs/{output_id}	orders:read
GET	/api/v1/exports/batches/{batch_id}/stream	orders:read
GET	/api/v1/exports/jobs/{job_id}/download	orders:read
GET	/api/v1/deliveries/{prospect_search_id}/companies	companies:read, prospects:read
GET	/api/v1/deliveries/{prospect_search_id}/companies/{company_id}/website-markdown	delivery:read
GET	/api/v1/prospect-searches	prospect_searches:read
POST	/api/v1/blacklists	blacklists:write
GET	/api/v1/blacklists	blacklists:read
GET	/api/v1/blacklists/{blacklist_id}	blacklists:read
PATCH	/api/v1/blacklists/{blacklist_id}	blacklists:write
DELETE	/api/v1/blacklists/{blacklist_id}	blacklists:write
POST	/api/v1/blacklists/{blacklist_id}/entries	blacklists:write
GET	/api/v1/blacklists/{blacklist_id}/entries	blacklists:read
DELETE	/api/v1/blacklists/{blacklist_id}/entries	blacklists:write
GET	/api/v1/prospect-searches/{prospect_search_id}/blacklists	blacklists:read
PUT	/api/v1/prospect-searches/{prospect_search_id}/blacklists	blacklists:write

The deliveries companies collection is legacy profile-wide CRM sync / drip, not how you read an order. Reconcile orders with GET /api/v1/orders/{order_id}/results.

First Calls

1. Validate your key with Authentication.
2. Understand the profile-first Orders Overview.
3. Create and poll a reusable Search Profile.
4. Create a Discovery or Enrichment order with the returned profile_id.
5. Fetch a completed order's companies only from GET /api/v1/orders/{order_id}/results. Use Delivery Integration only for legacy profile-wide CRM sync / drip.
6. Inspect schemas in Interactive API.

Response Format

Success responses are JSON. Error responses use a stable object with a machine-readable code and a human-readable message.

{
  "code": "AUTHORIZATION_ERROR",
  "message": "Missing required scopes: orders:write",
  "details": {
    "required_scopes": ["orders:write"]
  }
}

See Error Handling for status codes and examples.