Skip to content

Overview

API Overview

The OpenProspect Developer API is a REST API that provides programmatic access to company data from your prospect searches.

Base URL

All API requests should be made to:

Text Only
https://api.openprospect.io

For staging/testing:

Text Only
https://api.staging.openprospect.io

Authentication

All API requests require authentication via API key:

HTTP
Authorization: Bearer lnc_live_your_api_key_here

Learn more about authentication →

Request Format

The API accepts requests with:

  • Method: Standard HTTP methods (GET, POST, PUT, DELETE)
  • Headers: JSON content type for request bodies
  • Parameters: Query parameters for GET requests, JSON body for POST/PUT

Example request:

HTTP
GET /api/v1/companies/?prospect_search_id=<uuid>&limit=10 HTTP/1.1
Host: api.openprospect.io
Authorization: Bearer lnc_live_your_api_key_here
Accept: application/json

Response Format

All responses are returned in JSON format:

JSON
{
  "items": [...],
  "total": 157,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Success Responses

  • 200 OK: Request successful, response body contains data
  • 201 Created: Resource created successfully
  • 204 No Content: Request successful, no response body

Error Responses

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: API key lacks required permissions
  • 404 Not Found: Resource doesn't exist
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error, contact support

Error response format:

JSON
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}

Pagination

All list endpoints support offset-based pagination:

HTTP
GET /api/v1/companies/?prospect_search_id=<uuid>&limit=50&offset=0

Parameters:

  • limit - Number of results per page (1-100, default 50)
  • offset - Number of results to skip (default 0)

Response:

JSON
{
  "items": [...],
  "total": 237,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

To get the next page:

HTTP
GET /api/v1/companies/?prospect_search_id=<uuid>&limit=50&offset=50

Rate Limiting

Rate limits are enforced per API key and returned in response headers:

HTTP
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Rate Limit Tiers:

  • Free: 100 requests/hour
  • Pro: 1,000 requests/hour
  • Enterprise: Custom limits

When limit exceeded, you'll receive a 429 response:

JSON
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Retry after 3600 seconds.",
  "retry_after": 3600
}

Filtering

List endpoints support filtering via query parameters:

HTTP
GET /api/v1/companies/?prospect_search_id=<uuid>&min_match_score=7.0&review_status=accepted

Common filters:

  • min_match_score - Minimum match score (0-10)
  • review_status - Filter by acceptance status
  • search - Text search across multiple fields

See Companies API for available filters →

Data Types

UUID

All IDs are UUIDs in standard format:

Text Only
550e8400-e29b-41d4-a716-446655440000

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

Text Only
2024-01-15T10:30:00Z

Match Scores

Match scores are floats from 0.0 to 10.0:

JSON
{
  "match_score": 8.5
}

Versioning

The API is versioned via URL path:

Text Only
https://api.openprospect.io/api/v1/companies/

Current version: v1

Breaking changes will be introduced in new versions (v2, v3, etc.). Non-breaking changes may be added to existing versions.

SDK Support

Official SDKs coming soon:

  • 🔜 Python SDK
  • 🔜 TypeScript/JavaScript SDK
  • 🔜 Go SDK

For now, use standard HTTP clients. See our code examples for integration patterns.

OpenAPI Specification

Download the full OpenAPI spec:

Text Only
https://api.openprospect.io/openapi-public.json

Import this into tools like:

  • Postman
  • Insomnia
  • OpenAPI Generator
  • Swagger UI

Support