Getting Started with LaborLens API

Get up and running with the LaborLens API in just a few minutes. This guide will walk you through authentication, API key creation, and making your first API call.

Quick Start

Authentication

The LaborLens API uses Bearer Token authentication. Include your API key in the Authorization header of every request:

Code
 
Authorization: Bearer YOUR_API_KEY_HERE

Rate Limits

The API is rate-limited to 50 requests per minute per API key. Rate limit information is included in response headers:

• X-RateLimit-Limit: Maximum requests per window
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when rate limit resets

Available Endpoints

The LaborLens API provides four main endpoints:

Endpoint	Purpose	Use Case
GET /industries	Get industry classifications	Discover filter options for searches
POST /search	Search plan sponsors	Find companies matching specific criteria
GET /sponsor/{id}	Get sponsor details	Deep dive into a specific company's plans
GET /filing/{ack_id}	Get filing details	Access specific regulatory filing data

Common Search Patterns

Find Companies by Industry

Code
 
{
  "industries": ["Technology", "Software"],
  "min_total_participants": 500
}

Find Large Retirement Plans

Code
 
{
  "min_active_participants": 1000,
  "min_total_participants": 2000
}

Search by Company Name

Code
 
{
  "query": "apple inc"
}

Pagination Example: Fetching All Results

When working with large datasets, you'll often need to paginate through results. Here's a complete Python example that demonstrates how to fetch all plan sponsors from a specific industry:

Code
 
import requests
import json
import csv
from typing import List, Dict, Any

def fetch_all_results(industries: List[str]) -> List[Dict[str, Any]]:
    url = "https://laborpulse-api-main-86f2470.zuplo.app/search"
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY_HERE'
    }
    
    all_results = []
    start = 1
    
    while True:
        payload = json.dumps({
            "industries": industries,
            "start": start
        })
        
        response = requests.post(url, headers=headers, data=payload)
        response.raise_for_status()
        
        data = response.json()
        results = data.get('results', [])
        
        if not results:
            break
            
        all_results.extend(results)
        print(f"Fetched {len(results)} results (page starting at {start}). Total so far: {len(all_results)}")
        
        start += 1
    
    return all_results

def save_to_csv(results: List[Dict[str, Any]], filename: str = 'industry_report.csv'):
    if not results:
        print("No results to save")
        return
    
    # Collect all unique field names from all records
    fieldnames = set()
    for result in results:
        fieldnames.update(result.keys())
    fieldnames = sorted(fieldnames)
    
    with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(results)
    
    print(f"Saved {len(results)} records to {filename}")

def main():
    # Example: Fetch all results for NAICS code 621210 (Dental Offices)
    industries = ["621210"]
    
    print("Starting to fetch all results...")
    results = fetch_all_results(industries)
    
    print(f"Total results fetched: {len(results)}")
    save_to_csv(results)

if __name__ == "__main__":
    main()

This example demonstrates:

• Pagination Logic: Incrementing the start parameter until no more results are returned
• Rate Limiting: The loop naturally respects rate limits as it makes sequential requests
• Data Export: Saving all results to a CSV file for analysis
• Progress Tracking: Logging the pagination progress

Error Handling

The API returns standard HTTP status codes:

• 200: Success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (invalid/missing API key)
• 429: Rate Limit Exceeded
• 500: Internal Server Error

Error responses include detailed information to help debug issues:

Code
 
{
  "message": "Invalid search parameters: 'min_participants' must be a positive integer",
  "status_code": 400
}

Next Steps

• Explore the full API Reference for detailed endpoint documentation
• Check your usage and manage API keys in Access & Usage
• Review the About page to understand the full scope of available data

Ready to start building? Head over to the API Reference to see all available parameters and response schemas.

Support

Need help getting started or have questions about the API? Contact our support team at support@laborlens.io.