# HappyFetch API

HappyFetch has five endpoints. All take JSON and return JSON. The lookups and search are billed per call
in credits; the cache check is free.

| Endpoint | What it does |
|---|---|
| [`POST /v1/company`](/docs/company) | Turns a LinkedIn company URL, slug, numeric id or URN into a structured company profile. |
| [`POST /v1/domain`](/docs/domain) | Finds the company behind a website domain and returns the same profile. |
| [`POST /v1/person`](/docs/person) | Returns a person's public mini profile from their LinkedIn profile: name, location, employers and schools. |
| [`POST /v1/search`](/docs/search) | Runs a web search and returns the results as JSON. |
| [`POST /v1/cache`](/docs/cache) | Free: says how old our copy of a company is, and what a lookup would cost now. |

The base URL is `https://api.happyfetch.net`. Authenticate with your API key in `Authorization: Bearer <key>`; see
[Authentication](/docs/authentication).

## Every response looks the same

A result has `data` (what you asked for) and `meta` (what it cost and how fresh it is). This is a
complete company lookup, exactly as the API returns it:

```json title="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"
    }
  }
}
```

An error has `error` (what went wrong and whether retrying helps) and the same `meta`. Every error
code has its own entry in [Errors](/docs/errors), and `error.doc_url` links straight to it.

## Principles

- **You pay for answers, not attempts.** Calls we can't complete are refunded automatically in the same
  request. Invalid input and rate limits are never charged. See [Credits, billing and refunds](/docs/billing).
- **Every call is traceable.** `meta.request_id` (also the `X-Request-Id` header) ties the call to its
  charge and to the data it returned.
- **Repeat lookups are cheap and fast.** Results are cached in our database; see [Caching](/docs/caching).
- **Retries are safe.** Send an `Idempotency-Key` and a retry replays the stored answer instead of charging
  twice; see [Idempotency](/docs/idempotency).

Start with the [quickstart](/docs/quickstart): an account, a key and a first call in five minutes.