# Overage billing Source: https://docs.brandfetch.com/brand-api/overage-billing When you purchase a subscription plan, you are allotted a quota depending on the payment plan. When you make more API requests than your quota allows, rather than blocking requests which are over your quota, we apply overage billing. This means that you'll never have any unexpected downtime. Requests over your quota are charged at an overage-fee rate. To set a spending limit, head to the [Developer Dashboard](https://developers.brandfetch.com/dashboard/billing) and set a hard spending limit. Set this to \$0 if you want to disable overage. Further details on the mechanics of overage are available [here](/changelog#overage-billing). Overage billing is not available on the free plan. To start using overage, please upgrade first to one of the paid plans. # Overview Source: https://docs.brandfetch.com/brand-api/overview Brand data for B2B Personalization If you have custom requirements, or any questions [contact us](https://brandfetch.com/developers/contact/sales). [Brand API](https://brandfetch.com/developers/brand-api) provides programmatic access to any company's brand assets through a single API call. This includes their latest logos, color schemes, fonts, images, and other firmographic information. Brand API works in real-time, if a brand is not part of our dataset, it will index the information live ensuring **global coverage** for businesses of all sizes, geography and industries. ## Implementation guide For more details, refer to our [API Reference](/reference/brand-api). You’ll need to create an account on our [Developer Portal](https://developers.brandfetch.com/register). Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your API key. Implement or run the code below to make your first API request. ```curl curl theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/{identifier} \ --header 'Authorization: Bearer ' ``` Authentication is done by passing your API key as a [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). The Brand API can be accessed through the following structure: To avoid potential naming collisions between identifier types (e.g., a Stock or ETF ticker that matches a domain), you can use explicit type routes: `/v2/brands/{type}/{identifier}` where `type` can be `domain`, `ticker`, `isin`, or `crypto`. All requests for the domain brandfetch.com are free and will not count towards your usage/quotas. You can make as many requests to the Brandfetch’s brand as you need while you iterate on and test your integration. Once you are ready to go live, simply replace brandfetch.com with the domain name, Stock/ETF ticker, ISIN, or Crypto symbol you want to look up. ## Query by domain, Stock/ETF ticker, ISIN, or Crypto symbol The Brand API supports multiple identifier types to query brand data: * **Domain:** `nike.com` (e.g., `https://api.brandfetch.io/v2/brands/nike.com`) * **Stock or ETF ticker:** `NKE` (e.g., `https://api.brandfetch.io/v2/brands/NKE`) * **ISIN:** `US6541061031` (e.g., `https://api.brandfetch.io/v2/brands/US6541061031`) * **Crypto symbol:** `BTC`, `ETH` (e.g., `https://api.brandfetch.io/v2/brands/BTC`) To avoid potential naming collisions between identifier types, you can use explicit type routes with the pattern `/v2/brands/{type}/{identifier}`: ```curl Auto-detection theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/nike.com \ --header 'Authorization: Bearer ' ``` ```curl Domain theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/domain/nike.com \ --header 'Authorization: Bearer ' ``` ```curl Stock or ETF ticker theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/ticker/NKE \ --header 'Authorization: Bearer ' ``` ```curl ISIN theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/isin/US6541061031 \ --header 'Authorization: Bearer ' ``` ```curl Crypto symbol theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/crypto/BTC \ --header 'Authorization: Bearer ' ``` ### Auto-detection (legacy) The original route `/v2/brands/{identifier}` still works and will auto-detect the identifier type. The detection order is: domain → Stock or ETF ticker → ISIN → Crypto symbol. However, **we recommend using explicit type routes** to prevent collisions and ensure accurate results. If you only have company names, use the [Brand Search API](/brand-search-api/overview) to match brand names to the most likely URLs. ## API Reference For more details, refer to our [API Reference](/reference/brand-api). # Quotas and usage Source: https://docs.brandfetch.com/brand-api/quotas-and-usage When you sign up for a free developer account, you get 100 free requests. If you need to make more requests, please upgrade to a paid plan. When upgrading, you can confirm your quota by looking at the `x-api-key-quota` response header. To see your current month's usage, look for the `x-api-key-approximate-usage` response header. We will also send you an email warning you upon reaching 80% of your quota. The API will return an HTTP status code 429 when the quota has been reached. In addition to a usage quota we also apply a request throughput limit to protect our service from abuse. By default, throughput is limited to a sustained 100 requests/second with some flexibility to accommodate bursts (30,000 requests / rolling 5 minute hard limit). You'll receive an HTTP status code 429 when you exceed this limit. If your use-case requires higher throughput limits, [contact us](https://brandfetch.com/developers/contact/sales). # Brand Search API Usage Guidelines Source: https://docs.brandfetch.com/brand-search-api/guidelines Match brand names to their domain and logo Brand Search API is free to use and we don't ask for any attribution. ## Authentication **To use Brand Search API, you must include your client ID with every request.** Adding your client ID provides reliable access, supports fair usage, and keeps consistent performance across all requests. [Create a free account](https://developers.brandfetch.com/register) and access your client ID from the Developer Portal. To use Brand Search API, include your client ID with every request as shown below: ```curl curl theme={null} curl --request GET \ --url "https://api.brandfetch.io/v2/search/:name?c=BRANDFETCH_CLIENT_ID" ``` ## Hotlinking **We require Brand Search API to be directly embedded in your user-facing applications.** The API should be used directly as is, with all data fetched live and not altered or persisted. Your users should make requests to the API directly from their browsers. The logo image URLs provided by the Brand Search API must be hotlinked. Other data, such as brand names, should not be cached and should be used exclusively for building an autocomplete experience. Image URLs expire after 24 hours and must be refetched. For more information on the API’s availability, see our [uptime status](https://status.brandfetch.io/). We can provide custom SLAs for enterprise customers. If your use case requires more flexibility, please [contact us](https://brandfetch.com/developers/contact/sales) for a custom setup. ## Replicating Brandfetch **You cannot replicate the core user experience of Brandfetch.** The best way to ensure that your application doesn’t violate this guideline is by integrating Brandfetch into an existing app that offers more value than just the Brandfetch integration. Some examples: * ✅ The [Pitch integration](https://brandfetch.com/developers/customers/pitch) helps their users autocomplete brand names to streamline logo search within Pitch’s editor. Without this integration, the app still has a lot of value to its users. * 🚫 An unofficial Brand Search API that allows users to autocomplete brands. Without the API, the app has no content and no value to users. If you're unsure about your use case, please [contact us](https://brandfetch.com/developers/contact). # Overview Source: https://docs.brandfetch.com/brand-search-api/overview Match brand names to their domain and logo [Brand Search API](https://brandfetch.com/developers/brand-search-api) provides fast querying of brands. It lets you search by brand names and match them to their corresponding URLs, enabling you to create rich autocomplete experiences. The Brand Search API is designed to work in tandem with our other services. Once a user selects a brand, you can use its unique identifier to retrieve detailed data using our other APIs. ## Implementation guide For more details, refer to our [API Reference](/reference/brand-api). You’ll need to create an account on our [Developer Portal](https://developers.brandfetch.com/register). Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your client ID. Brand Search API is free to use and we don't ask for any attribution. Implement or run the code below to make your first API request. ```curl curl theme={null} curl --request GET \ --url "https://api.brandfetch.io/v2/search/:name?c=BRANDFETCH_CLIENT_ID" ``` Authentication is done by passing your client ID as a query parameter. The Brand Search API is a free product. Before you deploy your application to a live environment, be sure to consult our [rate limits](/brand-search-api/rate-limits) and review our [usage guidelines](/brand-search-api/guidelines) to ensure a smooth launch. ## API Reference For more details, refer to our [API Reference](/reference/brand-search-api). # Rate limits Source: https://docs.brandfetch.com/brand-search-api/rate-limits We offer a fair use base rate limit of 500,000 requests per month, with 200 requests per 5 minutes per IP address, which is designed to cover most small to medium applications. The rate limit should allow for roughly 30 search-sessions in a 5-minute period and is intended to discourage abuse. Use a [debounce strategy](https://developer.mozilla.org/en-US/docs/Glossary/Debounce) inbetween keystrokes to avoid hitting the rate limit. If your usage approaches the monthly limit, we may reach out to discuss an upgrade to a paid, unlimited tier. For enterprises, we provide custom solutions, including SLA agreements, custom terms, and flexible caching options to ensure optimal performance at scale. These plans are tailored to meet the needs of high-volume users. Feel free to [contact us](https://brandfetch.com/developers/contact/sales) to discuss the right plan for your use case. # Changelog Source: https://docs.brandfetch.com/changelog/index Follow along with updates across Brandfetch’s API. ## 2026 Updates ### **Cryptocurrency support in Brand API & Logo API** We've added support for the top 2000 cryptocurrency symbol (e.g., `BTC`, `ETH`) to both Brand API and Logo API. You can now query Logos using crypto symbols alongside domains, stock or ETF tickers, and ISINs. ```html Crypto symbol theme={null} Bitcoin logo by Brandfetch ``` ### **ETF ticker in Brand API & Logo API** We've added support for the top 10,000 ETFs provided by more than 300 US and European providers. Querying with an ETF ticker will return the logo of its provider. ```html ETF ticker theme={null} Invesco logo provided by Brandfetch ``` ### **Explicit Type Routes** To prevent naming collisions between identifier types, we've also introduced explicit type routes with the pattern `{type}/{identifier}` where `type` can be `domain`, `ticker`, `isin`, or `crypto`. While the original routes still work with auto-detection, **we recommend using explicit type routes** for accurate results. **Examples:** ```curl Auto-detection theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/nike.com \ --header 'Authorization: Bearer ' ``` ```curl Domain theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/domain/nike.com \ --header 'Authorization: Bearer ' ``` ```curl Stock or ETF ticker theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/ticker/NKE \ --header 'Authorization: Bearer ' ``` ```curl ISIN theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/isin/US6541061031 \ --header 'Authorization: Bearer ' ``` ```curl Crypto symbol theme={null} curl --request GET \ --url https://api.brandfetch.io/v2/brands/crypto/BTC \ --header 'Authorization: Bearer ' ``` Get started by reviewing the [Brand API documentation](/brand-api/overview) and [Logo API documentation](/logo-api/overview). *** ## 2025 Updates ### **Query by ISIN & Stock ticker: Now available in Brand API & Logo API** We've expanded the capabilities of our Brand API and Logo API endpoints. You can now query brand data directly using financial identifiers such as ISIN (e.g., `US6541061031`) or Stock tickers (e.g., `NKE`). Previously, website URLs or Brand IDs were the primary ways to access brand information. With this update, simply input an ISIN or Stock ticker to easily retrieve brand details and logos, further streamlining integrations for financial and investment platforms. Get started by reviewing the [documentation](/brand-api/overview). ### **Transaction API: Turn payment transactions into merchant data.** We've released a new endpoint called the Transaction API, enabling you to convert messy payment transactions into merchant data (e.g., logos, name, location, industry, etc.). The primary input for querying the Transaction API is a raw transaction descriptor (the line-item text on a bank or credit card statement). You provide this as the `transactionLabel` in the request body, along with a `countryCode` to narrow down the merchant’s locale. For example, a transaction label like `STARBUCKS 1523 OMAHA NE` with country code `US` can be resolved to `starbucks.com`. Get started by reading the [documentation](/transaction-api/overview). ### **404 Fallback for Logo API** We have introduced a new fallback option to the Logo API, enabling you to choose whether you want to receive a 404 response if no logo is found. This complements our existing fallback options: `transparent`, `lettermark`, and `brandfetch`. You can access the 404 fallback in the same way as the other fallback options by specifying `404` in the link: [`https://cdn.brandfetch.io/randomInvalidDomain.com/fallback/404/icon`](https://cdn.brandfetch.io/randomInvalidDomain.com/fallback/404/icon) *** ## 2024 Updates ### Logo API Logo API is a simple CDN link that gives you access to any brand’s latest logos. Logos by Brandfetch `https://cdn.brandfetch.io/brandfetch.com?c={your-client-id-here}` It’s customizable with powerful transformation capabilities and is meant to be directly embedded in your HTML tags so the logo always remains up-to-date. **Key features:** * **Rich taxonomy:** Access not just logo icons, but also brand symbols and main horizontal logos. * **Theme support:** Access dark or light logos so you can display them on any background. * **Customizable sizing:** Adjust the logo’s height and width to fit your needs. * **Smart fallbacks:** Even when a logo isn’t available, you’ll get fallbacks. * **Stay on-brand:** Logos automatically updates to the latest brand logo, so you’re always on-brand. Best of all? [It’s free without attribution](/logo-api/guidelines). Get started by trying the [query builder](https://brandfetch.com/developers/logo-api) and reading the [documentation](/logo-api/overview). ### Brand Quality Score We now score brands on quality and make the score available via the Brands API. The quality score is a float between 0-1 which indicates the quality of the data for the given brand. The score is useful for when you don't want to show lower quality brands to your users. Each brand now has a new `qualityScore` attribute with it's respective score: ```json theme={null} { "name": "Brandfetch", "domain": "brandfetch.com", "qualityScore": 0.7599741515319993, ... } ``` The score is engineered to divide into thirds: Lower 3rd is poor quality, middle 3rd is OK quality, upper 3rd is high quality. Lower scores indicate that a brand is less likely to be a "real" brand. For example, where google.com will score high, my-random-blog.com will score between 0.3-0.4. The score factors in things like data-recency, whether the brand has been claimed, if it has been manually verified by our team, the brand's domain ranking on the web, as well as other factors. The score can be used to sort multiple brands in a list to determine which brand may be the best option to show to a user. The way we calculate this score may change over time such that a score for a given brand may change, but will remain aligned such that it divides quality into thirds: low, medium, high. ### Brand Firmographics We've added a few firmographic attributes to brands on the Brands API. The new attributes: number of employees, year founded, industry categorization, company kind, and geographic information about the brand's company headquarters. ```json theme={null} { "name": "Stripe", "domain": "stripe.com", "company": { "employees": 1001, "foundedYear": 2010, "industries": [ { "score": 1, "id": "37", "name": "Programming and Developer Software", "emoji": "🖥", "parent": { "emoji": "🖥", "id": "28", "name": "Computers Electronics and Technology", "slug": "computers-electronics-and-technology" }, "slug": "programming-and-developer-software" }, { "score": 1, "id": "28", "name": "Computers Electronics and Technology", "emoji": "🖥", "parent": null, "slug": "computers-electronics-and-technology" } ], "kind": "PRIVATELY_HELD", "location": { "city": "South San Francisco", "country": "United States", "countryCode": "US", "region": "Americas", "state": "California", "subregion": "Northern America" }, }, ... } ``` More details on the available attributes can be found in the API documentation [here](/reference/brand-api). ### Brand is NSFW? We've added a `isNsfw` convenience attribute to the root of the brand object on the Brands API response. When the value of `isNsfw` is `true`, we're indicating that we believe the brand to be, contain, or relate to adult content such as pornography (both photographic and animated) as well as adult-related like online sex shops. ```json theme={null} { "name": "Example", "domain": "adult-content.xxx", "isNsfw": true, ... } ``` ### Brand industry classifications We now classify brands into one or more industry categories and make this data available through the Brands API. The industry is returned on brands' company attribute: ```json theme={null} { "name":"Stripe", "domain": "stripe.com", "company": { "industries": [ { "score": 1, "id": "37", "name": "Programming and Developer Software", "emoji": "🖥", "parent": { "emoji": "🖥", "id": "28", "name": "Computers Electronics and Technology", "slug": "computers-electronics-and-technology" }, "slug": "programming-and-developer-software" }, { "score": 1, "id": "28", "name": "Computers Electronics and Technology", "emoji": "🖥", "parent": null, "slug": "computers-electronics-and-technology" } ], ... }, ... } ``` More details on the available attributes can be found in the [API Reference](/reference/brand-api). In the coming weeks we will release a free Taxonomy API for retrieving our industry taxonomy. In the meantime view the complete industry list [here](https://docs.google.com/spreadsheets/d/1N44nMfVtPCFM4ebTcmRlqbyxjFtDAGVuqd0mh0dcOU0/edit?usp=sharing). *** ## 2023 Updates ### Refreshed Developer Dashboard We've rolled out an updated developer dashboard. The new dashboard better communicates your API usage and makes it easier to monitor your API requests. Here’s what we've added: * **Overage Budget Limit Control**: You can now set your own overage budget limit. Don't want to spend more than you planned? Set it up right in the dashboard. * **API Usage**: Keep an eye on your API usage. Simple and clear to help you track what you're using. * **Usage History**: See your usage over the past months. ### Overage billing budget hard limit controls In November we released overage billing for paid customers which let's customers make requests beyond their plan quotas. Via the developer dashboard, customers can now also set a spending hard limit to better control costs of overage fees. This makes it possible to go over quota, but not go being a certain dollar amount. The default monthly budget is set at \$100 USD. ### Pseudo-Sandbox All requests for the brand `brandfetch.com` are now free and will not count towards your usage quota. For example, if you fetch the brandfetch.com brand via `GET` `https://api.brandfetch.com/v2/brands/brandfetch.com`, your request will not count towards your quota. You can make as many requests for the brandfetch.com brand as you need while you iterate on and test your integration. ### "photographic" and "portrait" asset tags for logos and icons To give you more insight into the assets you work with, we've introduced a powerful new tagging feature. Now, assets such as Logos and Icons come with descriptive tags that provide a quick understanding of their characteristics. For instance, you might see the "photographic" tag associated with an asset, indicating that the image has realistic elements, which might differ from the standard vector logos typically used by brands. Similarly, the "portrait" tag suggests that the asset includes a portrait-like image, offering a personal touch often used by sole proprietors or small brands. These tags are designed to streamline your search and selection process, allowing you to quickly identify the type of asset you need and want to use with your customers. Check our our [API documentation](/reference/brand-api) for further details. ### Overage Billing We are thrilled to announce a frequently requested update to our subscription payment plans that will provide you with greater flexibility over your usage. Starting this month, we're saying goodbye to the hard limits on API requests that could disrupt your business. No more interruptions. Instead, we understand that your demand may sometimes exceed your quota, and we want to support your growth every step of the way. Here’s what’s changing: * **No more hard stops**: Once you hit your usage quota, you won't face immediate cutoffs anymore. Our system will continue to seamlessly fulfill your API requests. * **Transparent overage fees**: Each additional request over your quota will now be billed at a \$0.1 per request. Upgrade your billing plan at any time to take advantage of bucket discounts. * **End-of-month overage billing**: Any overages will be billed at the end of the month, allowing you to manage your budget without any mid-month surprises. To disable or limit your overage fees, log into your [developer dashboard](https://developers.brandfetch.com) and set a spending limit. Set the limit to \$0 to completely disable overage. Overage billing is not available on the Free plan. To start using overage, please upgrade first to one of the paid plans. ### longDescription property on brands Introducing `longDescription` – In-depth brand narratives We've heard your feedback! Alongside our flexible API request limits, we're excited to introduce an enhancement to our Brand API that will enrich the data you receive about each brand. While our description field provided a short blurb for brands, there was a growing need for more comprehensive descriptions—including for use with generative AI products to create content such as videos and other media. Here’s what’s new: * **`longDescription` property**: Dive deeper with `longDescription`, a new property in the Brand API's response that offers an extensive description about each brand. * **Richer brand stories**: These longer descriptions encapsulate the essence of a brand, giving you more context and content to engage with your audience. By weaving in the brand's history, industry standing, and product range, `longDescription` gives you the data to generate answers to question from your users and provides the context to derive further actions. * **Seamless integration**: The new property is available right now. You can start fetching more detailed brand narratives without any changes to your current setup. `longDescription` is already being returned in in your requests today. ### The Brand Search API We are pleased to announce that we've released the Brand Search API 🎉 The Brand Search API is a powerful tool designed to help users find a brand based on its name. Whether you're looking to build a brand autocomplete feature or simply want to search for a specific brand, this API has you covered. Feel free to check out [our documentation](/brand-search-api/overview) to learn more about it! ### Usage & Quota Notification 1. Every user of the Brand API will now be notified via email if their usage goes beyond 80% of the allocated limit. 2. Users can view their quota by checking `x-api-key-quota`, and can also keep track of their usage for the current month by referring to `x-api-key-approximate-usage`. 3. The API will return an HTTP status code 429 when the quota has been reached. ### Dark & Light Logos You can now retrieve both the dark and light versions of the logo, the symbol and the icon (see example below). 🌗 ```JSON theme={null} "logos": [ { "type": "logo", "theme": "light", "formats": [ { "src": "https://asset.brandfetch.io/idL0iThUh6/id9WE9j86h.svg", "background": "transparent", "format": "svg", "size": 15555 } ] }, { "type": "logo", "theme": "dark", "formats": [ { "src": "https://asset.brandfetch.io/idL0iThUh6/idWbsK1VCy.png", "background": "transparent", "format": "png", "height": 215, "width": 800, "size": 33937 }, { "src": "https://asset.brandfetch.io/idL0iThUh6/idtCMfbWO0.svg", "background": "transparent", "format": "svg", "height": null, "width": null, "size": 15567 } ] }, { "type": "symbol", "theme": null, "formats": [ { "src": "https://asset.brandfetch.io/idL0iThUh6/iddCQ52AR5.svg", "background": "transparent", "format": "svg", "size": 2215 } ] }, { "type": "icon", "theme": "dark", "formats": [ { "src": "https://asset.brandfetch.io/idL0iThUh6/idls3LaPPQ.png", "background": null, "format": "png", "height": 400, "width": 400, "size": 2565 } ] }, { "type": "other", "theme": null, "formats": [ { "src": "https://asset.brandfetch.io/idL0iThUh6/idXGq6SIu2.svg", "background": "transparent", "format": "svg", "size": 2215 } ] } ] ``` # Getting started Source: https://docs.brandfetch.com/get-started [Brandfetch](https://brandfetch.com/developers) provides instant access to company logos and brand assets through a simple API. Retrieve high-quality logo files in multiple formats and sizes by passing a company name or domain. Eliminates manual logo collection and ensures consistent, up-to-date brand imagery across your application. ## Our APIs Personalize your customer journey by building unique branded experiences. Instantly add company logos to your app or website by domain name, Stock/ETF ticker, ISIN, or Crypto symbol. Autocomplete brand names for a streamlined user experience. Boost merchant recognition by enriching transactions with brand logos. ## Use cases * **[User XP](https://brandfetch.com/developers/user-xp) - Bring verified brand visuals into your product**: Add real logos, colors, brand styles or company information directly to your interface instantly and accurately. * **[Finance](https://brandfetch.com/developers/finance) - Identify merchants and enrich transactions**: Turn raw transaction data into recognizable brands. Perfect for banking apps, spending trackers, or transaction feeds. * **[Growth](https://brandfetch.com/developers/onboard) - Boost your campaigns with consistent brand data**: Enrich your marketing dashboards and reports with verified brand assets and metadata that stay current automatically. * **[Sales](https://brandfetch.com/developers/enrich) - Enrich your leads with brand identity**: Give your CRM and sales tools a visual upgrade by automatically adding company logos, colors, and brand data. * **[Gen AI](https://brandfetch.com/developers/gen-ai) - Feed real-time brand data into your AI models**: Give your AI tools brand context so they can generate accurate, on-brand visuals and text every time. ## Trusted by leading companies Don't take our word for it. Learn how brand data enables new heights in B2B personalization. * [How GBM made investing instantly recognizable with Brandfetch’s Logo API](https://brandfetch.com/developers/customers/gbm) * [How CyberRisk saw a 650% increase in conversion with one API call](https://brandfetch.com/developers/customers/cyberrisk) * [How Envestnet | Yodlee augmented their Merchant API for better merchant identification](https://brandfetch.com/developers/customers/yodlee) * [How Senja increased customer activation by 233% using the Brand API](https://brandfetch.com/developers/customers/senja) * [How Typeform saw a 5% lift in conversion by transforming their onboarding](https://brandfetch.com/developers/customers/typeform) See how other companies are leveraging our APIs to enhance their products and user experiences on [our website](https://brandfetch.com/developers/customers). # How to access the Brandfetch GraphQL API Source: https://docs.brandfetch.com/guides/access-graphql-api GraphQL is currently available to [Entreprise](https://brandfetch.com/developers/pricing) customers only, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). ## GraphQL Playground Explore the GraphQL API using the interactive playground: * [Apollo Studio](https://studio.apollographql.com/sandbox/explorer?endpoint=https%3A%2F%2Fgraphql.brandfetch.io) ## GraphQL schema definition You can find a guide on previewing the full schema reference in the following sections: # Using a custom fallback image with Logo API Source: https://docs.brandfetch.com/guides/customize-logo-api-fallback Learn how to handle 404s and implement your own fallback image. When working with [Logo API](/logo-api/overview), implementing proper fallback handling ensures a smooth user experience. While we provide [built-in fallback options](/logo-api/parameters), here's how to implement custom fallback handling for 404s and loading states in React. ### Enhanced Fallback Mechanism Our React approach combines the basic fallback structure with error handling and loading states: ```jsx theme={null} const LogoCDN = ({ domain, clientId, fallbackText = "N / A" }) => { const [isLoading, setLoading] = useState(true); const [isError, setError] = useState(false); // Transparent 1x1 pixel PNG used as initial placeholder const transparent = `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=`; // Construct the logo URL with domain and client ID const logoCDN = `https://cdn.brandfetch.io/${domain}/fallback/404/icon?c=${clientId}`; // Determine which source to use based on component state // - During loading: show transparent placeholder // - After loading, no error: show actual logo // - On error: transparent placeholder remains while fallback UI shows const src = !isLoading && !isError ? logoCDN : transparent; return (
setLoading(false)} onError={() => setError(true)} alt="Logo by Brandfetch" className="icon" src={src} /> {/* Fallback UI shown only when there's an error loading the logo */} {isError && (

{fallbackText}

)}
); }; ``` Style your fallback mechanism with this CSS: ```css theme={null} .wrapper { border-radius: 9999px; position: relative; overflow: hidden; height: 128px; width: 128px; } .fallback { background-color: #eaeaea; justify-content: center; align-items: center; text-align: center; display: flex; height: 100%; width: 100%; } .fallback p { font-weight: bold; font-size: 24px; color: #666; } .icon { position: absolute; object-fit: cover; height: 100%; width: 100%; left: 0; top: 0; } ``` ### How It Works 1. **Initial render:** Shows transparent placeholder image 2. **After initial load:** Attempts to load actual logo 3. **Success:** Displays logo 4. **Error:** Shows fallback UI with provided text The key benefits of using a transparent placeholder is that users never see the default browser "broken image" icon. ### Using the LogoCDN Component The LogoCDN component can be easily integrated into your React application. Here's how to use it: ```jsx theme={null} ``` The component automatically handles loading states and errors, providing a smooth experience for your users. # Guide to Logo Fair use Source: https://docs.brandfetch.com/guides/logo-fair-use Understanding fair use principles for logo usage ## What is Logo Fair Use? When using another company’s logo or branding through Brandfetch’s APIs, it’s essential to understand logo fair use to avoid legal issues. This guide explains fair use, its applications, and limitations, helping you use logos confidently and legally. ## DO’s and️ DONT’s ### ✅ What’s allowed: * **Referring:** One of the most common principles of fair use is to cite a brand using their logo. For example, a stock trading app might feature each company's logo to clearly identify the brands. * **Commentary:** You can use a logo when discussing or reviewing a company or its products. For instance, a tech blogger might include a logo in a review of a new smartphone to add relevance. * **Educational:** Logos can be used in educational contexts, like school projects or presentations analyzing branding strategies. A marketing class might use a logo to explore a company’s branding approach. * **Parody or Satire:** Logos can be used in parodies, as long as it’s clear the intent is humorous and not commercial. A comedic take on a brand’s ad campaign, using its logo, falls under fair use if it’s obviously a joke. ### ❌ What’s not allowed: * **Commercial Use:** Using a third party logo to on your own products or services is not fair use. For instance, placing a famous logo on merchandise without permission is likely trademark infringement. * **Confusing Similarity:** Any use that might mislead consumers into believing your business is affiliated with the logo owner is not fair use. Using a well-known logo on your website to imply a false affiliation can lead to legal issues. * **Trademark Damage:** If your use of the logo harms the reputation of the brand or makes it look bad, this is not fair use. For instance, using a logo in a way that insults the company can get you into trouble. * **Imitating the Logo’s Style:** Copying a logo’s style doesn’t qualify as fair use. Creating a similar logo to mimic a well-known brand violates trademark law. ## 4 Practical ways to determine fair use One well-known example is the case of "Louis Vuitton vs. Warner Bros" involving the movie The Hangover Part II. * **What happened:** In the movie, a character is seen carrying a bag that looks like a Louis Vuitton bag. The character even refers to it as a "Louis Vuitton" bag in a scene. However, the bag was actually a fake (a knockoff), not a real Louis Vuitton product. * **Designation of Origin:** Do you use the logo of a third party in a way that leads others to think your product could come from that third party? If yes, it’s likely not fair use. * **Market:** Will your use of the logo hurt the company’s ability to make money from it? If your use is unlikely to diminish the brand’s revenue or market position, it’s likely to be fair use. * **Compliance:** Are you using the logo as intended by the company, with the latest version and in accordance with brand guidelines? Use Brandfetch to ensure compliance and streamline your pro ## Legal considerations Trademark law is straightforward and consistent across most jurisdictions, and the downsides are usually manageable. Here’s the typical process: > *You can use the trademarks of others without infringing trademark law. When the legal situation is unclear and a brand has concerns about your use of their trademark, they’ll usually start with a request to take it down before taking legal action.*

**Christian Meisser - CEO of LEXR Law Switzerland AG** To help you stay compliant, Brandfetch provides the most up-to-date logos. If you're unsure, seek permission from the logo owner, email us, or consult a lawyer. *** *Logos are the property of their respective trademark owners. Logo usage must comply with the principles of "fair use," which allow referencing a brand without endorsement, misrepresentation, or alteration. If you're unsure, consult a legal professional.* # Overview Source: https://docs.brandfetch.com/guides/overview **Our APIs are easy to integrate, most teams are fully set up in minutes.** These tutorials are designed to help you leverage the full potential of our API and streamline your brand data integration process. * [Using a custom fallback image with Logo API](/guides/customize-logo-api-fallback) * [Query Brand API logos for different use cases](/guides/query-brand-api-logos) * [Setup a webhook and subscribe to brand updates](/guides/subscribe-to-webhook-updates) * [How to access the Brandfetch GraphQL API](/guides/access-graphql-api) ## Documentation For detailed information on our APIs, including endpoints, request parameters, and response formats, please refer to our comprehensive [documentation](/get-started). ## We're here to help! If you have any questions or run into any issues, [contact us](https://brandfetch.com/developers/contact). # Query Brand API logos for different use cases Source: https://docs.brandfetch.com/guides/query-brand-api-logos This recipe explores an effective strategy for selecting the best logo to display in company listing apps, such as those used in fintech and other industries. #### Query logos by type ```JavaScript index.js theme={null} const icon = brand.logos.find(({ type }) => type === 'icon') const logos = brand.logos.filter(({ type }) => type === 'logo') const symbols = brand.logos.filter(({ type }) => type === 'symbols') ``` #### Query logos by theme ```JavaScript index.js theme={null} const logoDark = brand.logos.find(({ type, theme }) => type === 'logo' && theme === 'dark') const logoLink = brand.logos.find(({ type, theme }) => type === 'logo' && theme === 'light') ``` #### Query a specific format ```JavaScript index.js theme={null} const file = logo.formats.find(({ format }) => format === 'svg') ``` #### Retrieve the best available format ```JavaScript index.js theme={null} const priorityList = ['svg', 'webp', 'png', 'jpeg', 'jpg'] const file = priorityList.find(priorityFormat => logo.formats.some(({ format }) => format === priorityFormat) ) ``` ## API Reference For more details, refer to our [API Reference](/reference/brand-api). # Setup a webhook and subscribe to brand updates Source: https://docs.brandfetch.com/guides/subscribe-to-webhook-updates A quick walk through on how to fetch a brand and subscribe to receive updates using webhooks. ## Setting up APIs ```JavaScript JavaScript theme={null} const BRANDFETCH_SECRET_API_KEY = "..." async function brandApi(domain) { const response = await fetch( `https://api.brandfetch.io/v2/brands/${domain}`, { method: 'GET', headers: { 'authorization': `Bearer ${BRANDFETCH_SECRET_API_KEY}` } } ) return response.json() } async function graphql(query, variables) { const response = await fetch( `https://graphql.brandfetch.io/`, { method: 'POST', headers: { 'authorization': `Bearer ${BRANDFETCH_SECRET_API_KEY}` } } ) return response.json() } ``` ## Create a Webhook Create a new webhook with the `createWebhook` mutation. You can subscribe to receive updates on multiple brands on a single webhook. ```JavaScript JavaScript theme={null} const webhookEndpointUrl = 'https://your-website.com/webhook' const { data: { createWebhook: { webhook } } } = await graphql(` mutation CreateWebhook($createInput: CreateWebhookInput!) { createWebhook(input: $createInput) { code message success webhook { urn } } } `, { createInput: { description: 'Brand updates', enabled: true, events: ['brand.updated'], url: webhookEndpointUrl } }) ``` ## Retrieve a brand We need to retrieve the brand to get it's URN (ID). Typically you'll have already made an initial request to fetched a brand — and now you want to continue to receive updates on it. ```JavaScript JavaScript theme={null} const brand = await brandApi('brandfetch.com') ``` ## Subscribe to brand updates To subscribe to a brand's data updates, we can use the `addWebhookSubscriptions` mutation to add the brand to the list of active subscriptions on the webhook. We can subscribe to one or more brands at once with this mutation by passing the each brand's URN in the `subscriptions` list variable. ```JavaScript JavaScript theme={null} await graphql(` mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) { code message success } } `, { webhookUrn: webhook.urn, subscriptions: [brand.urn] }) ``` ## Unsubscribe a subscription If we later wish to unsubscribe from a brand we can do so with the `removeWebhookSubscriptions` mutation. Like the `addWebhookSubscriptions` mutation, here we can remove multiple URNs at once by providing them as part of the `subscriptions` list variable. ```JavaScript JavaScript theme={null} await graphql(` mutation RemoveWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) removeWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) { code message success } } `, { webhookUrn: webhook.urn, subscriptions: [brand.urn] }) ``` # Logo API Usage Guidelines Source: https://docs.brandfetch.com/logo-api/guidelines Instantly add any company logos to your app or website Logo API is free to use and we don't ask for any attribution. ## Authentication **To use Logo API, you must include your client ID with every request.** Adding your client ID provides reliable access, supports fair usage, and keeps consistent performance across all requests. [Create a free account](https://developers.brandfetch.com/register) and access your client ID from the developer portal. Include your client ID in each request as shown in the example below: ```html theme={null} Logos by Brandfetch ``` ## Hotlinking **We require logo links to be directly embedded in your applications.** Embedding logo links directly within your HTML image tags guarantees that the logo remains up-to-date at all times. It also ensures a faster and more reliable implementation. When embedding a logo link, HTTP requests must include the `Referer` header with the request origin. Your HTTP `Referrer-Policy` header must be set to one of: `origin`, `origin-when-cross-origin`, `strict-origin`, `strict-origin-when-cross-origin` (browser default), or `unsafe-url`. Programmatic access to logo images is not permitted and may result in rate limiting or blocking. Scraping logos will also lead to a block. If your use case requires caching, please [contact us](https://brandfetch.com/developers/contact/sales) for a custom setup. ## Replicating Brandfetch **You cannot replicate the core user experience of Brandfetch.** The best way to ensure that your application doesn’t violate this guideline is by integrating Brandfetch into an existing app that offers more value than just the Brandfetch integration. Some examples: * ✅ The [Typeform integration](https://brandfetch.com/developers/customers/typeform) improves the user’s onboarding by presenting brand logos. Without this integration, the app still has a lot of value to its users. * ✅ The [Pitch integration](https://brandfetch.com/developers/customers/pitch) brings brand logos inside Pitch’s editor to streamline the creation of presentations. Without this integration, the app still has a lot of value to its users. * 🚫 A logo search that only returns logos from Logo API. Without the integration, the app has no content and no value to users. * 🚫 An unofficial Logo API that allows users to access brand logos via Logo API. Without the API, the app has no content and no value to users. If you're unsure about your use case, please [contact us](https://brandfetch.com/developers/contact). # Overview Source: https://docs.brandfetch.com/logo-api/overview Instantly add any company logos to your app or website [Logo API](https://brandfetch.com/developers/logo-api) is a simple CDN link that gives you access to any brand’s latest logos. It’s customizable with powerful transformation capabilities and is meant to be directly embedded in your HTML tags so the logo always remains up-to-date. ## Implementation guide The Logo API is a free product. Before you deploy your application to a live environment, be sure to consult our [rate limits](/logo-api/rate-limits) and review our [usage guidelines](/logo-api/guidelines) to ensure a smooth launch. To embed a logo, simply use an `img` tag with the following `src` attribute: ```html Auto-detection theme={null} Logo by Brandfetch ``` ```html Domain theme={null} Logo by Brandfetch ``` ```html Stock or ETF ticker theme={null} Logo by Brandfetch ``` ```html Crypto symbol theme={null} Logo by Brandfetch ``` ```html ISIN theme={null} Logo by Brandfetch ``` You can use explicit type routes (`domain/`, `ticker/`, `isin/`, `crypto/`) to avoid naming collisions. Without a type prefix, the API will auto-detect the identifier type (domain → ticker → isin → crypto). Logo API is free to use and we don't ask for any attribution. Each request must include your unique client ID. This ensures your usage stays within fair limits and logos render reliably. To get your client ID, register for free from our [Developer Portal](https://developers.brandfetch.com/register). Beyond simply swapping out the base URL, Brandfetch's Logo API offers powerful features to enhance your logo fetching experience: * **Logo types:** Access not just logo icons, but also brand symbols and main logos. * **Theme variants:** Access dark or light logos, display them on any background. * **Customizable sizing:** Adjust the logo’s height and width to fit your needs. * **Smart fallbacks:** Even when a logo isn’t available, you’ll get fallbacks. * **Search by Stock or ETF ticker:** Query directly by Stock or ETF ticker (e.g., `NKE`, `QQQ`). * **Search by ISIN**: Query directly by ISIN (e.g., `US6541061031`). * **Search by Crypto symbol:** Query directly by Crypto symbol (e.g., `BTC`, `ETH`). Explore these options in our Logo API [parameters page](/logo-api/parameters). *** ## Default icon Get the brand's default logo icon. ```html Domain theme={null} Logos by Brandfetch ``` ```html Stock or ETF ticker theme={null} Logos by Brandfetch ``` ```html Crypto symbol theme={null} Logos by Brandfetch ``` ### PNG or JPG instead of WEBP By default Logo API serves logos in the modern and highly efficient WebP format. You can use others formats by specifying the file extension in the URL. `logo`, `symbol` type variants support an additional `svg` format. ```html theme={null} Logos by Brandfetch ``` ### Logo sizing / Retina Customize the logo’s dimensions by adding `w` (width) and `h` (height) query parameters to the URL. The ratio of the logo is always respected. For Retina displays, double the size values for optimal display. e.g., for a 64x64 icon display, set `h=128` and `w=128`. ```html theme={null} Logos by Brandfetch ``` ### Type variants Request different types of logos by using the `type` path parameter. Available variants are: `icon`, `symbol`, and `logo`. ```html theme={null} Logos by Brandfetch ``` ### Dark and light themes Ensure the logo looks great regardless of the background color of your application. ```html theme={null} Logos by Brandfetch ``` ### Multiple fallbacks Specify a fallback option to be used when the a logo is not available. [See all fallbacks](/logo-api/parameters). ```html theme={null} Logos by Brandfetch ``` ## Explore more options Explore these options in our Logo API [parameters page](/logo-api/parameters). # Parameters Source: https://docs.brandfetch.com/logo-api/parameters Detailed reference of all Logo API parameters ## URL Structure The Logo API uses a structured URL format that allows you to customize logo retrieval through path and query parameters: #### Short version ```html Domain theme={null} Logo by Brandfetch ``` ```html Stock or ETF ticker theme={null} Logo by Brandfetch ``` ```html Crypto symbol theme={null} Logo by Brandfetch ``` #### Full version with all parameters ```html Domain theme={null} Logo by Brandfetch ``` ```html Stock or ETF ticker theme={null} Logo by Brandfetch ``` ```html Crypto symbol theme={null} Logo by Brandfetch ``` To use Logo API, you must include your client ID with every request. To get your client ID, register for free from our [Developer Portal](https://developers.brandfetch.com/register). *** ## identifier **Type:** `string` **Required** Identifier to retrieve brand assets. Accepted formats: * **Domain:** `nike.com` * **Brand ID:** `id_0dwKPKT` * **ISIN:** `US6541061031` * **Stock or ETF ticker:** `NKE` * **Crypto symbol:** `BTC`, `ETH` (uppercase preferred) To avoid potential naming collisions between identifier types, you can use explicit type routes with the pattern `{type}/{identifier}`: * `domain/nike.com` - Query by domain name * `ticker/NKE` - Query by Stock or ETF ticker * `isin/US6541061031` - Query by ISIN code * `crypto/BTC` - Query by Crypto symbol **Examples:** ```html Auto-detection theme={null} Logo by Brandfetch ``` ```html Domain theme={null} Logo by Brandfetch ``` ```html Stock or ETF ticker theme={null} Logo by Brandfetch ``` ```html ISIN theme={null} Logo by Brandfetch ``` ```html Crypto symbol theme={null} Logo by Brandfetch ``` If you omit the type prefix (e.g., `nike.com` instead of `domain/nike.com`), the API will auto-detect the identifier type. The detection order is: Domain → Stock or ETF ticker → ISIN → Crypto symbol. However, **we recommend using explicit type routes** to prevent collisions and ensure accurate results. ## theme **Type:** `enum` * `light` — The light version of the logo * `dark` — The dark version of the logo ## fallback **Type:** `enum` * `brandfetch` — The Brandfetch logo * `transparent` — A see-through placeholder for custom background options * `lettermark` — A square icon featuring the first letter of the brand's name (applies only to type=icon) * `404` — HTTP status 404 and a see-through placeholder for custom background options **Default:** Varies by type * `brandfetch` for `icon` * `transparent` for `logo` and `symbol` ## h **Type:** `number` Height of the logo. The ratio of the logo is always respected. ## w **Type:** `number` Width of the logo. The ratio of the logo is always respected. ## type **Type:** `enum` * `icon` — (default) The icon used on social profiles (e.g., Tesla's social icon) * `logo` — The horizontal logo, usually seen on large surfaces (e.g., Tesla's logo) * `symbol` — The universal mark that abstractly represents the brand (e.g., Tesla's T symbol) # Rate limits Source: https://docs.brandfetch.com/logo-api/rate-limits We offer a fair use rate limit of 500,000 requests per month, which is designed to cover most small to medium applications. This is a soft limit and you won't immediately be blocked if you exceed it. If your usage approaches this limit, we’ll send you a friendly heads-up so you can adjust your usage or explore an upgrade to an unlimited tier. To maintain platform reliability, request throughput limits also apply: * 1,000 requests every 5 minutes per IP * 2,400 requests every 5 minutes per customer Exceeding these throughput limits returns an HTTP 429 status code. Let us know if your application requires higher throughput. For enterprises, we provide custom solutions, including SLA agreements, custom terms, and flexible caching options to ensure optimal performance at scale. These plans are tailored to meet the needs of high-volume users. Feel free to [contact us](https://brandfetch.com/developers/contact/sales) to discuss the right plan for your use case. # Migrating from Clearbit to Brandfetch Logo API Source: https://docs.brandfetch.com/migrations/migrate-from-clearbit-logo-api Complete guide to replacing Clearbit's deprecated Logo API with Brandfetch Clearbit's Logo API will shut down on December 1, 2025. Brandfetch Logo API is the ideal future-proof replacement for modern startups and large enterprises. Clearbit's once-popular Logo API is shutting down, leaving many developers searching for a Clearbit logo alternative that offers reliable, up-to-date logos. If your code currently relies on `https://logo.clearbit.com/:domain` to fetch brand logos, your app might stop rendering logos soon. This guide provides a comprehensive overview of migrating to a new Logo API solution. We'll explain why you should consider migrating, and walk through the migration process (using Brandfetch's Logo API as an example) with code samples and best practices. By the end, you'll have a clear path to replace Clearbit's Logo API with a robust alternative. ## Why Brandfetch? Clearbit's Logo API service is being deprecated – it's not maintained and is **scheduled to terminate at the end on December 1, 2025**. This means existing integrations will eventually stop working. To keep your product's UI displaying company logos, migrating to a new Logo API is a must. Fortunately, several alternatives have emerged. Logo API from Brandfetch is a strong choice, it's reliable with a 100% uptime, it's trusted in production by Canva, Typeform and Experian, and has the most generous free tier with up-to 500,000 requests/month making it the no-brainer alternative solution. ## Migration guide Below is a simplified pathway for migrating from Clearbit's Logo API to Brandfetch as your primary logo API. Brandfetch is designed as a drop-in replacement for Clearbit's Logo API. The migration primarily involves updating the base URL in your existing requests. ```text Clearbit Base URL theme={null} https://logo.clearbit.com/ ``` ```text Brandfetch Base URL theme={null} https://cdn.brandfetch.io/ ``` Beyond simply swapping out the base URL, Brandfetch's Logo API offers powerful features to enhance your logo fetching experience: * **Logo types:** Access not just logo icons, but also brand symbols and main logos. * **Theme variants:** Access dark or light logos, display them on any background. * **Customizable sizing:** Adjust the logo’s height and width to fit your needs. * **Smart fallbacks:** Even when a logo isn’t available, you’ll get fallbacks. * **Search by Stock or ETF ticker, Crypto symbol:** Query directly by Stock/ETF ticker, or Crypto symbol (e.g., `NKE`, `QQQ`, `BTC`). * **Search by ISIN**: Query directly by ISIN (e.g., `US6541061031`). To make the most of your logo integrations, explore these options in our [Logo API](/logo-api/overview). Each request must include your unique client ID. This ensures your usage stays within fair limits and logos render reliably. ```text Brandfetch Base URL theme={null} https://cdn.brandfetch.io/:domain?c=BRANDFETCH_CLIENT_ID ``` To get your client ID, register for free from our [Developer Portal](https://developers.brandfetch.com/register). ## Pricing, Attribution & Rate Limits Logo API is free with 500,000 requests/mo and you don't need to display an attribution link—simply include your client ID in every request. If you anticipate heavy usage, [contact sales](https://brandfetch.com/developers/contact/sales) to explore enterprise packages including custom caching rules, SLAs, and flexible legal terms. ## Conclusion [Brandfetch Logo API](https://brandfetch.com/developers/logo-api) is the replacement for modern startups and large enterprise with reliable maintenance, and a far richer dataset for those who want to expand beyond simple logos. Get started today by signing up for a free account on our [Developer Portal](https://developers.brandfetch.com/register). # Brand API Source: https://docs.brandfetch.com/reference/brand-api GET /v2/brands/{identifier} Get brand data using a Domain, Brand ID, ISIN, Stock/ETF ticker, or Crypto symbol. This endpoint supports auto-detection of the identifier type. To prevent issues with naming collisions, we recommend using one the explicit type routes: * [by Domain API](/reference/brand-api-domain) - `/v2/brands/domain/{domain}` * [by Stock or ETF API](/reference/brand-api-ticker) - `/v2/brands/ticker/{ticker}` * [by ISIN API](/reference/brand-api-isin) - `/v2/brands/isin/{isin}` * [by Crypto API](/reference/brand-api-crypto) - `/v2/brands/crypto/{symbol}` # Brand API - Crypto symbol Source: https://docs.brandfetch.com/reference/brand-api-crypto GET /v2/brands/crypto/{symbol} Get brand data using a crypto symbol. # Brand Data - Domain name Source: https://docs.brandfetch.com/reference/brand-api-domain GET /v2/brands/domain/{domain} Get brand data using a domain name identifier. # Brand API - ISIN Source: https://docs.brandfetch.com/reference/brand-api-isin GET /v2/brands/isin/{isin} Get brand data using an ISIN code. # Brand API - Stock or ETF ticker Source: https://docs.brandfetch.com/reference/brand-api-ticker GET /v2/brands/ticker/{ticker} Get brand data using a Stock or ETF ticker. # Brand Search API Source: https://docs.brandfetch.com/reference/brand-search-api GET /v2/search/{name}?c={clientId} Search for brands by name, login to get a clientId Read our [guidelines](/brand-search-api/guidelines) before using the Brand Search API. # Transaction API Source: https://docs.brandfetch.com/reference/transaction-api POST /v2/brands/transaction Turn payment transactions into merchant data. # Getting help Source: https://docs.brandfetch.com/support/getting-help Our support team is always available and willing to assist you. ## Technical Support If you come across any questions or encounter any issues, do not hesitate to [contact us](https://brandfetch.com/developers/contact). To help us quickly identify and fix the issue, kindly provide us with the following details: * The email address of your account. * The URL of the call you were making when the error occurred. * The brand you were accessing. * The status error you were facing. ## Contact sales If you want to ask for new features, buy additional API requests, unlock premium endpoints, or gain insights on how to make the most out of the API, [contact sales](https://brandfetch.com/developers/contact/sales) with us! # Report inaccuracies Source: https://docs.brandfetch.com/support/report-inaccuracies Report incorrect or missing brand info. We run an internal QA process to keep our brand library accurate and complete. If you spot missing or incorrect information in our index, you can let us know through [this form](https://brandfetch.com/update?mode=dev). Every submission is manually reviewed and, if verified, the update will be reflected in our index within 1-7 days, and we'll notify you once it's live. # Security & SOC2 Source: https://docs.brandfetch.com/support/security-soc2 Our commitment to secure data handling and best-in-class practices. We are committed to building a secure and trustworthy platform. As part of that commitment, we are on track to achieve our SOC2 certification by Q1 2026. ## Overview Given that our platform exclusively handles public data and our API does not process any PII or sensitive customer information, we have not prioritized SOC2 certification at this time. However, our enterprise customers, including leading multinational banks, continue to trust and work with us, recognizing the security context of our public-data model and our SOC2–compliant handling of internal systems and infrastructure. ### User Data & PII * **Minimal PII Storage**: Brandfetch does not collect or store Personally Identifiable Information (PII) beyond login email addresses for passwordless authentication. * **Logging**: We retain logs for up to 90 days for operational purposes. These may include IP addresses and User-Agent strings, which typically reflect server infrastructure rather than individual users. ### API Data Handling * **Public Data Only**: The Brandfetch API strictly processes publicly available data tied to domain names. It does not access, store, or interact with any private or customer-owned data. * **Data Processing Workflow**: Our API indexes, processes, and enhances publicly available brand data, making it accessible for our customers. At no point does the API interact with private data. ### Security Measures * **Data Encryption**: We utilize AES-256 encryption for data at-rest and TLS for data in-transit, ensuring end-to-end security. * **Secure Infrastructure**: Our development, staging, and production environments are hosted on Amazon Web Services (AWS), which offers secure, resilient hosting with 24x7 security and compliance certifications. * **Best Development Practices**: Our software development lifecycle adheres to OWASP best practices, incorporating human review processes enhanced by AI to maintain high quality standards. ## Contact sales Have questions about security, want to discuss enterprise usage, or need help optimizing your API integration?\ [Contact sales](https://brandfetch.com/developers/contact/sales) with our team to get started. # Service status Source: https://docs.brandfetch.com/support/service-status Check the status of Brandfetch services. For real-time updates and incident reports, please visit our [status page](https://status.brandfetch.io). If you're experiencing issues not reflected in our [status page](https://status.brandfetch.io), please don't hesitate to contact our support team. Get in touch with our support team for assistance # Terms and Conditions Source: https://docs.brandfetch.com/support/terms-and-conditions You can view our complete [Terms and Conditions](https://brandfetch.com/terms?mode=dev) for all the details. If you have specific legal questions about them, don't hesitate to reach out to our team Get in touch with our sales team for assistance # Overview Source: https://docs.brandfetch.com/transaction-api/overview Turn payment transactions into merchant data. Requests to the Transaction API count against your Brand API usage quotas. The Transaction API identifies merchant brands from raw transaction data in a single call. It processes unstructured payment text, maps it to a domain, and returns brand details (e.g., name, logo, domain, industry, etc). For more details, refer to our [API Reference](/reference/transaction-api). Transaction API works in real-time to recognize merchants worldwide. If a brand is not part of our dataset, it will index the information live, providing data for brands of every size, geography, or sector. ## Implementation guide For more details, refer to our [API Reference](/reference/brand-api). You’ll need to create an account on our [Developer Portal](https://developers.brandfetch.com/register). Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your API key. Implement or run the code below to make your first API request. ```curl curl theme={null} curl --request POST \ --url https://api.brandfetch.io/v2/brands/transaction \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "transactionLabel": "STARBUCKS 1523 OMAHA NE", "countryCode": "US" }' ``` Authentication is done by passing your API key as a [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). The Transaction API can be accessed through the following structure: All requests for the domain brandfetch.com are free and will not count towards your usage/quotas. You can make as many requests to the Brandfetch’s brand as you need while you iterate on and test your integration. Once you are ready to go live, simply replace brandfetch.com with the domain name, Stock/ETF ticker, ISIN or Crypto symbol you want to look up. ## Transaction input The primary input for querying the Transaction API is a raw transaction descriptor (the line-item text on a bank or credit card statement). You provide this as the `transactionLabel` in the request body, along with a `countryCode` to narrow down the merchant’s locale. For example, a transaction label like `"STARBUCKS 1523 OMAHA NE"` with country code `"US"` can be resolved to starbucks.com. ## API Reference For more details, refer to our [API Reference](/reference/transaction-api). # Best practices Source: https://docs.brandfetch.com/webhooks/best-practices Review these best practices to make sure your webhooks remain secure and function well with your integration. Webhooks are available to [Entreprise](https://brandfetch.com/developers/pricing) customers, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). ## Handle duplicate events Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events. Each event payload includes an event URN—a unique identifier for the event—which can be used as an idempotency key. ## Only listen to event types your integration requires Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it. You can change the events that a webhook endpoint receives by updating the webhook object using the `updateWebhook` [mutation](/guides/access-graphql-api). ## Handle events asynchrounously The volume of events that get generated can be spike-y. A data enrichment may result in millions of objects being updated in a very short period of time. Configure your handler to process incoming events with an asynchronous queue. You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, during a large data enrichment) might overwhelm your endpoint hosts. Asynchronous queues allow you to process the concurrent events at a rate your system can support. For example, your webhook endpoint could simply verify a payload and then push the event directly to a queue (like AWS SQS) where you can then process the events with better concurrency control. ## Receive events with an HTTPS server You must use an HTTPS URL for your webhook endpoint. Brandfetch validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate. ## Verify events are sent from Brandfetch Verify webhook signatures to confirm that received events are sent from Brandfetch. Brandfetch signs webhook payload sent to your endpoints by including a signature in each event’s `Webhook-Signature` header. This allows you to verify that the events were sent by Brandfetch, not by a third party. ## Preventing replay attacks A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Brandfetch includes a timestamp in the `Webhook-Signature` header. Because this timestamp is part of the signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload. We recommend a tolerance of no greater than 5 minutes between the timestamp and the current time. Use Network Time Protocol (NTP) to make sure that your server’s clock is accurate and is in-sync with the time on Brandfetch’s servers. Brandfetch generates the timestamp and signature each time we send an event to your endpoint. If Brandfetch retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt. ## Example code for handling signature and timing verification ```javascript JavaScript theme={null} import crypto from "node:crypto"; const TIMESTAMP_TOLERANCE_IN_MILISECONDS = 2 * 60 * 1000; // 2 minutes function hasVerifiedPayload({ sharedWebhookSecret, headers, rawRequestBody }) { const webhookId = headers["webhook-id"]; const signature = headers["webhook-signature"].split(",")[1]; const timestamp = Number(headers["webhook-timestamp"]); const signatureAlgorithm = headers["webhook-signature-algorithm"]; const now = Date.now(); const signatureIsOk = crypto .createHmac(signatureAlgorithm, sharedWebhookSecret) .update(`${webhookId}.${timestamp}.${rawRequestBody}`) .digest("hex") === signature; const timingIsOk = timestamp < now && timestamp > now - TIMESTAMP_TOLERANCE_IN_MILISECONDS; return signatureIsOk && timingIsOk; } ``` ## Quickly return a 2xx response Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout. For example, you must return a 200 response before updating any records in your database or making additional API requests. # Delivery behaviors Source: https://docs.brandfetch.com/webhooks/delivery-behaviors This section helps you understand different behaviors to expect regarding how Brandfetch sends events to your webhook endpoint. Webhooks are available to [Entreprise](https://brandfetch.com/developers/pricing) customers, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). ## Retry behavior Brandfetch attempts to deliver a given event to your webhook endpoint for up to 3 days with an exponential back off. If your endpoint has been disabled or deleted when Brandfetch attempts a retry, future retries of that event are prevented. However, if you disable and then re-enable a webhook endpoint before Brandfetch can retry, you can still expect to see future retry attempts. ## Disable behavior Brandfetch attempts to notify you of a mis-configured endpoint by email if the endpoint hasn’t responded with a 2xx HTTP status code for multiple days in a row. The email also states when the endpoint will be automatically disabled. ## Event ordering While events are usually in order, your integration should not depend on it. Brandfetch doesn’t guarantee delivery of events in the order in which they’re generated. For example, re-indexing a brand might generate the following events: * `brand.company.updated` * `brand.updated` Your endpoint shouldn’t expect delivery of these events in this order, and needs to handle delivery accordingly. You can also use the API to fetch any missing objects (for example, you can fetch the current brand information from `brand.company.updated` if you happen to receive this event first). # Event types Source: https://docs.brandfetch.com/webhooks/event-types Overview of subscribable event types Webhooks are available to [Entreprise](https://brandfetch.com/developers/pricing) customers, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). The following table lists the type of events which can be subscribed to. There are additional events not shown in this table—if you have a custom need for an additional event, please reach out to us. * **Event type**: `brand.claimed`
**Namespace**: `brand`
**Scope**: `urn:brandfetch:brand:`
**Description**: Triggered when a brand is claimed by the brand owner. * **Event type**: `brand.deleted`
**Namespace**: `brand`
**Scope**: `urn:brandfetch:brand:`
**Description**: Triggered when a brand is soft-deleted. This is exceedingly rare and usually related to a take-down request by the brand's owner. * **Event type**: `brand.updated`
**Namespace**: `brand`
**Scope**: `urn:brandfetch:brand:`
**Description**: Triggered anytime a brand's data is updated. * **Event type**: `brand.company.updated`
**Namespace**: `brand`
**Scope**: `urn:brandfetch:brand:`
**Description**: Triggered anytime a brand's company data is updated. * **Event type**: `brand.verified`
**Namespace**: `brand`
**Scope**: `urn:brandfetch:brand:`
**Description**: Triggered when a brand's data is human-reviewed (by our curation team). # Overview Source: https://docs.brandfetch.com/webhooks/overview Get notified of changes by receiving events at your webhook URL. Webhooks are available to [Entreprise](https://brandfetch.com/developers/pricing) customers, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). ## Why use webhooks When building Brandfetch integrations, you might want your applications to receive events as they occur for brands you're interested in, so that your backend systems can execute actions accordingly. To enable webhook events, you need to [register webhook endpoints](/webhooks/setup#register-your-endpoint). After you register them, Brandfetch can push real-time event data to your application’s webhook endpoint when things happen. Brandfetch uses HTTPS to send webhook payloads to your app as a JSON payload that includes an Event object. The implementation follows the v1 of the [Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) specification. Receiving webhook events is particularly useful for listening to asynchronous events such as when a brand’s logo changes, a company detail is updated, or when we index new data. ## Event overview Brandfetch implements version 1.0.0 of [the Standard Webhooks](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) specification. Brandfetch generates event data that we can send you to inform you of brand activity. When an event occurs, Brandfetch generates a new event object. A single API request might result in the creation of multiple events. For example, if we re-index a brand, you may receive `brand.company.updated` and `brand.updated` events. By registering webhook endpoints with Brandfetch, you enable us to automatically send event payloads as part of POST requests to the registered webhook endpoint hosted by your application. After your webhook endpoint receives the event payload, your app can run backend actions (for example, updating your database after you receive a `brand.updated` event). ### Event payload The event object we send to your webhook endpoint provides a snapshot of the object that changed. They might include a `delta` property that indicates the change, when applicable. See the full [list of event types](/webhooks/event-types) that we can send to your webhook. ### Example event payload The following event shows a subscription update at the end of a trial. ```JSON JSON theme={null} { "type": "brand.updated", "timestamp": "2024-01-01T00:00:00.000000Z", "urn": "urn:brandfetch:organization:0123:webhook:1234:event:2345", "data": { "object": { "__typename": "Brand", "id": "id123456", "domain": "brandfetch.com", "verified": true, ... }, "delta": { "verified": { "old": false, "new": true } } } } ``` ```TypeScript TypeScript theme={null} interface WebhookEventPayload { readonly type: string; readonly timestamp: string; readonly urn: string; readonly data: { readonly object: Record; readonly delta: Record; }; } ``` ### Event type You receive events for all of the event types your webhook endpoint is listening for in your configuration. Use the received event type to determine what processing your application needs to perform. The `data.object` corresponding to each event type varies, but typically will be the namespace object (e.g. a Brand given brand.updated where `brand.*` is the event namespace.) ### Data object and previous attributes delta Event payloads may include a `data.delta` property which will indicate which fields changed. For `*.updated` events, the event payload always includes the `data.delta` property which will allow you to inspect what’s been updated on the object. The delta attributes in the example `brand.updated` event above indicates that the brand has a previous value of `verified: false`. The `data.object` property shows that the verified field has been set to `true` which indicates that the brand has been `verified` by Brandfetch's curation team. # Setup a webhook Source: https://docs.brandfetch.com/webhooks/setup Start receiving event payloads Webhooks are available to [Entreprise](https://brandfetch.com/developers/pricing) customers, if you're interested [contact us](https://brandfetch.com/developers/contact/sales). ## Summary To start receiving webhook events in your integration, create and register a webhook endpoint by following the steps below: 1. Create a webhook endpoint handler to receive event data POST requests. 2. Register your endpoint with Brandfetch via an API request. 3. Secure your webhook endpoint. You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events. [Setup a webhook and subscribe to brand updates](/guides/subscribe-to-webhook-updates) ## Create a handler See the [events reference](/webhooks/event-types) to identify the event types your webhook handler needs to process. Set an HTTPS endpoint function that can accept webhook requests with a POST method. Set up your endpoint function so that it: 1. Handles POST requests with a JSON payload consisting of an event object. 2. Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout. ### Example endpoint This code snippet is a webhook function configured to check that the event type was received, to handle the event, and return a 200 response. Example code for `hasVerifiedPayload()` is available [here](/webhooks/best-practices#example-code-for-handling-signature-and-timing-verification). ```javascript theme={null} const express = require("express"); const app = express(); // Verify the signature by comparing the signature // provided in the signature header with one we // compute ourselves with the shared secret. // If the signatures don't match, we return an error function verifyWebhook(request, response, rawBodyBuffer, encoding) { if (!rawBodyBuffer || !rawBodyBuffer.length) { return response.status(400).json({ message: "Request body missing" }); } const payload = rawBodyBuffer.toString(encoding || "utf8"); const headers = request.headers; if ( !hasVerifiedPayload({ sharedWebhookSecret: process.env.SHARED_WEBHOOK_SECRET, headers, rawRequestBody: payload, }) ) { return response.status(400).json({ message: "Signature does not match.", }); } } app.post( "/webhook", express.json({ type: "application/json", verify: verifyWebhook }), (request, response) => { const event = request.body; switch (event.type) { case "brand.updated": const brand = event.data.brand; const changes = event.data.delta; // Then define and call a method to handle the brand updated event. handleBrandUpdated(brand, changes); break; case "brand.verified": const brand = event.data.brand; // Then define and call a method to handle the brand verified event. handleBrandVerified(brand); break; // ... handle other event types default: console.log(`Unhandled event type ${event.type}`); } // Return a response to acknowledge receipt of the event response.json({ received: true }); } ); app.listen(8000, () => console.log("Running on port 8000")); ``` ## Register your endpoint Once your handler is deployed on the web and ready to go, register your endpoint with Brandfetch by creating a webhook using the GraphQL APIs `createWebhook` [mutation](/guides/access-graphql-api). Registered webhook endpoint URLs must be publicly accessible HTTPS URLs. ```cURL cURL theme={null} curl --request POST \ --header 'content-type: application/json' \ --header 'authorization: Bearer YOUR_API_KEY_HERE' \ --url 'https://graphql.brandfetch.io' \ --data '{"query":"mutation CreateWebhook($input: CreateWebhookInput!) {\n createWebhook(input: $input) {\n code\n message\n success\n webhook {\n urn\n enabled\n }\n }\n}","variables":{"input":{"description":"My new Webhoook","events":["brand.updated","brand.verified"],"url":"https://httpbin.org/status/200"}}}' ``` ```GraphQL GraphQL theme={null} mutation CreateWebhook($input: CreateWebhookInput!) { createWebhook(input: $input) { code message success webhook { urn } } } # Example Variables: { "input": { "description": "Get updates when a brand's logo changes", "events": ["brand.updated"], "url": "https://httpbin.org/status/200"}} ``` ## Subscribe to objects using their URNs The final step is to subscribe to the objects (like brands) for which you want to receive events. You can subscribe to a few objects, or many thousands—one at a time, or in batches. For example, perhaps you want to receive events for the Brandfetch brand. The URN for this brand is `urn:brandfetch:brand:idL0iThUh6which` means we would subscribe to that URN. To add a subscription we need two things: The URN for the webhook we created (`$webhookUrn: URN!`) and the URN for the object to which we want to subscribe to (`$subscriptions: [URN!]!`). ```cURL cURL theme={null} curl --request POST \ --header 'content-type: application/json' \ --header 'authorization: Bearer YOUR_API_KEY_HERE' \ --url 'https://graphql.brandfetch.io' \ --data '{"query":"mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) {\n addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) {\n code\n message\n success\n webhook {\n urn\n }\n }\n}","variables":{"webhookUrn":"urn:brandfetch:organization:1234:webhook:5678","subscriptions":["urn:brandfetch:brand:idL0iThUh6"]}}' ``` ```GraphQL GraphQL theme={null} mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) { addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) { code message success webhook { urn } } } # Example Variables: { "webhookUrn": "urn:brandfetch:organization:1234:webhook:1234", "subscriptions": ["urn:brandfetch:brand:id123456"] } ``` ## Debugging delivery issues To help debug your endpoint, or to later retrieve failed event deliveries when your endpoint has a long duration outage, you can review all of the events Brandfetch attempted to deliver to your webhook endpoint using the GraphQL API. Performing the following GraphQL query on the Webhooks API will return a list of all attempted webhook deliveries, responses from your endpoint, and the respective HTTP status codes we received. Delivery history is kept for 30 days after which time it is irreversibly deleted. ```cURL cURL theme={null} curl --request POST \ --header 'content-type: application/json' \ --header 'authorization: Bearer YOUR_API_KEY_HERE' \ --url 'https://graphql.brandfetch.io' \ --data '{"query":"query RetrieveWebhookDeliveries($webhookUrn: URN!) {\n webhook(urn: $webhookUrn) {\n url\n urn\n description\n enabled\n deliveries {\n totalCount\n edges {\n node {\n createdAt\n deliveredAt\n status\n result {\n body\n headers {\n name\n value\n }\n message\n statusCode\n }\n }\n }\n }\n }\n}","variables":{"webhookUrn":"urn:brandfetch:organization:1234:webhook:1234"}}' ``` ```GraphQL GraphQL theme={null} query RetrieveWebhookDeliveries($webhookUrn: URN!) { webhook(webhook: $webhookUrn) { url urn description enabled deliveries { totalCount edges { node { createdAt deliveredAt status result { body headers { name value } message statusCode } } } } } } # Example Variables: { "webhookUrn": "urn:brandfetch:organization:1234:webhook:1234" } ```