API reference

Brand API

GET /v1/brands/{domain}: every field in the response (logos, brand colors, fonts, company data), the parameters, status codes and caching.

Request

GEThttps://brandidentityapi.com/v1/brands/{identifier}

Needs a secret key. A lookup costs one credit only when it returns a brand with a logo: a 4xx or 5xx answer is refunded straight away.

Path parameter

Name	Description
identifier	A domain (`stripe.com`), a URL (`https://www.stripe.com/pricing`, URL-encoded) or an email address (`jane@stripe.com`). We reduce it to the registrable domain, so `shop.example.co.uk` is filed under `example.co.uk`. IP addresses, `localhost` and private suffixes such as `.local` are refused with `invalid_domain`.

Query parameter

Name	Description
refresh	`true` re-crawls the site now instead of answering from the index. Paid plans only; on the free plan it is ignored. It counts as one lookup, like any other.

Example

curl https://brandidentityapi.com/v1/brands/stripe.com \
  -H "Authorization: Bearer $BRAND_IDENTITY_API_KEY"

200 OK · stripe.com, trimmed

{
  "id": "0b7e9a52-3c1d-4f6e-8a2b-5d9c1e7f4a30",
  "name": "Stripe",
  "domain": "stripe.com",
  "claimed": false,
  "description": "Stripe is a financial infrastructure platform that businesses use to accept payments and manage money online.",
  "longDescription": null,
  "links": [
    {
      "name": "twitter",
      "url": "https://x.com/stripe"
    },
    {
      "name": "linkedin",
      "url": "https://www.linkedin.com/company/stripe"
    },
    {
      "name": "github",
      "url": "https://github.com/stripe"
    }
  ],
  "logos": [
    {
      "type": "logo",
      "theme": "dark",
      "formats": [
        {
          "src": "https://brandidentityapi.com/cdn/5f0d6a1e8c2b4e7a9d3f1b6c0a8e2d4f.svg",
          "format": "svg",
          "background": "transparent",
          "width": 360,
          "height": 150,
          "size": 1612
        },
        {
          "src": "https://brandidentityapi.com/cdn/5f0d6a1e8c2b4e7a9d3f1b6c0a8e2d4f.png",
          "format": "png",
          "background": "transparent",
          "width": 1024,
          "height": 427,
          "size": 18244
        }
      ],
      "tags": []
    },
    {
      "type": "logo",
      "theme": "light",
      "formats": [
        {
          "src": "https://brandidentityapi.com/cdn/9a3c7e1f5b0d4a8c2e6f1d9b3a7c5e0f.svg",
          "format": "svg",
          "background": "transparent",
          "width": 360,
          "height": 150,
          "size": 1598
        }
      ],
      "tags": [
        "generated"
      ]
    },
    {
      "type": "icon",
      "theme": null,
      "formats": [
        {
          "src": "https://brandidentityapi.com/cdn/2e8b4d0f6a1c3e5b7d9f0a2c4e6b8d1f.png",
          "format": "png",
          "background": "transparent",
          "width": 256,
          "height": 256,
          "size": 6340
        }
      ],
      "tags": []
    }
  ],
  "colors": [
    {
      "hex": "#635bff",
      "type": "accent",
      "brightness": 112
    },
    {
      "hex": "#0a2540",
      "type": "dark",
      "brightness": 32
    },
    {
      "hex": "#f6f9fc",
      "type": "light",
      "brightness": 248
    }
  ],
  "fonts": [
    {
      "name": "Sohne",
      "type": "title",
      "origin": "custom",
      "originId": null,
      "weights": [
        500,
        600
      ]
    },
    {
      "name": "Sohne",
      "type": "body",
      "origin": "custom",
      "originId": null,
      "weights": [
        400
      ]
    }
  ],
  "images": [],
  "ogImage": "https://stripe.com/img/v3/home/social.png",
  "company": {
    "employees": 5001,
    "foundedYear": 2010,
    "kind": "PRIVATELY_HELD",
    "location": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "countryCode": "US",
      "region": "Americas",
      "subregion": "Northern America"
    },
    "industries": [
      {
        "id": "payments",
        "name": "Payments",
        "slug": "payments",
        "emoji": "💳",
        "score": 0.92,
        "parent": {
          "id": "finance",
          "name": "Finance & Fintech",
          "slug": "finance",
          "emoji": "💳"
        }
      }
    ],
    "ticker": null,
    "financialIdentifiers": {
      "isin": [],
      "ticker": []
    }
  },
  "qualityScore": 0.94,
  "isNsfw": false,
  "restriction": null,
  "urn": "urn:brandidentityapi:brand:0b7e9a52-3c1d-4f6e-8a2b-5d9c1e7f4a30",
  "status": "ready",
  "updatedAt": "2026-10-12T09:00:00.000Z"
}

Response fields

Field names follow Brandfetch's Brand API v2. Fields marked as additions are ours.

Brand

Brand fields
Field	Type	Description
id	string	The record's stable id.
name	string \| null	The brand's name as it presents itself.
domain	string	The registrable domain the record is filed under.
claimed	boolean	True when the brand's owner has claimed and checked the record.
description	string \| null	One or two neutral sentences about what the company does.
longDescription	string \| null	A longer description, when one is available.
links	Link[]	Social and reference profiles. See Link.
logos	Logo[]	Every logo we kept, each with its formats. See Logo.
colors	Color[]	Brand colors with their roles. See Color.
fonts	Font[]	The title and body fonts the site loads. See Font.
images	Image[]	The site's pictures, none of them icons: the banner (its share image) first, then the other images we found on its page. Each is a JPEG on our CDN, at most 1600px wide. Empty when the site has none.
ogImage	string \| null	The URL of the site's own share image: og:image, or twitter:image when the page has no og:image. It points at the file on the site. When the file is at least 400 by 200, we also keep a copy as a banner in images. An addition to Brandfetch's shape.
company	Company \| null	Firmographics. See Company.
qualityScore	number	0 to 1: how complete and trustworthy the record is.
isNsfw	boolean	True when the site is adult content. The record is then empty: no name, logos, colors, fonts, images, links or description, and a company with only its Adult industry.
restriction	{ code, message } \| null	Null for a normal record. For an adult site, `{ code: "nsfw", message }` says why the record is empty, so it is not mistaken for a site we failed to read. An addition to Brandfetch's shape.
urn	string	`urn:brandidentityapi:brand:{id}`
status	"ready" \| "partial" \| "pending" \| "failed"	Whether the record is complete. Partial records are retried sooner. An addition to Brandfetch's shape.
updatedAt	string	When the record was last refreshed, ISO 8601. An addition.

Logo

Logo fields
Field	Type	Description
type	"icon" \| "symbol" \| "logo" \| "other"	icon: a square mark, like an app icon. symbol: the mark without words. logo: the wordmark or full lockup.
theme	"light" \| "dark" \| null	The color of the artwork's ink. A dark logo is for light backgrounds; a light logo is for dark backgrounds. Null when it reads on both.
formats	Format[]	The same logo in each file format we have, SVG first.
tags	string[]	Hints. `generated` means we drew this variant from a single-color original for the other background; `wikimedia` means the file came from Wikimedia Commons; `photographic` marks a photo rather than artwork.

Format

Format fields
Field	Type	Description
src	string	Absolute URL of the file on our CDN. Stable: safe to store and hotlink.
format	"svg" \| "png" \| "webp" \| "jpeg" \| "ico"	The file format.
background	"transparent" \| null	transparent when the image has a used alpha channel.
width	number \| null	Pixels. For an SVG, its intrinsic size.
height	number \| null	Pixels.
size	number	File size in bytes.

Color

Color fields
Field	Type	Description
hex	string	Six lower-case hex digits with a leading #.
type	"accent" \| "dark" \| "light" \| "brand"	accent: the most saturated color the brand uses prominently. dark: the darkest color in real use. light: the lightest. brand: the other distinct colors, heaviest first. At most six.
brightness	number	0 to 255, perceived brightness, `(299R + 587G + 114B) / 1000`. Put dark text on colors at 150 and above.

Font

Font fields
Field	Type	Description
name	string	The family name, as the site declares it.
type	"title" \| "body"	Where the site uses it: headings or running text.
origin	"google" \| "adobe" \| "custom" \| "system"	Where the font file comes from. custom is a self-hosted or licensed face. adobe (Adobe Fonts) is an addition; Brandfetch reports those as custom.
originId	string \| null	The family id at its origin, such as the Google Fonts family name.
weights	number[]	Weights the site loads, such as 400 and 600.

Link

Link fields
Field	Type	Description
name	string	twitter, linkedin, github, instagram, facebook, youtube, tiktok, crunchbase, discord, pinterest, threads, bluesky, medium or wikipedia.
url	string	The profile URL.

Company

Company fields
Field	Type	Description
employees	number \| null	The floor of a headcount band: 1, 2, 11, 51, 201, 501, 1001, 5001 or 10001. 2 is 2 to 10; records crawled before that band existed say 1 for 1 to 10.
foundedYear	number \| null	The year the company was founded.
kind	string \| null	PUBLIC_COMPANY, PRIVATELY_HELD, NON_PROFIT, GOVERNMENT_AGENCY, EDUCATIONAL, SELF_EMPLOYED or PARTNERSHIP.
location	Location \| null	Headquarters. See Location.
industries	Industry[]	Up to three industries, most likely first. See Industry.
ticker	string \| null	Exchange and symbol for a listed company, such as NASDAQ:AAPL. An addition.
financialIdentifiers	{ isin: string[], ticker: string[] }	Brandfetch's field, never null: ticker holds the bare symbol from ticker above, such as AAPL. isin is not collected yet and is always empty.

Location

Location fields
Field	Type	Description
city	string \| null	City.
state	string \| null	State, province or region.
country	string \| null	Country name in English.
countryCode	string \| null	ISO 3166-1 alpha-2 code, such as US.
region	string \| null	Continent-level region, such as Americas.
subregion	string \| null	Subregion, such as Northern America.

Industry

Industry fields
Field	Type	Description
id	string	Stable id of the category.
name	string	Display name.
slug	string	URL-safe name, stable forever.
emoji	string	An emoji for the parent category.
score	number	0 to 1: how sure the classifier is.
parent	object \| null	The parent category (id, name, slug, emoji), or null for a top-level one.

Image

Image fields
Field	Type	Description
type	"banner" \| "other"	banner: the site's share image (og:image). other: another picture from its page, a hero or a team photo.
formats	Format[]	As for logos.
tags	string[]	Hints, as for logos.

Status codes

Status	Code	Meaning
200		The brand record.
400	invalid_domain	The identifier has no public domain in it.
401	unauthorized	No key, or a key that is not valid.
403	forbidden	A publishable key, or a suspended account.
404	domain_not_found	No site answers at that domain.
404	no_brand_data	The site answered, but there was nothing to build a brand from.
422	fetch_blocked	The site refused our crawler, or resolves to an address we never fetch.
402	insufficient_credits	No credits left. Add credits on the billing page.
429	rate_limited	Too many requests this minute.
502	fetch_failed	The site could not be fetched.
504	timeout	The live crawl ran out of time. Retry in a minute.
500	internal_error	Something failed on our side.
503	internal_error	Usage metering was briefly unavailable, so nothing ran and nothing was counted. See Retry-After.

Every error has the same envelope. The Errors page has one entry per code.

Headers

Header	Description
X-Cache	`HIT` when the answer came from the index, `MISS` when it was crawled for this request.
X-Request-Id	A unique id for the request. Quote it when you contact us.
X-Credits-Remaining	Credits left after this lookup.
X-RateLimit-Limit	Requests allowed per minute on your plan.
X-RateLimit-Remaining	Requests left in the current minute.
X-RateLimit-Reset	When the current minute ends, in Unix seconds.
Retry-After	On a 429, how many seconds to wait.

Freshness and refresh

A complete record is re-crawled when it is more than 30 days old and someone looks it up. You get the stored record at once; the refresh runs behind it.
A partial record, usually from a site that was down or slow, is retried after 3 days.
On paid plans, ?refresh=true re-crawls on the spot and returns the new record.

Caching on your side

You may cache and store responses forever, on every plan. The updatedAt field tells you how old a record is if you want your own refresh rule.

GET /v2/brands/{identifier} and GET /v2/brands/domain/{domain} answer exactly like this endpoint, at the paths Brandfetch's API uses. Point a Brandfetch client at https://brandidentityapi.com and it works. See Migrate from Brandfetch.