{"openapi":"3.1.0","info":{"title":"Hunter API (Bowmark)","version":"e833508f87ff","description":"Work email addresses: the people at a given company and how to reach them, the address of one named person at one employer, whether an address will actually accept mail, the company or person behind a domain or an address, and company/people search by ideal-customer profile.\n\nEvery function Bowmark has for Hunter (hunter.io) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/hunter/findDomain":{"post":{"operationId":"findDomain","summary":"Turns a company NAME into the domain it sends mail from — the missing first step for every lead that arrives as \"Jane Smith, Acme Corp\" with no website.","description":"Turns a company NAME into the domain it sends mail from — the missing first step for every lead that arrives as \"Jane Smith, Acme Corp\" with no website. Returns up to `limit` candidates (default 5, max 10 — the site's own ceiling) in Hunter's ranking order, each with the company name, its email domain and how many addresses Hunter holds there. No key and no browser: one bootstrap GET for a visit token, then ~0.3s per lookup. READ `bestMatch` FIRST — it is the one domain worth acting on, and it is deliberately null when Hunter's best candidate is not the company you asked for, because this endpoint never admits it does not know a company: ask it for a firm that does not exist and it returns five confident rows matched on a substring. Legal suffixes are handled, so \"Basecamp LLC\" resolves to basecamp.com, while \"Tamarack Fabricating\" (Hunter knows only a \"Tamarack\") yields bestMatch null and leaves the judgement to you.\n\nCalls `bowmark.providers.hunter.findDomain`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<hunterDomainMatch>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","description":"TypeScript: `string`"},"limit":{"type":"number","description":"TypeScript: `number`"}},"required":["company"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/hunter/countEmails":{"post":{"operationId":"countEmails","summary":"How many work email addresses Hunter holds for one DOMAIN — the cheap look-before-you-search that says whether a company is worth spending a real lookup on.","description":"How many work email addresses Hunter holds for one DOMAIN — the cheap look-before-you-search that says whether a company is worth spending a real lookup on. Takes the domain, not the company name (pair it with `findDomain` when all you have is a name); `www.`, mixed case and a pasted URL are all handled. No key and no browser: the same one-bootstrap visit-token route `findDomain` uses, ~0.3s per lookup. READ `total` AS A NULLABLE — **null is not zero**. 0 means Hunter indexes the domain and holds no addresses there (basecamp.io really is 0); null means Hunter has no row for it at all, and the two call for opposite decisions. When `total` is null, `otherDomains` shows what the search did surface, which is usually how you learn the company is indexed under a country TLD or a marketing domain instead. This is the SAME number the paid `/v2/email-count` endpoint reports as `total` — cross-checked on stripe.com, which reads 2207 on both — but only the total: the personal/generic, department and seniority BREAKDOWN that endpoint also returns is not served on this route, and is declared separately as `getEmailBreakdown`.\n\nCalls `bowmark.providers.hunter.countEmails`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<hunterDomainEmailCount>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"TypeScript: `string`"}},"required":["domain"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}