Skip to content

Quick Start

Quick Start Guide

Get started with the OpenProspect API in under 5 minutes. This guide walks you through making your first API call to retrieve company data.

Prerequisites

  • API key with companies:read scope
  • A prospect search ID (UUID) from your OpenProspect account
  • cURL, Python, or your preferred HTTP client

Don't have an API key?

Contact your OpenProspect account manager to request API access for your organization.

Step 1: Test Your API Key

Verify your API key works by calling the health endpoint:

Bash
curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  https://api.openprospect.io/health

Expected response:

JSON
{
  "service": "OpenProspect API",
  "status": "healthy"
}

API Key Valid

If you receive a healthy response, your API key is configured correctly!

401 Unauthorized

If you receive a 401 error, verify:

  • Your API key is correct and not revoked
  • The key includes the lnc_live_ prefix
  • The Authorization header format is exactly: Bearer lnc_live_...

Step 2: Get Your Prospect Search ID

Log into your OpenProspect dashboard and:

  1. Navigate to Prospect Searches
  2. Select the search you want to access via API
  3. Copy the UUID from the URL: app.openprospect.io/searches/<uuid>

The UUID will look like: 550e8400-e29b-41d4-a716-446655440000

Step 3: Retrieve Companies

Now fetch companies from your prospect search:

Bash
curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  "https://api.openprospect.io/api/v1/companies/?prospect_search_id=550e8400-e29b-41d4-a716-446655440000&limit=10"
Python
import requests

api_key = "lnc_live_your_api_key_here"
prospect_search_id = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    "https://api.openprospect.io/api/v1/companies/",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "prospect_search_id": prospect_search_id,
        "limit": 10
    }
)

companies = response.json()
print(f"Retrieved {len(companies['items'])} companies")
TypeScript
const apiKey = "lnc_live_your_api_key_here";
const prospectSearchId = "550e8400-e29b-41d4-a716-446655440000";

const response = await fetch(
  `https://api.openprospect.io/api/v1/companies/?prospect_search_id=${prospectSearchId}&limit=10`,
  {
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  }
);

const companies = await response.json();
console.log(`Retrieved ${companies.items.length} companies`);

Step 4: Understand the Response

The API returns paginated company data:

JSON
{
  "items": [
    {
      "id": "7f3e8c90-1234-5678-9abc-def012345678",
      "name": "Acme Corporation",
      "city": "San Francisco",
      "country": "United States",
      "business_type": "B2B SaaS",
      "website": "https://acme.com",
      "match_score": 8.5,
      "review_status": "accepted",
      "contacts": [
        {
          "name": "John Doe",
          "title": "CEO",
          "email": "john@acme.com"
        }
      ]
    }
  ],
  "total": 157,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Key Response Fields

  • items: Array of company objects
  • total: Total number of companies in the search
  • limit: Number of results per page (max 100)
  • offset: Current pagination offset
  • has_more: Whether more results are available

Step 5: Filter Results (Optional)

Apply filters to narrow down results:

Bash
curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  "https://api.openprospect.io/api/v1/companies/?prospect_search_id=<uuid>&min_match_score=7.0&review_status=accepted&limit=20"

Available filters:

  • min_match_score - Minimum match score (0-10)
  • review_status - Filter by accepted, rejected, or pending
  • search - Text search across company name, city, and contacts
  • limit - Results per page (1-100, default 50)
  • offset - Pagination offset (default 0)

Next Steps

Now that you've made your first API call, explore more:

Common Issues

403 Forbidden

Your API key doesn't have the required companies:read scope. Contact your account manager to update your key permissions.

404 Not Found

The prospect search ID doesn't exist or doesn't belong to your organization. Verify the UUID is correct.

429 Too Many Requests

You've exceeded your rate limit. Wait for the rate limit to reset (check X-RateLimit-Reset header) or upgrade your tier.

Need Help?