Companies API

Companies API¶

The Companies API provides access to company data from your prospect searches, including contact information, match scores, and related data like job listings and technology stacks.

Endpoints¶

Method	Endpoint	Description
GET	`/api/v1/companies/`	List companies from a prospect search
GET	`/api/v1/companies/{company_id}`	Get a single company by ID
GET	`/api/v1/companies/{company_id}/jobs`	Get job listings for a company
GET	`/api/v1/companies/{company_id}/jobs/summary`	Get job activity summary
GET	`/api/v1/companies/{company_id}/webtech-intel`	Get technology stack details
GET	`/api/v1/companies/{company_id}/webtech-intel/summary`	Get technology summary

List Companies¶

Retrieve a paginated list of companies from a prospect search with optional filtering.

HTTP

GET /api/v1/companies/?prospect_search_id={uuid}&limit=50&offset=0

Query Parameters¶

Parameter	Type	Required	Description
`prospect_search_id`	UUID	Yes	ID of the prospect search
`limit`	integer	No	Results per page (1-100, default: 50)
`offset`	integer	No	Pagination offset (default: 0)
`min_match_score`	float	No	Minimum match score (0-10)
`review_status`	string	No	Filter by `accepted`, `rejected`, or `pending`
`review_status_list`	array	No	Filter by multiple statuses (preferred over `review_status`)
`search`	string	No	Text search across company name, city, business type, contacts

Example Request¶

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&min_match_score=7.0&review_status=accepted&limit=20"

Example Response¶

JSON

{
  "items": [
    {
      "id": "7f3e8c90-1234-5678-9abc-def012345678",
      "prospect_search_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corporation",
      "city": "San Francisco",
      "country": "United States",
      "business_type": "B2B SaaS",
      "website": "https://acme.com",
      "match_score": 8.5,
      "review_status": "accepted",
      "phone": "+1-415-555-0123",
      "contacts": [
        {
          "id": "9e2f7c80-5678-1234-9abc-def012345678",
          "name": "John Doe",
          "title": "CEO",
          "email": "john@acme.com",
          "linkedin_url": "https://linkedin.com/in/johndoe"
        }
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:22:00Z"
    }
  ],
  "total": 157,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

Response Fields¶

Field	Type	Description
`items`	array	Array of company objects
`total`	integer	Total number of companies matching filters
`limit`	integer	Number of results per page
`offset`	integer	Current pagination offset
`has_more`	boolean	Whether more results are available

Company Object¶

Field	Type	Description
`id`	UUID	Unique company identifier
`prospect_search_id`	UUID	Associated prospect search
`name`	string	Company name
`city`	string	Company city
`country`	string	Company country
`business_type`	string	Business model/industry
`website`	string	Company website URL
`match_score`	float	AI-calculated match score (0-10)
`review_status`	string	`accepted`, `rejected`, or `pending`
`phone`	string	Company phone number (optional)
`contacts`	array	Array of contact objects
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

Get Single Company¶

Retrieve detailed information about a specific company.

HTTP

GET /api/v1/companies/{company_id}

Path Parameters¶

Parameter	Type	Required	Description
`company_id`	UUID	Yes	Company identifier

Example Request¶

Bash

curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  https://api.openprospect.io/api/v1/companies/7f3e8c90-1234-5678-9abc-def012345678

Example Response¶

Returns a single company object (same structure as in list response).

Get Company Job Listings¶

Retrieve active job postings for a company with hiring activity metrics.

HTTP

GET /api/v1/companies/{company_id}/jobs?days_back=30&limit=50

Path Parameters¶

Parameter	Type	Required	Description
`company_id`	UUID	Yes	Company identifier

Query Parameters¶

Parameter	Type	Required	Description
`days_back`	integer	No	Days to look back (1-365, default: 30)
`platform`	string	No	Filter by platform (e.g., 'linkedin', 'indeed')
`limit`	integer	No	Results per page (1-200, default: 50)
`offset`	integer	No	Pagination offset (default: 0)

Example Request¶

Bash

curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  "https://api.openprospect.io/api/v1/companies/7f3e8c90-1234-5678-9abc-def012345678/jobs?days_back=30&limit=20"

Example Response¶

JSON

{
  "jobs": [
    {
      "id": "job-123",
      "title": "Senior Software Engineer",
      "platform": "linkedin",
      "date_posted": "2024-01-10T00:00:00Z",
      "job_url": "https://linkedin.com/jobs/view/123456"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0,
  "has_more": false,
  "activity_strength": "MODERATE",
  "velocity_per_month": 2.5
}

Activity Strength Levels¶

Level	Description	Jobs per Month
`STRONG`	Actively recruiting	≥ 3.0
`MODERATE`	Steady hiring	≥ 1.5
`LIGHT`	Occasional hiring	≥ 0.5
`NONE`	Minimal activity	< 0.5

Get Company Job Summary¶

Get lightweight hiring activity metrics with the most recently posted job.

HTTP

GET /api/v1/companies/{company_id}/jobs/summary?days_back=30

Example Request¶

Bash

curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  "https://api.openprospect.io/api/v1/companies/7f3e8c90-1234-5678-9abc-def012345678/jobs/summary"

Example Response¶

JSON

{
  "total": 15,
  "activity_strength": "MODERATE",
  "velocity_per_month": 2.5,
  "latest_job": {
    "id": "job-123",
    "title": "Senior Software Engineer",
    "platform": "linkedin",
    "date_posted": "2024-01-10T00:00:00Z"
  }
}

Get Company Technology Stack¶

Retrieve detailed technology stack information with filtering and pagination.

HTTP

GET /api/v1/companies/{company_id}/webtech-intel?category=javascript_framework&min_confidence=80

Query Parameters¶

Parameter	Type	Required	Description
`category`	string	No	Filter by technology category
`min_confidence`	integer	No	Minimum confidence score (0-100, default: 0)
`limit`	integer	No	Results per page (1-200, default: 100)
`offset`	integer	No	Pagination offset (default: 0)

Example Request¶

Bash

curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  "https://api.openprospect.io/api/v1/companies/7f3e8c90-1234-5678-9abc-def012345678/webtech-intel?min_confidence=80"

Example Response¶

JSON

{
  "technologies": [
    {
      "name": "React",
      "category": "javascript_framework",
      "confidence": 95,
      "version": "18.2.0"
    },
    {
      "name": "Google Analytics",
      "category": "analytics",
      "confidence": 100
    }
  ],
  "total": 23,
  "limit": 100,
  "offset": 0,
  "has_more": false,
  "scan_successful": true,
  "status": "completed"
}

Get Company Technology Summary¶

Get lightweight technology stack summary with top 3-5 technologies.

HTTP

GET /api/v1/companies/{company_id}/webtech-intel/summary

Example Request¶

Bash

curl -H "Authorization: Bearer lnc_live_your_api_key_here" \
  https://api.openprospect.io/api/v1/companies/7f3e8c90-1234-5678-9abc-def012345678/webtech-intel/summary

Example Response¶

JSON

{
  "top_technologies": [
    {
      "name": "React",
      "category": "javascript_framework",
      "confidence": 95
    },
    {
      "name": "Node.js",
      "category": "programming_language",
      "confidence": 90
    }
  ],
  "total_technologies": 23,
  "category_counts": {
    "javascript_framework": 3,
    "analytics": 5,
    "programming_language": 2
  },
  "scan_successful": true,
  "status": "completed"
}

Error Responses¶

400 Bad Request¶

Invalid request parameters:

JSON

{
  "error": "BAD_REQUEST",
  "message": "Invalid request data"
}

403 Forbidden¶

Insufficient permissions:

JSON

{
  "error": "FORBIDDEN",
  "message": "Insufficient scopes. Required: companies:read"
}

404 Not Found¶

Resource not found:

JSON

{
  "error": "NOT_FOUND",
  "message": "Company with ID 7f3e8c90-1234-5678-9abc-def012345678 not found"
}

Rate Limits¶

All endpoints are subject to rate limits based on your API key tier. See API Overview for details.

Code Examples¶

See complete integration examples:

Next Steps¶

Quick Start Guide - Make your first API call
Authentication - Learn about API key security
Python Examples - Complete Python integration