Clocsy API

See what's happening to any company — and why.

Clocsy is building the place developers and businesses come to check a company the way they'd check a stock ticker: who they are, what changed recently, and the signal behind it — funding, hiring surges, leadership moves, expansion, pricing-page edits. Four real, key-authenticated REST endpoints (/api/v1), documented exactly as shipped — nothing planned, nothing aspirational.

See Company Signals Get an API key

Not a static directory. A live feed on every company.

Most company APIs give you a firmographic snapshot — name, size, address — and stop there. Clocsy's news/signal engine keeps watching after that: it crawls company sites, filings, hiring pages, and news sources to build a running record of what's actually changing at a company right now, and surfaces it as structured, queryable signals your product can act on.

Hiring surges and headcount shifts
Funding rounds and M&A activity
Leadership and org changes
Market expansion and new regions
Pricing-page and site changes
Procurement and buyer intent

This is genuinely new, metered infrastructure — see the Company Signals endpoint below for exactly what's returned and how it's billed.

Authentication

Every request carries a standard REST bearer token — not a custom header. Send your API key as:

Header
Authorization: Bearer csy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Keys are prefixed csy_live_ and shown to you exactly once, at creation — Clocsy stores only a salted hash, never the raw key.
  • A missing, invalid, expired, or revoked key returns 401 with code: "API_KEY_REQUIRED".
  • A valid key still only unlocks the endpoints that key's project plan covers — see each endpoint's access gate below.
  • Every key belongs to one project and authenticates as that project — there is no separate "user" identity on this API.

Endpoints

Three routes are read-only GET requests, rate-limited to 60 requests/minute per API key. Company Signals and its batch sibling are additionally credit-metered per company resolved — see the pricing table and note below.

Find Companies — search

Request
GET /api/v1/companies/search?q=fintech%20saas&page=1&pageSize=25
Requires active Sales Engine access on the key's project60 req/min

Query parameters

qstringFree-text search, trimmed, capped at 200 characters.
pageintegerDefault 1, max 2000.
pageSizeintegerDefault 25, max 50.

Response — 200

{
  "success": true,
  "companies": [
    {
      "id": "string",            // stable result handle, not a DB id
      "name": "string",
      "domain": "string | null",
      "website": "string | null",
      "city": "string | null",
      "country": "string | null",
      "location": "string | null",     // "City, Region, Country"
      "industry": "string | null",
      "employeeCount": "number | null"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 0,
  "hasMore": false
}

This reuses the exact internal client the in-app Find Companies tool already talks to — results are the same company graph, not a separate dataset.

Company Signals — what's happening, and why

Paid · credit-metered

Look up a single company by domain or name and get back its tracked intent/signal history — hiring, funding, expansion, leadership changes, site changes, and more — sourced by Clocsy's own news/signal crawler. This is the one endpoint on this page that isn't bundled free into plan access: every successful call costs credits from the key's project balance.

This endpoint spends real credit. The moment an authenticated request succeeds, 1 credit is debited from your project's balance automatically — there's no confirmation step, and looking up the same company twice is billed twice. Every response includes creditsCharged and creditsRemaining so you can track spend in real time; a 402 API_CREDITS_REQUIRED means the balance ran out before the call.

That $0.05/credit debit is the pay-as-you-go rate — the price you pay by default, no commitment. Top up the same wallet with a credit pack instead and every future lookup still costs exactly 1 credit, it just costs less per dollar to get there:

TierPriceCreditsEffective rate
Pay-as-you-go—No pack$0.05 / credit, list rate
Starter$20500 credits$0.04 / credit — 20% off list
Growth$351,000 credits$0.035 / credit — 30% off list
Scale$1505,000 credits$0.03 / credit — 40% off list, matches Apollo's own best rate
EnterpriseContact sales25,000+ creditsCustom pricing

Packs are bought from the API Pricing tab in your dashboard's Account area — the same wallet, the same checkout, just tagged so the right number of bonus credits land in your balance.

Request
GET /api/v1/companies/signals?domain=example.com
Requires active Sales Engine access on the key's project60 req/min 1 credit / request, debited automatically on success

Query parameters

domainstringCompany domain, e.g. example.com. At least one of domain or q is required.
qstringCompany name to search for if domain isn't known. Capped at 200 characters.

Response — 200

{
  "success": true,
  "company": {
    "id": "string",
    "name": "string",
    "domain": "string | null",
    "website": "string | null",
    "city": "string | null",
    "country": "string | null",
    "location": "string | null",
    "industry": "string | null",
    "employeeCount": "number | null"
  },
  "signalsTracked": true,      // false = company exists but Clocsy hasn't crawled signals for it yet
  "signalCount": 4,
  "signals": [
    {
      "id": "string",
      "source": "string",        // e.g. "rss" | "sec_edgar" | "site_change" | "google_news"
      "signalType": "string",    // e.g. "funding" | "hiring" | "leadership_change" | "expansion"
      "title": "string | null",
      "summary": "string",
      "url": "string | null",
      "strength": 0,             // 0-100 relevance/confidence score
      "occurredAt": "string | null"
    }
  ],
  "researchStatus": "string | null",  // latest research job status for this company, if any
  "creditsCharged": 1,
  "creditsRemaining": 249
}

Signal coverage grows continuously as Clocsy's crawler discovers and tracks more companies — a company that returns signalsTracked: false today may have signals tomorrow. Only genuinely unmatched domains/names return a 404.

Company Signals — batch lookup

Paid · credit-metered

Resolve up to 100 companies — by domain, name, or both — in a single authenticated call. Every item in the batch runs through the exact same lookup as the endpoint above; this is a batching wrapper around it, not a separate dataset or a different result shape.

You're billed only for companies actually resolved — never for the HTTP request itself, and never for a domain that comes back not-found. Capped at 100 companies per call. If your balance runs out partway through, Clocsy resolves as many as it can afford and marks the rest skipped_insufficient_credit — you always get one result per item you sent, the batch is never thrown away for one exhausted balance.

Request
POST /api/v1/companies/signals/batch
Body
{
  "companies": [
    { "domain": "example.com" },
    { "name": "Acme Inc" }
  ]
}
Requires active Sales Engine access on the key's projectLower rate limit than single lookups, scaled to batch cost 1 credit per resolved company · max 100/request

Body parameters

companiesarray1-100 items. Required.
companies[].domainstringCompany domain, e.g. example.com. At least one of domain or name is required per item.
companies[].namestringCompany name to search for if domain isn't known.

Response — 200

{
  "success": true,
  "resolved": 47,
  "notFound": 3,
  "skipped": 0,
  "creditsCharged": 47,
  "creditsRemaining": 202,
  "results": [
    {
      "index": 0,
      "domain": "example.com",
      "q": null,
      "status": "resolved",   // "resolved" | "not_found" | "skipped_insufficient_credit" | "invalid"
      "company": { "...": "same shape as the single-lookup endpoint's company object" },
      "signalsTracked": true,
      "signalCount": 4,
      "signals": ["..."],
      "researchStatus": "string | null"
    },
    {
      "index": 1,
      "domain": "doesnotexist.example",
      "q": null,
      "status": "not_found",
      "error": "No company matched this domain or name."
    }
  ]
}

results always has exactly one entry per item you sent, in the same order you sent it — match by index, not by status. creditsCharged always equals the count of resolved items — not-founds and skipped items never appear in it.

Find Talent — candidate search

Request
GET /api/v1/talent/candidates/search?page=1&pageSize=25
Requires an active Find Talent subscription on the key's project60 req/min

Query parameters

pageintegerDefault 1, max 2000.
pageSizeintegerDefault 25, max 100.

Response — 200

{
  "success": true,
  "candidates": [
    {
      "id": "string",
      "allocationId": "string",
      "searchId": "string",
      "searchTitle": "string | null",
      "prospectId": "string | null",
      "displayName": "string | null",
      "title": "string | null",
      "company": "string | null",
      "location": "string | null",
      "hasEmail": true,           // real email address is never returned by this endpoint
      "pipelineStatus": "string",
      "relevanceScore": "number | null",
      "relevanceMethod": "string | null"
    }
  ],
  "page": 1,
  "pageSize": 25,
  "total": 0,
  "hasMore": false
}

This reads candidates your project has already sourced through Find Talent — it does not trigger a new, live sourcing run, and it never exposes a candidate's actual email address (only whether one is on file).

Errors

Every error response shares one shape:

{ "success": false, "error": "human-readable message", "code": "MACHINE_READABLE_CODE" }
StatusCodeMeaning
401API_KEY_REQUIREDNo key, or the key is invalid, expired, or revoked.
403API_SALES_ACCESS_REQUIREDCompanies search / Company Signals: the key's project doesn't have active Sales Engine access.
403API_TALENT_ACCESS_REQUIREDTalent search: the key's project doesn't have an active Find Talent subscription.
400API_QUERY_REQUIREDCompany Signals: neither domain nor q was provided.
402API_CREDITS_REQUIREDCompany Signals: the key's project doesn't have enough credit balance for this request.
404API_COMPANY_NOT_FOUNDCompany Signals: no company matched the given domain or name.
400API_BATCH_EMPTYBatch lookup: companies was missing or an empty array.
400API_BATCH_TOO_LARGEBatch lookup: companies had more than 100 items.
429SALES_RATE_LIMITEDToo many requests in the current window for this key. Retry-After header is set.
500API_REQUEST_FAILEDUnexpected server-side failure processing the request.

Get an API key

API keys are created, revealed once, and revoked from inside your Clocsy dashboard — there's no separate developer portal. Once you're signed in:

  1. 1.Open your dashboard — it lands on your project automatically.
  2. 2.Go to Account, then the API Keys tab.
  3. 3.Create a key, copy it immediately — it's shown only once — and use it as your bearer token above.
Open Dashboard Sign in first