# Quick Leaves API

> B2B data enrichment API built from the public web: company details, customers, partners, vendors,
> competitors and people for a given company domain, each relationship with the public page that shows it.

Authentication: send `X-API-Key: gtm_live_…` (or `Authorization: Bearer gtm_live_…`).
Every metered response carries `X-Credits-Cost` (credits charged for this call) and `X-Credits-Remaining`.
Errors are RFC 9457 problem+json. You are never charged for errors, 202s, 404s or 503s, with one exception: `404 company_not_found` from `/company/details` costs 1 credit.
Responses use snake_case JSON. `domain` accepts a bare domain, a URL, or an email address.
A company's old domain (one it moved away from) answers with the company under its current domain, at the same price.

Freshness: company endpoints always answer from stored data at once (typically < 50 ms) and refresh data
older than 30 days in the background; `fresh=true` queues that refresh now. `cache=only` reads stored data,
also when stale, and never queues anything: a company not in the graph is a free `404` with code `not_in_graph`,
and `cache=only` together with `fresh=true` is `400 conflicting_parameters`. A company never seen before is
crawled while you wait (typically 5–20 s) and returns partial data; if that takes longer you get `202` with
`Retry-After` and nothing is charged. `X-Enrichment-Status` says what you got: `complete`, `partial` (some
fields are still being filled: industry, business model and similar companies may be missing), `refreshing`,
`refresh_deferred` (stored data; your organization already has 50 refreshes waiting, so none was queued and
`fresh=true` adds no credit) or `queued`.
Poll the free `/company/status` endpoint until it says `complete` instead of polling a paid endpoint.
Or add `callback_url=https://…` to details, customers or competitors: once the company is `complete` (or
`not_found`) we POST a Standard Webhooks message (`webhook-id`, `webhook-timestamp`, `webhook-signature`;
body `{"type":"company.enrichment.completed","timestamp":…,"data":{"domain":…,"status":…}}`) signed with the
secret from `/callbacks/secret`. Free; retried up to 6 times over about 9 hours; dropped after 24 h without
`complete`; no redirects followed; at most 100 pending per organization (more is a free `429 callback_limit`).
An organization may have at most 10 never-seen companies waiting for their first data (200 from
`/company/batch`, which wait behind all other work); another one is answered `429` with `Retry-After` (free).
Companies already in the graph, or already queued, never count. A domain whose crawl found no website
answers `404` for a day (1 credit on `/company/details`, free elsewhere), then is crawled again. Queued work is shared out between organizations in turn.
Trial organizations (made by a console sign-up, no payment yet) have lower limits until their first payment:
60 requests a minute per key, 3 never-seen companies waiting at once (3 from batches),
25 new never-seen companies a UTC day and 2 active keys. Over a limit the answer is the usual free `429`
(`rate_limited` or `queue_full`) and its `detail` names the trial limit. A sign-up with a verified work e-mail
gets 200 trial credits for 30 days, once per e-mail domain.

## Endpoints

- [Company details](https://api.quickleaves.com/api/v1/company/details?domain=stripe.com): firmographics, technographics (tech stack, email provider/gateway, email pattern), open roles by department, `tagline`, `cover_image_url` and `social_profiles` (LinkedIn, X, Facebook, Instagram, YouTube, GitHub, TikTok; as linked from the company's website), `company_type` (public, private, nonprofit, government, educational or unknown), `public_listing` (stock ticker and exchange), `sic_code` and `identifiers` (LEI, SEC CIK, ISIN, when known), and `executives` (up to 20 people with an executive role from the company's own pages, at no extra cost). 2 credits (+1 with `fresh=true`); 1 credit for `404 company_not_found` (no public web presence found, also on a repeat within the day); 0 for `404 not_in_graph` with `cache=only`.
- [Company customers](https://api.quickleaves.com/api/v1/company/customers?domain=stripe.com&max_results=20): customers with confidence scores and verbatim evidence quotes. Only customers with a verified domain are returned; `include_unverified=true` adds guessed and rejected ones (see `domain_status`). `include=partners` (or `include=customers,partners`) adds `partners`: partner platforms from the company's own integration, partner and marketplace pages (investors are not offered). `fresh=true` queues a refresh. Up to 200 per page and list (`max_results`); pass `next_cursor` (customers) or `partners_next_cursor` (partners) back as `cursor` with that one list in `include` (null on the last page). 1 credit + 2 per row returned over all lists, per page.
- [Company vendors](https://api.quickleaves.com/api/v1/company/vendors?domain=openai.com&max_results=20): the reverse of customers: companies whose own customer pages or case studies name the company as a customer, with the vendor's evidence page and quote and its `card`. Rows only when the company's own domain is verified (`company_domain_status`); otherwise the list is empty and free, unless `include_unverified=true`. Answers from stored data only: never crawls, and an unknown company is a free `404 not_in_graph`. Up to 200 per page with `cursor` / `next_cursor`. 1 credit + 2 per vendor returned, per page.
- [Company people](https://api.quickleaves.com/api/v1/company/people?domain=linear.app&limit=25): people named on the company's own team, about and leadership pages, with the published `title`, `roles` (`ceo`, `cto`, `cfo`, `coo`, `cmo`, `cro`, `cpo`, `ciso`, `founder`, `co_founder`, `president`, `chair`, `other`), `seniority` (`c_suite`, `vp`, `director`, `manager`, `ic`) and the page where each was seen (`evidence.url`). Executives first, then by name. Investors, advisors and board members are left out, and only the people from the latest check of those pages are shown. Filters `seniority`, `role` and `title` (part of the title, no case). No e-mail: use the work email lookup. A never-seen company behaves as in details (`202` queued); `cache=only` and `fresh=true` as in details. Up to 100 per page (`limit`, default 25) with `cursor` / `next_cursor`. 1 credit + 1 per person returned; an empty list costs 1, or 0 while `partial`.
- [Company competitors](https://api.quickleaves.com/api/v1/company/competitors?domain=stripe.com&limit=10): evidenced competitors first, then similar companies in the same market that are not confirmed competitors (`basis`: `evidenced` | `similar`). Each row has a `reason` (`compare_page`, `compare_page_text`, `similar_profile`); a similar row's `confidence` is how often such rows are real competitors, with its `similarity` and `match_score` beside it. `fresh=true` queues a refresh at no extra cost. 3 credits; 0 for an empty list while `partial`.
- [Company batch](https://api.quickleaves.com/api/v1/company/batch): POST `{"domains":["stripe.com","linear.app"],"cache":"only"}` (1–50 entries; `cache` optional). One result per input with `status` `found` (with `data`), `queued`, `queue_full` (200 never-seen companies from batches already waiting), `not_found` (with `cache=only`, or when the last crawl found no website) or `invalid` (with `error.code`). Never crawls while you wait. 2 credits per distinct found domain; the balance must cover 2 per distinct valid domain first. Own rate limit: 30 batches per minute per key.
- [Company search](https://api.quickleaves.com/api/v1/company/search?q=tools%20to%20chase%20unpaid%20invoices&max_results=10): enriched companies ranked by the meaning of a plain-words query (`q`, 3–200 characters; `max_results` 1–50, default 10). Each row has `domain`, `name`, `similarity`, `match_score` and the company `card`. Only strong matches are shown, so an answer can be shorter than `max_results` or empty. Never crawls. 1 credit per started 50 rows; an empty answer is free. Own rate limit: 60 searches per minute per key; `503 busy` with `Retry-After` when search is busy (free).
- [Company status](https://api.quickleaves.com/api/v1/company/status?domain=stripe.com): `complete`, `partial`, `refreshing`, `queued` or `not_found`, with `last_enriched_at` and `fields_completed_at`. Never starts a crawl. Free.
- [Public profile](https://api.quickleaves.com/api/v1/profile?url=https://example.com/team/jane-doe): the person described by an openly published page. Login-walled and people-search sites are rejected. 2 credits (+1 with `fresh=true`); 0 if no person is found.
- [Work email lookup](https://api.quickleaves.com/api/v1/work-email/lookup): POST `{"first_name":"Jane","last_name":"Doe","domain":"example.com"}`. Billed by verdict: `valid` 2, `likely_valid_pattern` / `catch_all_domain` 1, `unknown` / `invalid` 0. No e-mail is sent.
- [Callback secret](https://api.quickleaves.com/api/v1/callbacks/secret): the `whsec_` secret that signs your callbacks; POST `/api/v1/callbacks/secret/rotate` replaces it at once. Free.
- [Credit balance](https://api.quickleaves.com/api/v1/credits): the balance with `plan_credits` (spent first), `payg_credits` and their expiry dates. Free.
- [Usage](https://api.quickleaves.com/api/v1/usage?from=2026-10-01&to=2026-10-31): per UTC day and endpoint, requests by status class and the credits charged (at most 92 days; last 30 by default). Free.
- [Billing plans](https://api.quickleaves.com/api/v1/billing/plans): free.
- [Pricing](https://api.quickleaves.com/api/v1/pricing): plans and packs with list prices (minor units), the credits of every endpoint and the free trial with its limits, as JSON. No key needed. Free.
- [Checkout](https://api.quickleaves.com/api/v1/billing/checkout): POST `{"plan":"pack_10k"}` → hosted checkout URL. One subscription per workspace: a second one is `409 subscription_exists` (change the plan in the console). Free.

People data: only names and titles that the company or the person published openly; no private profiles, no
people-search sites, no guessed e-mail addresses in lists. Removal: e-mail support@quickleaves.com with the page URL, or
the full name and the company domain. The person is deleted and kept out of later answers, including
`/profile`.

Every customer, partner, vendor and competitor row carries a `card` (description, industry, logo URL, HQ country, employee range,
`enriched`, `tagline`, `linkedin`, `x`), so a list needs no second call. `enriched=false` means the counterparty is known only from another
company's pages, and its card fields are empty. Company details list every known `websites` entry, primary first.

## MCP

- [MCP server](https://api.quickleaves.com/mcp): stateless Streamable HTTP, same key (`X-API-Key` or `Authorization: Bearer`), same prices, rate limit and error codes as REST. Tools: `company_details`, `company_customers`, `company_competitors`, `company_status`, `company_batch`, `company_search`, `company_vendors`, `company_people`, `profile_lookup`, `work_email_lookup`, `credits_balance`, `usage`. Each result is JSON with `data`, `credits_charged`, `credits_remaining` and `trace_id`; an error result has `code`. `GET /mcp/health` is free and needs no key.

## Docs

- [Full reference: prices, MCP tools, every endpoint with an example answer](https://api.quickleaves.com/llms-full.txt)
- [Agent skill (SKILL.md; its version changes with its content)](https://api.quickleaves.com/skills/quickleaves/SKILL.md)
- [OpenAPI document](https://api.quickleaves.com/openapi/v1.json)
- [Interactive reference](https://api.quickleaves.com/docs)

## Status codes

- 400 invalid input · 401 missing/invalid key · 402 insufficient credits · 404 not found (free, except `company_not_found` from `/company/details`: 1 credit) · 202 queued for enrichment (free; retry after `Retry-After`) · 429 rate limited or too many new companies queued (free; honour `Retry-After`) · 503 at capacity (free; honour `Retry-After`)

## Error codes and headers

Every error body has a stable `code` (schema `ErrorCode` in the OpenAPI document) and a `trace_id`. Branch on `code`, not on `title`.
Codes: `invalid_request`, `invalid_domain`, `invalid_url`, `conflicting_parameters`, `batch_too_large`, `invalid_api_key`, `invalid_signature`, `insufficient_credits`, `organization_suspended`, `not_found`, `company_not_found`, `profile_not_found`, `not_in_graph`, `payload_too_large`, `rate_limited`, `queue_full`, `callback_limit`, `callbacks_disabled`, `subscription_exists`, `internal_error`, `upstream_error`, `busy`. A `402 insufficient_credits` body also has `required_credits`. `403 organization_suspended` means the organization's API access is suspended (for example during a payment dispute); contact support@quickleaves.com.

Every authenticated response carries `X-RateLimit-Limit` (requests per minute for your key), `X-RateLimit-Remaining`
(requests left in the key's bucket now) and `X-RateLimit-Reset` (seconds until the bucket is full again), plus the credit headers.
Company answers (200) carry `X-Data-Age-Days` (whole days since the data was last collected) and `Last-Modified`.