API reference Pro

Read-only REST API

Programmatic access to workplace signal scores for 1,600+ companies.

Beta. This API is provided as-is for developers and researchers. Endpoints, field names, and rate limits may change without notice. Pin the response fields you depend on and monitor the methodology page for scoring changes.

Overview

The Pulvian API gives you programmatic access to workplace signal scores for 1,600+ companies. Use it to build internal dashboards, enrich your portfolio monitoring tools, or power due-diligence workflows.

All endpoints are read-only and return JSON. The base URL for all requests is:

Base URL

https://api.pulvian.com

Responses use standard HTTP status codes. Errors return a JSON object with a detail field explaining the problem.

Authentication

All API endpoints require authentication. Pass your API key in the X-API-Key header on every request. Keys are issued to Pro and Enterprise subscribers.

Example request

curl "https://api.pulvian.com/api/v1/companies/stripe" \
  -H "X-API-Key: pk_live_your_key_here"

Pro

1,000/ day

Enterprise

Unlimited

Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. A 429 means you've exhausted the daily quota — it resets at 00:00 UTC.

Rate limits

Rate limits are enforced per API key. Exceeding the limit returns 429 Too Many Requests. Scores update at most once per day — cache responses on your side to stay well within limits.

Tier	Requests / day	History	Export
Pro	50,000	180 days	CSV
Enterprise	500,000	Full	CSV + JSON

Endpoints

GET/api/v1/companies/{slug}Full company profile and latest signal scores

Returns the company profile and its latest signal scores. Replaces {slug} with the company identifier (e.g. stripe).

Example request

curl "https://api.pulvian.com/api/v1/companies/stripe" \
  -H "X-API-Key: pk_live_your_key_here"

Example response (abbreviated)

{
  "company": {
    "name": "Stripe",
    "slug": "stripe",
    "industry": "Fintech",
    "country": "US",
    "website": "https://stripe.com"
  },
  "latest_snapshot": {
    "stress_score": 42.1,
    "risk_score": 31.8,
    "confidence_score": 87.5,
    "stress_level": "medium",
    "snapshot_date": "2026-05-24"
  },
  "coverage": "strong"
}

Key response fields

company.name	string	Display name of the company.
latest_snapshot.stress_score	float 0–100	Aggregate stress signal. Higher = more stress indicators.
latest_snapshot.risk_score	float 0–100	Aggregate risk signal. Higher = more risk flags.
latest_snapshot.confidence_score	float 0–100	Data confidence. Lower = fewer sources, treat with caution.
coverage	strong \| moderate \| limited	Qualitative coverage band for this company.

GET/api/v1/companiesList companies with optional filters, paginated

Key info & usage

Returns metadata for the currently authenticated API key — tier, daily usage, and remaining requests. Use this as a health-check to confirm your key works and to monitor consumption without making a data request.

GET/api/v1/meGet current API key info

Example request

curl "https://api.pulvian.com/api/v1/me" \
  -H "X-API-Key: pk_live_your_key_here"

Example response

{
  "key_prefix": "pk_live_",
  "tier": "pro",
  "customer_email": "you@example.com",
  "organization_name": null,
  "daily_limit": 1000,
  "requests_today": 47,
  "requests_remaining": 953,
  "last_reset_date": "2026-06-04",
  "last_used_at": "2026-06-04T14:23:11Z",
  "created_at": "2026-05-01T09:00:00Z",
  "is_active": true
}

Response fields

key_prefix	string	First 8 characters of your key — confirms which key is in use.
tier	string	Key tier: free \| pro \| enterprise.
customer_email	string	Email the key was issued to.
daily_limit	integer	Maximum requests allowed per day.
requests_today	integer	Requests made today (resets at UTC midnight).
requests_remaining	integer	Requests remaining today.
last_reset_date	string	Date the daily counter last reset (YYYY-MM-DD).
last_used_at	string	UTC timestamp of the most recent request.
created_at	string	UTC timestamp when the key was created.

CSV export

Download a full snapshot of all tracked companies as a CSV file. Requires a valid X-API-Key header (Pro or Enterprise). The export includes company metadata and the latest stress, risk, and confidence scores for every scored company.

GET/api/v1/pro/companies/exportDownload all companies as CSV

Returns a text/csv file attachment. The response includes a Content-Disposition header with a timestamped filename (e.g. pulvian-companies-2026-06-01.csv).

Example request

curl "https://api.pulvian.com/api/v1/pro/companies/export" \
  -H "X-API-Key: pk_live_your_key_here" \
  --output pulvian-companies.csv

Query parameters

limit	integer	Maximum number of companies to include. Default: 5000. Max: 10000.
industry	string	Filter by industry (case-insensitive exact match).
country	string	Filter by country (case-insensitive exact match).
stress_level	string	Filter by stress level: low \| medium \| high.

CSV columns

slug	string	Unique company identifier.
name	string	Company display name.
industry	string

Webhooks

Register HTTPS endpoints to receive company.score_changed events in real time. Pulvian posts a signed JSON payload to your URL whenever a company's stress or risk score is updated after a rescore run.

Every delivery includes an X-Pulvian-Signature-256 header so you can verify the payload origin using the secret returned at registration:

Signature verification (Python)

import hashlib, hmac

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Event payload

{
  "event": "company.score_changed",
  "timestamp": "2026-06-03T08:14:32.441Z",
  "data": {
    "company_slug": "stripe",
    "company_name": "Stripe",
    "stress_score": 45.2,
    "risk_score": 33.1,
    "confidence_score": 87.5,
    "stress_delta": 3.1,
    "risk_delta": 1.3
  }
}

POST/api/v1/webhooksRegister a new webhook endpoint

Creates a new webhook subscription. The secret field in the response is shown once — save it immediately. Up to 10 active webhooks are allowed per API key.

Example request

curl -X POST "https://api.pulvian.com/api/v1/webhooks" \
  -H "X-API-Key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/pulvian-events", "events": ["company.score_changed"]}'

Example response

{
  "id": "3f2a1b4c-...",
  "url": "https://your-server.com/pulvian-events",
  "secret": "a3f9c2e1...",
  "events": ["company.score_changed"],
  "is_active": true,
  "created_at": "2026-06-03T08:00:00Z"
}

Error format

All errors return JSON with a detail field:

{
  "detail": "Company not found."
}

400		Bad request — malformed query parameter or body.
401		Missing or invalid API key.
404		Resource not found.
422		Validation error — missing required field or invalid value.
429		Rate limit exceeded. Back off and retry after the window resets.

Lists companies with optional filters. Returns paginated results with latest scores.

Example request

curl "https://api.pulvian.com/api/v1/companies?industry=Fintech&limit=20" \
  -H "X-API-Key: pk_live_your_key_here"

Query parameters

industry	string	Filter by industry (e.g. "Fintech", "SaaS"). Case-insensitive.
country	string	ISO 3166-1 alpha-2 country code (e.g. US, GB, DE).
stress_level	low \| medium \| high	Filter by stress level band.
sort	string	Sort order: name_asc (default), stress_desc, risk_desc, recently_updated, most_changed.
limit	integer	Results per page (1–100, default 20).
offset	integer	Pagination offset (default 0).

GET/api/v1/companies/{slug}/trendScore history time series, ordered by date ascending

Returns score history as a time series, ordered by date ascending. History depth depends on your plan tier (see Rate Limits above).

Example request

curl "https://api.pulvian.com/api/v1/companies/stripe/trend?limit=90" \
  -H "X-API-Key: pk_live_your_key_here"

Example response (abbreviated)

{
  "slug": "stripe",
  "snapshots": [
    {
      "snapshot_date": "2026-03-01",
      "stress_score": 38.4,
      "risk_score": 29.1,
      "confidence_score": 85.2
    }
  ],
  "total": 90
}

Query parameters

limit

integer

Cap the number of returned points (most-recent N, max 1,000). Default 30.

GET/api/v1/searchSearch companies by name or slug

Full-text search across company names and slugs. Useful for autocomplete or resolving a company name to its canonical slug.

Example request

curl "https://api.pulvian.com/api/v1/search?q=stripe&limit=5" \
  -H "X-API-Key: pk_live_your_key_here"

Query parameters

q	string	Search term — company name or slug prefix. Required.
limit	integer	Max results to return (1–50, default 10).

GET/api/v1/companies/{slug}/similarCompanies similar to the given company

Returns companies in the same industry with comparable size and score profile. Useful for benchmarking or building competitor comparisons.

Example request

curl "https://api.pulvian.com/api/v1/companies/stripe/similar?limit=4" \
  -H "X-API-Key: pk_live_your_key_here"

Query parameters

limit

integer

Number of similar companies to return (1–10, default 4).

GET/api/v1/companies/industry-statsAggregate stress and risk scores grouped by industry

Returns average stress and risk scores for every tracked industry. Industries are ordered by average stress descending (highest-stress first). Useful for sector-level screening and benchmarking individual companies against their industry average.

Example request

curl "https://api.pulvian.com/api/v1/companies/industry-stats" \
  -H "X-API-Key: pk_live_your_key_here"

Example response (abbreviated)

[
  {
    "industry": "Fintech",
    "company_count": 142,
    "scored_count": 138,
    "avg_stress": 54.2,
    "avg_risk": 41.7
  },
  ...
]

GET/api/v1/companies/moversCompanies with the largest recent stress-score change

Returns companies whose stress score changed the most between their two most recent scored snapshots. Sorted by absolute change descending. Only companies with at least two scored snapshots (confidence ≥ 15) appear. Use this to surface early warning signals and rapid sentiment shifts across the tracked universe.

Example request

curl "https://api.pulvian.com/api/v1/companies/movers?limit=10" \
  -H "X-API-Key: pk_live_your_key_here"

Example response (abbreviated)

{
  "items": [
    {
      "company": { "name": "Acme Corp", "slug": "acme-corp", "industry": "SaaS" },
      "latest_snapshot": { "stress_score": 74.3, "risk_score": 61.0 },
      "stress_change": 18.5,
      "trend_direction": "up"
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 0
}

Query parameters

limit	integer	Number of movers to return (1–50, default 10).
industry	string	Filter by industry (optional).
country	string	Filter by country (optional).

Key response fields

stress_change	float	Delta since previous snapshot. Positive = stress increased, negative = decreased.
trend_direction	up \| down \| stable	Direction of the stress change.

GET/api/v1/companies/top-stressCompanies ranked by stress score — highest first

Returns companies sorted by current stress score, highest first. Useful for building risk dashboards, screening watchlists, or identifying companies under the most workplace pressure. Supports industry and country filters.

Example request

curl "https://api.pulvian.com/api/v1/companies/top-stress?limit=20&industry=Fintech" \
  -H "X-API-Key: pk_live_your_key_here"

Query parameters

limit	integer	Results per page (1–100, default 20).
offset	integer	Pagination offset (default 0).
industry	string	Filter by industry (optional).
country	string	Filter by country (optional).

GET/api/v1/companies/top-riskCompanies ranked by risk score — highest first

Returns companies sorted by current risk score, highest first. Risk score reflects structural and financial indicators, whereas stress score reflects employee sentiment. Use this endpoint to surface companies with elevated organisational or financial risk profiles.

Example request

curl "https://api.pulvian.com/api/v1/companies/top-risk?limit=20&country=USA" \
  -H "X-API-Key: pk_live_your_key_here"

Query parameters

limit	integer	Results per page (1–100, default 20).
offset	integer	Pagination offset (default 0).
industry	string	Filter by industry (optional).
country	string	Filter by country (optional).

GET/api/v1/companies/statsPlatform-wide coverage and score distribution statistics

Returns a snapshot of the tracked universe: total companies, how many have been scored, average stress and risk across all companies, distribution by stress level (high / medium / low), total signal count, and the date of the most recent scoring run. Useful for calibrating thresholds and understanding data coverage before querying individual companies.

Example request

curl "https://api.pulvian.com/api/v1/companies/stats" \
  -H "X-API-Key: pk_live_your_key_here"

Example response

{
  "total_companies": 1842,
  "scored_companies": 1614,
  "avg_stress": 47.3,
  "avg_risk": 38.9,
  "high_stress_count": 312,
  "medium_stress_count": 798,
  "low_stress_count": 504,
  "signal_count": 94217,
  "last_updated": "2026-06-03"
}

Response fields

total_companies	integer	All companies in the tracked universe.
scored_companies	integer	Companies with at least one scored snapshot.
avg_stress	float 0–100	Mean stress score across all scored companies.
avg_risk	float 0–100	Mean risk score across all scored companies.
high_stress_count	integer	Companies with stress ≥ 70.
medium_stress_count	integer	Companies with 40 ≤ stress < 70.
low_stress_count	integer	Companies with stress < 40.
signal_count	integer	Total workplace signals ingested across all companies.
last_updated	date	Date of the most recent scoring run.

POST/api/v1/companies/bulkFetch up to 50 companies in a single request

Resolves a list of company slugs in one round-trip. Ideal for monitoring a fixed watchlist without repeated single-company calls. Results preserve the input slug order. Slugs with no match are returned in not_found — no error is raised.

Example request

curl -X POST "https://api.pulvian.com/api/v1/companies/bulk" \
  -H "X-API-Key: pk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"slugs": ["stripe", "linear", "notion"]}'

Example response (abbreviated)

{
  "items": [
    {
      "company": { "name": "Stripe", "slug": "stripe", "industry": "Fintech" },
      "latest_snapshot": {
        "stress_score": 42.1,
        "risk_score": 31.8,
        "stress_level": "medium",
        "snapshot_date": "2026-06-01"
      },
      "stress_change": -3.2,
      "trend_direction": "down"
    }
  ],
  "requested": 3,
  "found": 3,
  "not_found": []
}

Request body fields

slugs*

string[]

Array of company slugs to look up. Max 50 per request.

Response fields

items	array	Company cards in the same order as the input slugs.
requested	integer	Number of slugs submitted.
found	integer	Number of slugs that matched a tracked company.
not_found	string[]	Slugs from the request that did not match any company.

GET/api/v1/webhooksList all webhooks for the calling API key

Returns all webhook registrations (active and inactive) for your API key, ordered by creation date descending. Check last_status_code and failure_count to monitor delivery health.

Example request

curl "https://api.pulvian.com/api/v1/webhooks" \
  -H "X-API-Key: pk_live_your_key_here"

Example response

{
  "webhooks": [
    {
      "id": "3f2a1b4c-...",
      "url": "https://your-server.com/pulvian-events",
      "events": ["company.score_changed"],
      "is_active": true,
      "created_at": "2026-06-03T08:00:00Z",
      "last_triggered_at": "2026-06-03T09:15:00Z",
      "last_status_code": 200,
      "failure_count": 0
    }
  ],
  "total": 1
}

DELETE/api/v1/webhooks/{id}Deactivate a webhook — stops delivery immediately

Deactivates the webhook. Delivery stops immediately; the record is kept for audit purposes. To re-enable, register a new webhook.

Example request

curl -X DELETE "https://api.pulvian.com/api/v1/webhooks/3f2a1b4c-..." \
  -H "X-API-Key: pk_live_your_key_here"

Example response

{
  "id": "3f2a1b4c-...",
  "is_active": false,
  "deactivated_at": "2026-06-03T10:00:00Z"
}

POST/api/v1/webhooks/{id}/testSend a synthetic test event to verify your endpoint

Sends a synthetic company.score_changed event to your endpoint using a fake company (slug __test__). Use this to verify your receiver is reachable and your signature verification logic is correct before waiting for a real rescore event.

Example request

curl -X POST "https://api.pulvian.com/api/v1/webhooks/3f2a1b4c-.../test" \
  -H "X-API-Key: pk_live_your_key_here"

Example response

{
  "id": "3f2a1b4c-...",
  "url": "https://your-server.com/pulvian-events",
  "status_code": 200,
  "success": true,
  "message": "Test event delivered successfully."
}

API Reference | Pulvian

url*	string (https)	Your HTTPS endpoint that will receive POST requests.
events	string[]	Event types to subscribe to. Currently only "company.score_changed" is supported. Defaults to ["company.score_changed"].

Overview

Authentication

Rate limits

Endpoints

Key info & usage

CSV export

Webhooks

Error format

Terms and attribution