Quickstart

From sign-up to your first company lookup in five minutes.

1. Create an account#

Sign up at https://app.happyfetch.net/register and verify your email. Verifying adds 200 credits to your workspace. No card needed.

2. Create an API key#

In the console, open API keys and choose Create key. Copy it right away: it's shown once. Keys start with hf_live_. Keep yours out of browsers and repositories, for example in an environment variable:

Shell

export HAPPYFETCH_API_KEY="YOUR_API_KEY"

3. Look up a company#

Send a LinkedIn company URL. A slug or a numeric id works too.

curl https://api.happyfetch.net/v1/company --max-time 120 \
  -H "Authorization: Bearer $HAPPYFETCH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.linkedin.com/company/stripe"}'

const res = await fetch("https://api.happyfetch.net/v1/company", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAPPYFETCH_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // send the same key when you retry this call
  },
  body: JSON.stringify({
    "url": "https://www.linkedin.com/company/stripe"
  }),
  signal: AbortSignal.timeout(120_000),
});
const { data, meta, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(meta.request_id, meta.cache.status, data);

import os, uuid, requests

res = requests.post(
    "https://api.happyfetch.net/v1/company",
    headers={
        "Authorization": f"Bearer {os.environ['HAPPYFETCH_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # send the same key when you retry this call
    },
    json={
      "url": "https://www.linkedin.com/company/stripe"
    },
    timeout=120,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["meta"]["request_id"], body["meta"]["cache"]["status"])

4. Read the response#

This is the complete response to that call, exactly as the API returns it:

200 OK

{
  "data": {
    "name": "Stripe",
    "tagline": "Help increase the GDP of the internet.",
    "description": "Stripe builds programmable financial services. Millions of companies—from the world’s largest enterprises to the most ambitious startups—use Stripe to accept payments, grow their revenue, and accelerate new business opportunities. Headquartered in San Francisco and Dublin, the company aims to increase the GDP of the internet.",
    "industry": "Technology, Information and Internet",
    "websiteUrl": "https://stripe.com",
    "phone": null,
    "logo": "https://media.licdn.com/dms/image/v2/D560BAQE2ZfJyfn-VCg/company-logo_200_200/B56ZlyKwpUKIAI-/0/1758557047806/stripe_logo?e=2147483647&v=beta&t=En4Hm6NDGbDTYCoOQ0Ko5Ne2gylx0WRb0yL2GlOeXBQ",
    "backgroundUrl": "https://media.licdn.com/dms/image/v2/D563DAQFt98MykXcktg/image-scale_191_1128/B56Z352EMMKIAY-/0/1778013193531/stripe_cover?e=2147483647&v=beta&t=UwiZWbPrYkD77DpQmZIjVuuqKMCfyZ-e-YcHE336MlY",
    "followerCount": 1721407,
    "employeeCount": 16594,
    "employeeCountRange": {
      "start": 5001,
      "end": 10000
    },
    "foundedOn": {
      "year": 2010
    },
    "headquarter": {
      "city": "South San Francisco",
      "country": "US",
      "geographicArea": "California",
      "postalCode": "94080",
      "street1": "354 Oyster Point Blvd",
      "street2": null
    },
    "locations": [
      {
        "city": "South San Francisco",
        "country": "US",
        "postalCode": "94080",
        "state": "California",
        "street1": "354 Oyster Point Blvd",
        "street2": null
      }
    ],
    "specialities": [],
    "universalName": "stripe",
    "linkedInUrl": "https://www.linkedin.com/company/stripe",
    "linkedInId": "2135371"
  },
  "meta": {
    "request_id": "85fcc6e9-767a-44b1-876e-4099e3542ef9",
    "endpoint": "company",
    "credits_charged": 2,
    "credits_remaining": 198,
    "cache": {
      "status": "miss",
      "age_seconds": 0,
      "fetched_at": "2026-09-22T17:40:00.000Z",
      "max_age_seconds": 604800
    },
    "content_hash": "sha256:5da96e23d8f77cc3b21e33ef47ed3f0086328e61fdf427f2941e351f56af9554",
    "canonical": {
      "slug": "stripe",
      "id": "2135371"
    }
  }
}

data is the company. All 18 fields are always present.
meta.request_id identifies this call. Quote it to support; it ties the call to its charge and to the data it returned.
meta.cache says whether the answer came from our cache and how old it is.
meta.credits_charged and meta.credits_remaining show what the call cost.

5. Go further#

Search the web with POST /v1/search, using the same key and credits.
Retrying after a network error? Add an Idempotency-Key so it's never charged twice.
See what every error means and which ones are refunded.