API Documentation

Programmatic access to CEO performance metrics and company data

Subscribe — $99/month Unlimited API calls • Cancel anytime

Base URL

https://api.ceorater.com

Quick Navigation

Getting Started Authentication Get API Metadata List Companies Get Company by Ticker Search Companies Coverage Health Check Data Formats Field Reference Code Examples Error Responses OpenAPI Spec ↗

Getting Started

The CEORater API provides programmatic access to CEO performance metrics, compensation data, and proprietary scores for public company executives. Follow the steps below to subscribe and get your API key.

Subscribe Now

Pricing: $99/month — unlimited API calls. Cancel anytime.

1Subscribe & Complete Payment

Click the Subscribe button above. You'll be prompted to create an account (or log in) and complete payment via our secure checkout powered by Paddle.

2Access the Developer Portal

After payment, you'll be automatically redirected to the CEORater API Developer Portal. If you're not redirected, go directly to:

https://ceorater-api-main-7ef1acf.zuplo.site

3Log In to the Portal

Click Login in the top-right corner of the Developer Portal. Sign in using the same email address you used during checkout.

4Verify Your Email (if prompted)

If this is your first time, you may need to verify your email address. Check your inbox for a verification email and click the link.

5Retrieve Your API Key

Once logged in, navigate to Settings → API Keys (or click your email in the top-right corner). Your API key will be displayed — it starts with zpka_. Click the eye icon to reveal it or the copy icon to copy it.

Keep your API key secure! Never expose it in client-side code or public repositories.

6Test Your API Key

Run this command in your terminal or command prompt (replace zpka_your_api_key_here with your actual key):

curl -H "Authorization: Bearer zpka_your_api_key_here" https://api.ceorater.com/v1/meta

You should see a JSON response with the total company count and last updated timestamp.

Minimal Python Example

import requests

BASE_URL = "https://api.ceorater.com"
API_KEY = "zpka_your_api_key_here"

resp = requests.get(
    f"{BASE_URL}/v1/company/AAPL",
    params={"format": "raw"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

Authentication

All API requests require authentication using your API key in the Authorization header with a Bearer token:

Authorization: Bearer zpka_your_api_key_here

Your API key starts with zpka_ and is available in the Developer Portal after subscribing. Keep it secure and never expose it in client-side code.

401 Unauthorized: Returned when the API key is missing, invalid, or expired.

Endpoints

GET `/v1/meta`

Returns information about the current dataset.

Response Example:

{
  "count": 519,
  "last_loaded": "2026-01-17T08:00:00.000Z"
}

GET `/v1/companies`

Retrieve a paginated list of companies with CEO ratings.

Query Parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Number of results (max: 2000)
`offset`	integer	0	Starting position for pagination
`format`	string	ui	Response format: `ui` or `raw`

Example Request:

GET /v1/companies?limit=20&offset=0&format=ui
Authorization: Bearer zpka_your_api_key_here

Response Example (UI format):

{
  "items": [
    {
      "Company Name": "Apple Inc.",
      "Ticker": "AAPL",
      "Sector": "Technology",
      "Industry": "Computer Manufacturing",
      "CEO Name": "Tim Cook",
      "Founder (Y/N)": "N",
      "CEORaterScore": 87,
      "AlphaScore": 94,
      "CompScore": "C",
      "TSR During Tenure": "2,223%",
      "Avg. Annual TSR": "155%",
      "TSR vs. SPY": "1,564%",
      "Avg Annual TSR vs. SPY": "109%",
      "Compensation ($ millions)": "$74.6M",
      "CEO Compensation Cost / 1% Avg TSR": "$0.482M",
      "Tenure (years)": "14.4 years"
    }
  ],
  "total": 519,
  "offset": 0,
  "limit": 20
}

GET `/v1/company/:ticker`

Retrieve detailed information for a specific company.

Path Parameters:

ticker (string) - Stock ticker symbol (case-insensitive)

Query Parameters:

format (string) - Response format: ui or raw (default: ui)

Example Request:

GET /v1/company/AAPL?format=raw
Authorization: Bearer zpka_your_api_key_here

Response Example (raw format):

{
  "companyName": "Apple Inc.",
  "ticker": "AAPL",
  "sector": "Technology",
  "industry": "Computer Manufacturing",
  "ceo": "Tim Cook",
  "founderCEO": false,
  "ceoraterScore": 87,
  "alphaScore": 93.5,
  "compScore": "C",
  "tsrMultiple": 22.23,
  "tenureYears": 14.4,
  "avgAnnualTsrRatio": 1.55,
  "compPer1PctTsrMM": 0.482,
  "tsrVsSpyRatio": 15.64,
  "avgAnnualVsSpyRatio": 1.09
}

GET `/v1/search`

Search companies by name, ticker, sector, industry, or CEO name.

Query Parameters:

Parameter	Type	Description
`q`	string	Search query (required)
`format`	string	Response format: `ui` or `raw` (default: ui)

Example Request:

GET /v1/search?q=technology&format=raw
Authorization: Bearer zpka_your_api_key_here

Response Example (raw format):

{
  "q": "technology",
  "count": 45,
  "items": [
    { "companyName": "Apple Inc.", "ticker": "AAPL", ... },
    { "companyName": "Microsoft Corp.", "ticker": "MSFT", ... }
  ]
}

GET `/status`

Health check endpoint (no authentication required).

Response Example:

{
  "state": "ok",
  "last_loaded": "2026-01-17T08:00:00.000Z",
  "total": 519
}

Coverage

CEORater covers 519 CEOs across major U.S. public companies, including all S&P 500 constituents and select mid-cap companies.

Use the /v1/meta endpoint to get the current company count and last data refresh timestamp.

Data Formats

Most endpoints support two response formats via the format query parameter:

`format=ui` (default)

Human-readable labels and formatted values:

• Percentages: "155%"
• Money: "$74.6M"
• Duration: "14.4 years"

`format=raw`

Machine-readable camelCase keys and numeric values:

• Ratios: 1.55
• Millions: 74.6
• Years: 14.4

Field Reference

UI Label	Raw Key	Description	Example (UI / Raw)
Company Name	`companyName`	Full company name	"Apple Inc."
Ticker	`ticker`	Stock symbol	"AAPL"
CEORaterScore	`ceoraterScore`	Proprietary overall CEO rating (0-100)	87
AlphaScore	`alphaScore`	Performance vs. market (0-100)	94
CompScore	`compScore`	Compensation efficiency grade (A-F)	"C"
TSR During Tenure	`tsrMultiple`	Total Shareholder Return	"2,223%" / 22.23
Avg. Annual TSR	`avgAnnualTsrRatio`	Average Annual TSR	"155%" / 1.55
TSR vs. SPY	`tsrVsSpyRatio`	TSR vs. SPY	"1,564%" / 15.64
Avg Annual TSR vs. SPY	`avgAnnualVsSpyRatio`	Avg Annual TSR vs. SPY	"109%" / 1.09
CEO Compensation ($ millions)	`compensationMM`	Total CEO Compensation	"$74.6M" / 74.6
CEO Compensation / 1% Avg TSR	`compPer1PctTsrMM`	CEO Compensation Cost per Percentage Point TSR	"$0.482M" / 0.482
Tenure (years)	`tenureYears`	CEO Tenure	"14.4 years" / 14.4

Code Examples

JavaScript / Fetch

const API_KEY = 'zpka_your_api_key_here';
const BASE_URL = 'https://api.ceorater.com';

async function searchCompanies(query) {
  const response = await fetch(
    `${BASE_URL}/v1/search?q=${encodeURIComponent(query)}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  return response.json();
}

// Usage
const results = await searchCompanies('apple');
console.log(results.items);

Swift / iOS

struct CEORaterAPI {
    let baseURL = "https://api.ceorater.com"
    let apiKey = "zpka_your_api_key_here"
    
    func getCompany(ticker: String) async throws -> Company {
        let url = URL(string: "\(baseURL)/v1/company/\(ticker)?format=raw")!
        var request = URLRequest(url: url)
        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
        
        let (data, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(Company.self, from: data)
    }
}

Python

import requests

API_KEY = 'zpka_your_api_key_here'
BASE_URL = 'https://api.ceorater.com'

def list_companies(limit=50, offset=0):
    response = requests.get(
        f'{BASE_URL}/v1/companies',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'limit': limit, 'offset': offset, 'format': 'raw'}
    )
    return response.json()

# Usage
data = list_companies(limit=20)
print(f"Total companies: {data['total']}")

cURL

# Search for companies
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/search?q=technology"

# Get specific company
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/company/AAPL?format=raw"

# Get metadata
curl -H "Authorization: Bearer zpka_your_api_key_here" "https://api.ceorater.com/v1/meta"

Error Responses

401 Unauthorized

{
  "error": "Missing or invalid API key"
}

404 Not Found

{
  "error": "Not found"
}

400 Bad Request

{
  "ok": false,
  "error": "Expected array at top level"
}

Additional Information

Data Refresh: Dataset updates daily (weekdays, after market close)
CORS: Enabled for all origins

Support

For API access, technical support, or feature requests, please contact:

Email: support@ceorater.com

Web: https://www.ceorater.com/support.html

Developer Portal: https://ceorater-api-main-7ef1acf.zuplo.site

Manage Subscription: Billing Portal (via Paddle)

API Documentation

Base URL

Quick Navigation

Getting Started

1Subscribe & Complete Payment

2Access the Developer Portal

3Log In to the Portal

4Verify Your Email (if prompted)

5Retrieve Your API Key

6Test Your API Key

Minimal Python Example

Authentication

Endpoints

GET /v1/meta

Response Example:

GET /v1/companies

Query Parameters:

Example Request:

Response Example (UI format):

GET /v1/company/:ticker

Path Parameters:

Query Parameters:

Example Request:

Response Example (raw format):

GET /v1/search

Query Parameters:

Example Request:

Response Example (raw format):

GET /status

Response Example:

Coverage

Data Formats

format=ui (default)

format=raw

Field Reference

Code Examples

JavaScript / Fetch

Swift / iOS

Python

cURL

Error Responses

401 Unauthorized

404 Not Found

400 Bad Request

Additional Information

Support

GET `/v1/meta`

GET `/v1/companies`

GET `/v1/company/:ticker`

GET `/v1/search`

GET `/status`

`format=ui` (default)

`format=raw`