API Reference

CompanyLens API Documentation

One API for complete corporate intelligence. Aggregates SEC, Companies House, OpenSanctions, USAspending, SAM.gov, TED, CourtListener, EPA, FDA, and EUIPO data -- built for AI agents.

Base URL

https://companylensapi.vercel.app

All endpoints are prefixed with /v1.

Getting Started

Authentication

Generate an API key, then include it as a Bearer token in every request.

1. Generate an API key

POST /v1/keys

          Request
        
POST https://companylensapi.vercel.app/v1/keys
Content-Type: application/json

{
  "email": "agent@example.com",
  "name": "My AI Agent"
}

          Response
        
{
  "api_key": "cl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "message": "Store this key securely. It will not be shown again.",
  "agent_hint": "Save this key. Use it as Authorization: Bearer cl_live_... in all subsequent requests."
}

2. Use the key in requests

          Authorization Header
        
Authorization: Bearer cl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Important: Store your API key securely. It is shown only once upon creation and cannot be recovered.

Rate Limits

During the beta period, each API key is limited to:

Limit	Value
Requests per day	1,000
Burst (per minute)	60
Bulk check batch size	20 companies

When limits are exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Endpoints

Search Companies

Find companies by name across US (SEC EDGAR) and UK (Companies House) registries.

GET /v1/company/search

Parameters

Name	Type	Required	Description
q	string	required	Company name or search query
jurisdiction	string	optional	Filter by jurisdiction: `us`, `uk`, or `all` (default: `all`)
limit	integer	optional	Number of results, 1-50 (default: 10)

          Request
        
GET https://companylensapi.vercel.app/v1/company/search?q=Tesla&jurisdiction=us&limit=3
Authorization: Bearer cl_live_...

          Response
        
{
  "results": [
    {
      "id": "us_sec_1318605",
      "name": "Tesla, Inc.",
      "jurisdiction": "us",
      "source": "sec_edgar",
      "identifiers": { "cik": "1318605", "ticker": "TSLA" }
    },
    {
      "id": "uk_ch_11460060",
      "name": "TESLA MOTORS LTD",
      "jurisdiction": "uk",
      "source": "companies_house",
      "identifiers": { "company_number": "11460060" }
    }
  ],
  "total": 2,
  "agent_hint": "Use the id field to call /v1/company/{id}/profile for detailed information."
}

Next Steps

Use the returned id to fetch the company profile, sanctions status, contracts, court cases, regulatory actions, or risk score.

Company Profile

Retrieve comprehensive company details from SEC EDGAR (US) or Companies House (UK), including officers, filings, and financial data.

GET /v1/company/{id}/profile

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results (e.g. `us_sec_1318605`)

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/profile
Authorization: Bearer cl_live_...

          Response
        
{
  "id": "us_sec_1318605",
  "name": "Tesla, Inc.",
  "jurisdiction": "us",
  "sic": "3711",
  "sic_description": "Motor Vehicle & Passenger Car Bodies",
  "incorporated_state": "DE",
  "addresses": {
    "business": {
      "street": "1 Tesla Road",
      "city": "Austin",
      "state": "TX",
      "zip": "78725"
    }
  },
  "officers": [
    { "name": "Elon Musk", "title": "Chief Executive Officer" },
    { "name": "Vaibhav Taneja", "title": "Chief Financial Officer" }
  ],
  "recent_filings": [
    { "type": "10-K", "date": "2025-02-07", "url": "https://www.sec.gov/..." }
  ],
  "tickers": ["TSLA"],
  "exchanges": ["NASDAQ"],
  "agent_hint": "Profile loaded. Check /sanctions for risk flags, /contracts for government work, /court-cases for litigation."
}

Next Steps

After fetching the profile, call /v1/company/{id}/sanctions for sanctions screening or /v1/company/{id}/risk-score for an aggregated risk assessment.

Sanctions Screening

Screen a company against OpenSanctions global watchlists including OFAC SDN, EU sanctions, UN lists, and PEP databases.

GET /v1/company/{id}/sanctions

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/sanctions
Authorization: Bearer cl_live_...

          Response (Clean)
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "screened_at": "2026-03-26T12:00:00Z",
  "status": "clear",
  "matches": [],
  "datasets_checked": ["ofac_sdn", "eu_sanctions", "un_consolidated", "pep_databases"],
  "agent_hint": "No sanctions matches found. Company appears clear for compliance purposes. Proceed to /contracts or /risk-score."
}

          Response (Match Found)
        
{
  "company_id": "us_sec_9999999",
  "company_name": "Sanctioned Corp Ltd",
  "screened_at": "2026-03-26T12:00:00Z",
  "status": "matched",
  "matches": [
    {
      "score": 0.95,
      "dataset": "ofac_sdn",
      "entity_name": "SANCTIONED CORP LIMITED",
      "topics": ["sanction"],
      "countries": ["RU"]
    }
  ],
  "agent_hint": "SANCTIONS MATCH DETECTED (score: 0.95). Flag for compliance review. Do NOT proceed with onboarding."
}

Next Steps

If status is "clear", continue with contracts/regulatory checks. If "matched", flag for human compliance review.

Government Contracts

Retrieve government contract awards and opportunities from three sources: USAspending (US awards), SAM.gov (US opportunities), and TED (EU tenders).

GET /v1/company/{id}/contracts

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/contracts
Authorization: Bearer cl_live_...

          Response
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "us_awards": [
    {
      "source": "usaspending",
      "award_id": "CONT_AWD_47QFCA20F0035",
      "description": "Electric Vehicle Fleet Purchase",
      "awarding_agency": "General Services Administration",
      "amount": 12450000,
      "start_date": "2025-06-15",
      "end_date": "2027-06-14"
    }
  ],
  "us_opportunities": [
    {
      "source": "sam_gov",
      "notice_id": "fa8601-26-r-0042",
      "title": "Battery Storage Systems for DoD Installations",
      "type": "solicitation",
      "posted_date": "2026-03-10",
      "response_deadline": "2026-04-15"
    }
  ],
  "eu_tenders": [
    {
      "source": "ted",
      "notice_id": "2026/S 045-098765",
      "title": "Electric Vehicle Charging Infrastructure - City of Berlin",
      "buyer": "Berliner Verkehrsbetriebe",
      "value_eur": 8200000,
      "deadline": "2026-05-01"
    }
  ],
  "agent_hint": "Found 1 US award ($12.4M), 1 SAM.gov opportunity, 1 EU tender. Check /court-cases and /regulatory for risk factors."
}

Next Steps

Review contract amounts and agencies. For due diligence, combine with /sanctions and /regulatory data.

Court Cases

Search federal court cases involving the company via CourtListener (RECAP archive of US federal courts).

GET /v1/company/{id}/court-cases

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/court-cases
Authorization: Bearer cl_live_...

          Response
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "cases": [
    {
      "case_name": "Smith v. Tesla, Inc.",
      "docket_number": "3:25-cv-04821",
      "court": "N.D. Cal.",
      "date_filed": "2025-09-14",
      "status": "open",
      "nature_of_suit": "Product Liability",
      "url": "https://www.courtlistener.com/docket/..."
    },
    {
      "case_name": "SEC v. Tesla, Inc.",
      "docket_number": "1:18-cv-08865",
      "court": "S.D.N.Y.",
      "date_filed": "2018-09-27",
      "status": "closed",
      "nature_of_suit": "Securities/Commodities",
      "url": "https://www.courtlistener.com/docket/..."
    }
  ],
  "total": 2,
  "agent_hint": "Found 2 federal cases (1 open, 1 closed). Review nature_of_suit for risk categorization. Check /regulatory for additional compliance data."
}

Next Steps

Combine court case data with /regulatory for a complete legal/compliance picture. Use /risk-score for an aggregated assessment.

Regulatory Actions

Retrieve EPA ECHO environmental violations and FDA product recalls associated with the company.

GET /v1/company/{id}/regulatory

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/regulatory
Authorization: Bearer cl_live_...

          Response
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "epa_violations": [
    {
      "source": "epa_echo",
      "facility_name": "Tesla Fremont Factory",
      "registry_id": "110071488870",
      "program": "CAA",
      "violation_status": "resolved",
      "compliance_status": "In Compliance",
      "last_inspection": "2025-08-12"
    }
  ],
  "fda_recalls": [
    {
      "source": "fda",
      "recall_number": "V-0892-2025",
      "product": "Model Y Touchscreen Unit",
      "classification": "Class II",
      "status": "Ongoing",
      "initiated_date": "2025-11-03",
      "reason": "Software malfunction may cause display failure"
    }
  ],
  "agent_hint": "1 EPA violation (resolved), 1 FDA recall (ongoing, Class II). EPA compliance is current. Flag the active FDA recall for review."
}

Next Steps

Pay attention to classification for FDA recalls (Class I = most serious). Use /risk-score for an aggregated view of all risk factors.

Risk Score

Get an aggregated risk score (0-100) based on sanctions, litigation, regulatory actions, and other factors. Higher scores indicate higher risk.

GET /v1/company/{id}/risk-score

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/risk-score
Authorization: Bearer cl_live_...

          Response
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "risk_score": 34,
  "risk_level": "medium",
  "factors": [
    {
      "category": "sanctions",
      "score": 0,
      "detail": "No sanctions matches"
    },
    {
      "category": "litigation",
      "score": 15,
      "detail": "2 federal cases found (1 open)"
    },
    {
      "category": "regulatory",
      "score": 12,
      "detail": "1 active FDA recall (Class II)"
    },
    {
      "category": "environmental",
      "score": 5,
      "detail": "1 resolved EPA violation, currently in compliance"
    },
    {
      "category": "government_contracts",
      "score": 2,
      "detail": "Active government contractor, no debarments"
    }
  ],
  "computed_at": "2026-03-26T12:00:00Z",
  "agent_hint": "Risk score 34/100 (medium). Main contributors: open litigation (15) and active FDA recall (12). No sanctions risk. Suitable for standard due diligence."
}

Next Steps

Use the factors array to explain the score breakdown to users. Scores 0-25 = low, 26-50 = medium, 51-75 = high, 76-100 = critical.

Trademarks

Search EU trademarks registered with EUIPO (European Union Intellectual Property Office) for the company.

GET /v1/company/{id}/trademarks

Parameters

Name	Type	Required	Description
id	string	required	Company ID from search results

          Request
        
GET https://companylensapi.vercel.app/v1/company/us_sec_1318605/trademarks
Authorization: Bearer cl_live_...

          Response
        
{
  "company_id": "us_sec_1318605",
  "company_name": "Tesla, Inc.",
  "trademarks": [
    {
      "application_number": "018245673",
      "mark_name": "TESLA",
      "status": "Registered",
      "filing_date": "2019-04-12",
      "registration_date": "2019-09-27",
      "nice_classes": [12, 9, 37],
      "owner": "Tesla, Inc."
    },
    {
      "application_number": "018512890",
      "mark_name": "CYBERTRUCK",
      "status": "Registered",
      "filing_date": "2021-01-18",
      "registration_date": "2021-07-05",
      "nice_classes": [12],
      "owner": "Tesla, Inc."
    }
  ],
  "total": 2,
  "agent_hint": "Found 2 registered EU trademarks. Both are active. Nice classes: 9 (electronics), 12 (vehicles), 37 (repair services)."
}

Next Steps

Check nice_classes to understand trademark coverage. Use trademark data alongside /profile for IP due diligence.

Bulk Sanctions Check

Screen up to 20 companies against sanctions lists in a single request. Ideal for batch onboarding or periodic re-screening.

POST /v1/company/bulk-check

Request Body

Name	Type	Required	Description
companies	array	required	Array of company names (max 20)

          Request
        
POST https://companylensapi.vercel.app/v1/company/bulk-check
Authorization: Bearer cl_live_...
Content-Type: application/json

{
  "companies": [
    "Tesla, Inc.",
    "SpaceX",
    "Huawei Technologies"
  ]
}

          Response
        
{
  "results": [
    {
      "company": "Tesla, Inc.",
      "status": "clear",
      "matches": []
    },
    {
      "company": "SpaceX",
      "status": "clear",
      "matches": []
    },
    {
      "company": "Huawei Technologies",
      "status": "matched",
      "matches": [
        {
          "score": 0.98,
          "dataset": "us_bis_entity_list",
          "entity_name": "HUAWEI TECHNOLOGIES CO., LTD."
        }
      ]
    }
  ],
  "screened_at": "2026-03-26T12:00:00Z",
  "total": 3,
  "flagged": 1,
  "agent_hint": "Screened 3 companies. 1 flagged (Huawei Technologies). Route flagged entities to compliance review."
}

Next Steps

Filter results by status: "matched" to identify flagged entities. For detailed screening, use the individual /sanctions endpoint per company.

Reference

Error Handling

All errors follow a consistent JSON format with an agent_hint field that provides actionable guidance for AI agents.

          Error Response Format
        
{
  "error": "not_found",
  "message": "Company with ID 'us_sec_0000000' not found.",
  "agent_hint": "The company ID is invalid. Use /v1/company/search?q=... to find valid IDs first."
}

Error Codes

HTTP Status	Error Code	Description	Agent Hint
400	bad_request	Missing or invalid parameters	Check required parameters and format
401	unauthorized	Missing or invalid API key	Include Authorization: Bearer cl_... header
403	forbidden	API key revoked or disabled	Generate a new key via POST /v1/keys
404	not_found	Company ID does not exist	Use /v1/company/search to find valid IDs
429	rate_limited	Daily or burst limit exceeded	Wait for Retry-After seconds, then retry
500	internal_error	Server error	Retry after a brief delay. If persistent, contact support
502	upstream_error	Data source temporarily unavailable	External source down. Retry in 30s or try a different endpoint

For AI agents: Always read the agent_hint field in error responses. It provides specific next-step instructions tailored for automated workflows.

MCP Server

CompanyLens is available as an MCP (Model Context Protocol) server, allowing Claude, GPT, and other LLM agents to call CompanyLens tools natively.

Installation

          npx (no install required)
        
npx companylens-mcp

          Claude Desktop config (~/.claude/mcp.json)
        
{
  "mcpServers": {
    "companylens": {
      "command": "npx",
      "args": ["companylens-mcp"],
      "env": {
        "COMPANYLENS_API_KEY": "cl_live_..."
      }
    }
  }
}

Available Tools (7)

companylens_search

Search companies by name across US and UK registries. Maps to GET /v1/company/search.

companylens_profile

Get company profile with officers, filings, and financial data. Maps to GET /v1/company/{id}/profile.

companylens_sanctions

Screen company against global sanctions lists. Maps to GET /v1/company/{id}/sanctions.

companylens_contracts

Retrieve US awards, SAM.gov opportunities, and EU tenders. Maps to GET /v1/company/{id}/contracts.

companylens_court_cases

Search federal court cases via CourtListener. Maps to GET /v1/company/{id}/court-cases.

companylens_regulatory

Get EPA violations and FDA recalls. Maps to GET /v1/company/{id}/regulatory.

companylens_risk_score

Compute aggregated 0-100 risk score with factor breakdown. Maps to GET /v1/company/{id}/risk-score.

Typical Agent Workflow

A recommended sequence for AI agents performing company due diligence.

1

Search for the company

Call GET /v1/company/search?q=CompanyName to find the company and get its ID.

2

Fetch the company profile

Call GET /v1/company/{id}/profile to get officers, addresses, filings, and industry classification.

3

Screen for sanctions

Call GET /v1/company/{id}/sanctions. If status is "matched", stop and flag for compliance. If "clear", continue.

4

Check government contracts

Call GET /v1/company/{id}/contracts to see US awards, SAM.gov opportunities, and EU tenders.

5

Review court cases

Call GET /v1/company/{id}/court-cases to find federal litigation history.

6

Check regulatory actions

Call GET /v1/company/{id}/regulatory for EPA violations and FDA recalls.

7

Get aggregated risk score

Call GET /v1/company/{id}/risk-score for a 0-100 score with factor breakdown. Present this as the summary to the user.

          Complete Workflow Example
        
# Step 1: Search
GET /v1/company/search?q=Tesla&jurisdiction=us

# Step 2: Profile (using id from search)
GET /v1/company/us_sec_1318605/profile

# Steps 3-6: Parallel risk checks
GET /v1/company/us_sec_1318605/sanctions
GET /v1/company/us_sec_1318605/contracts
GET /v1/company/us_sec_1318605/court-cases
GET /v1/company/us_sec_1318605/regulatory

# Step 7: Aggregated score
GET /v1/company/us_sec_1318605/risk-score

Optimization tip: Steps 3-6 (sanctions, contracts, court-cases, regulatory) can be called in parallel since they are independent. The risk-score endpoint aggregates all of them, so you can also call it alone for a quick summary.