### Getting Started with Brandfetch APIs Source: https://docs.brandfetch.com/docs/getting-started Brandfetch APIs are designed for easy integration, with most teams completing setup within 30 minutes. They are trusted by companies of all sizes. ```APIDOC Getting Started: - Easy integration - Setup typically within 30 minutes - Trusted by startups to Fortune 500 companies ``` -------------------------------- ### Brandfetch API Integration Guide Source: https://docs.brandfetch.com/docs/index Brandfetch APIs are designed for easy integration, typically completed within 30 minutes. They are trusted by companies of all sizes and follow a RESTful model with SSL security. Responses and errors are returned in JSON format. ```APIDOC Brandfetch REST API: - Uses SSL for all requests. - Responses and errors are returned in JSON format. Products: - Logo Link: Embed brand logos for free. - Brand API: Provides data for B2B personalization. - Brand Search API: Autocomplete brand names for free. - Transaction API: Converts payment transactions into merchant data. ``` -------------------------------- ### Node.js Express Webhook Handler Source: https://docs.brandfetch.com/docs/webhooks/setup An example of a Node.js Express application that sets up a webhook endpoint to receive and process event data from Brandfetch. It includes signature verification and handles different event types like 'brand.updated' and 'brand.verified'. ```JavaScript 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")); ``` -------------------------------- ### Brandfetch GraphQL API - Create Webhook Source: https://docs.brandfetch.com/docs/webhooks/setup This section provides a cURL command to register a new webhook endpoint with Brandfetch using the GraphQL API. It demonstrates the `createWebhook` mutation, including required parameters like description, event types, and the webhook URL. ```cURL 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 mutation CreateWebhook($input: CreateWebhookInput!) { createWebhook(input: $input) { code message success webhook { urn enabled } } } ``` -------------------------------- ### Brand API Test Request Source: https://docs.brandfetch.com/docs/brand-api Provides an example of a GET request to the Brand API for testing purposes, targeting 'brandfetch.com'. ```APIDOC curl --request GET \ --url https://api.brandfetch.io/v2/brands/brandfetch.com \ --header 'Authorization: Bearer ' ``` -------------------------------- ### Subscribe to Brandfetch Objects via GraphQL Source: https://docs.brandfetch.com/docs/webhooks/setup This snippet demonstrates how to subscribe to Brandfetch objects, such as brands, using their URNs. It requires a webhook URN and a list of object URNs to subscribe to. The mutation returns a status code, message, success status, and the webhook URN. ```cURL 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"]}}' ``` ```APIDOC mutation AddWebhookSubscriptions($webhookUrn: URN!, $subscriptions: [URN!]!) { addWebhookSubscriptions(webhook: $webhookUrn, subscriptions: $subscriptions) { code message success webhook { urn } } } Parameters: webhookUrn: URN! - The URN for the webhook. subscriptions: [URN!]! - A list of URNs for the objects to subscribe to. Returns: code: Int - The status code of the operation. message: String - A message indicating the result of the operation. success: Boolean - True if the operation was successful, false otherwise. webhook: Webhook - Information about the webhook, including its URN. ``` -------------------------------- ### Webhooks Overview Source: https://docs.brandfetch.com/docs/getting-started This section covers the setup, delivery behaviors, and best practices for using Brandfetch webhooks, including a list of available event types. ```APIDOC Webhooks: - Overview - Setup guide - Delivery behaviors - Best practices - Event types ``` -------------------------------- ### Webhook Signature Verification Example Source: https://docs.brandfetch.com/docs/webhooks/best-practices Provides an example of how to verify webhook signatures and timestamps to ensure event authenticity and prevent replay attacks. ```APIDOC Webhook-Signature Header: Contains the signature and timestamp for the webhook payload. Format: t=,s= Verification Steps: 1. Retrieve the signature and timestamp from the 'Webhook-Signature' header. 2. Reconstruct the payload that was signed (typically the raw request body). 3. Compute the expected signature using your webhook secret and the reconstructed payload. 4. Compare the computed signature with the signature from the header. 5. Verify the timestamp: Ensure the timestamp is within an acceptable tolerance (e.g., 5 minutes) of the current time. 6. If both signature and timestamp are valid, process the event. Otherwise, reject the event. ``` -------------------------------- ### Brand Search API Reference Source: https://docs.brandfetch.com/docs/brand-search-api Provides access to the complete API reference documentation for the Brand Search API, offering detailed information and examples for all available endpoints and functionalities. ```APIDOC Brand Search API Reference: Overview: The 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. Guidelines: Rate Limit: - Base rate limit: 500,000 requests per month. - Per IP address limit: 200 requests per 5 minutes. - Recommended strategy: Use debounce between keystrokes. - Contact for upgrades or custom solutions for high-volume usage. Authentication: - Every request must include your unique `clientID`. - Obtain `clientID` from the developer portal after registration. - Include `clientId` in each request for reliable access and consistent performance. Hotlinking: - API must be directly embedded in user-facing applications. - Data fetched live, not altered or persisted. - Logo image URLs must be hotlinked. - Other data (brand names) should not be cached. - Image URLs expire after 24 hours and must be refetched. - Custom SLAs available for enterprise customers. Replicating Brandfetch: - Cannot replicate the core user experience of Brandfetch. - Integrate Brandfetch into existing apps that offer more value. - Example: Pitch integration for logo search within their editor. - Avoid creating unofficial Brand Search APIs without additional value. - Contact for clarification on use cases. React Integration: - Example available on CodeSandbox for seamless integration with React. Note: - Logos are the property of their respective trademark owners. - Logo usage must comply with "fair use" principles (referencing a brand without endorsement, misrepresentation, or alteration). - Consult a legal professional if unsure about usage. ``` -------------------------------- ### Retrieve Brandfetch Webhook Delivery History via GraphQL Source: https://docs.brandfetch.com/docs/webhooks/setup This snippet shows how to retrieve the delivery history for a specific webhook. It allows debugging delivery issues by providing details of attempted deliveries, responses from the endpoint, and HTTP status codes. Delivery history is retained for 30 days. ```cURL 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"}}' ``` ```APIDOC query RetrieveWebhookDeliveries($webhookUrn: URN!) { webhook(urn: $webhookUrn) { url urn description enabled deliveries { totalCount edges { node { createdAt deliveredAt status result { body headers { name value } message statusCode } } } } } } Parameters: webhookUrn: URN! - The URN of the webhook to retrieve delivery history for. Returns: webhook: Webhook - Information about the webhook, including its URL, URN, description, enabled status, and delivery history. url: String - The URL of the webhook endpoint. urn: String - The URN of the webhook. description: String - A description of the webhook. enabled: Boolean - Whether the webhook is enabled. deliveries: DeliveryConnection - A connection object for webhook deliveries. totalCount: Int - The total number of deliveries. edges: [DeliveryEdge!] - A list of delivery edges. node: Delivery - Information about a single delivery attempt. createdAt: String - The timestamp when the delivery was created. deliveredAt: String - The timestamp when the delivery was attempted. status: String - The status of the delivery attempt. result: DeliveryResult - The result of the delivery attempt. body: String - The response body from the endpoint. headers: [NameValuePair!] - A list of response headers. name: String - The header name. value: String - The header value. message: String - A message associated with the delivery result. statusCode: Int - The HTTP status code received from the endpoint. ``` -------------------------------- ### Brandfetch Webhook Event Payload Example Source: https://docs.brandfetch.com/docs/webhooks This example demonstrates the structure of a webhook event payload sent by Brandfetch, specifically for a brand update event. It includes the event type, timestamp, URN, and the data object with a delta indicating changes. ```json { "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 { "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 } } } } ``` -------------------------------- ### Brandfetch Webhook Event Payload Example Source: https://docs.brandfetch.com/docs/webhooks/overview This example demonstrates the structure of a webhook event payload sent by Brandfetch, specifically for a brand update event. It includes the event type, timestamp, URN, and the data object with a delta indicating changes. ```json { "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 { "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 } } } } ``` -------------------------------- ### Brand Search API Authentication Example Source: https://docs.brandfetch.com/docs/brand-search-api Demonstrates how to authenticate requests to the Brand Search API by including a unique clientID. This is crucial for reliable access and consistent performance. ```curl curl --request GET \ --url "https://api.brandfetch.io/v2/search/{query}?c={your-client-id-here}" ``` -------------------------------- ### Brandfetch Products Source: https://docs.brandfetch.com/docs/getting-started Brandfetch offers several APIs: Logo Link for free logo embedding, Brand API for B2B personalization data, Brand Search API for free brand name autocomplete, and Transaction API to convert payment transactions into merchant data. ```APIDOC Brandfetch Products: - Logo Link: Embed brand logos for free. - Brand API: Data for B2B personalization. - Brand Search API: Autocomplete brand names for free. - Transaction API: Convert payment transactions into merchant data. ``` -------------------------------- ### Brandfetch API Overview Source: https://docs.brandfetch.com/docs/getting-started Brandfetch APIs operate on a REST model for simple integration. All requests should use SSL, and responses/errors are returned in JSON format. ```APIDOC Brandfetch APIs: - RESTful model - Requires SSL for all requests - Responses and errors in JSON format ``` -------------------------------- ### Brand API Authentication Source: https://docs.brandfetch.com/docs/brand-api Demonstrates how to authenticate requests to the Brand API using a Bearer token. ```APIDOC Authorization: Bearer ``` -------------------------------- ### Embed Logo with Brandfetch Source: https://docs.brandfetch.com/docs/logo-link/guidelines Demonstrates how to embed a logo using Brandfetch's Logo Link service by including the domain and your client ID in the image source URL. ```HTML Logos by Brandfetch ``` -------------------------------- ### API Reference: Webhook Mutations Source: https://docs.brandfetch.com/docs/webhooks/best-practices This section details API mutations related to webhooks, specifically focusing on updating webhook configurations to manage received event types. ```APIDOC updateWebhook(webhookId: ID!, input: UpdateWebhookInput!): Webhook Updates an existing webhook. Arguments: webhookId: The ID of the webhook to update. input: The input object containing fields to update. clientMutationId: An identifier for the client. description: A description for the webhook. url: The URL for the webhook. secret: The secret used for signing webhook events. active: Whether the webhook is active. events: A list of event types the webhook should receive. Returns: The updated Webhook object. ``` -------------------------------- ### Brandfetch Logo Link API Endpoint Source: https://docs.brandfetch.com/docs/logo-link/parameters This snippet shows the structure of the Brandfetch Logo Link API endpoint, including path parameters for embedding logos. It details the required and optional parameters and their types. ```APIDOC Logo Link API Endpoint: .../{identifier}/{type}/theme/{theme}/fallback/{fallback}/h/{height}/w/{width}?c={your-clientId} Parameters: - identifier (string): Brand’s identifier (required). Options include domain, brandId, stock ticker, ISIN. - type (string): Logo’s type. Options: icon, logo, symbol. - theme (string): Logo’s theme. Options: light, dark. - fallback (string): Logo’s fallback. Options: brandfetch, transparent, lettermark, 404. - height (number): Logo’s height. Aspect ratio is always respected. - width (number): Logo’s width. Aspect ratio is always respected. - c (string): Your client ID (query parameter). Identifier Options: - domain: Domain name (FQDN) (e.g. nike.com). - brandId: Brand ID (e.g. id_0dwKPKT). - stock ticker: Abbreviation for publicly traded shares (e.g. NKE). - isin: International Securities Identification Number (ISIN) (e.g. US6541061031). Logo Type Options: - icon: Social profile icon (e.g. Tesla’s social icon). - logo: Horizontal logo for large surfaces (e.g. Tesla’s logo). - symbol: Universal mark representing the brand (e.g. Tesla’s T symbol). Logo Theme Options: - light: The light version of the logo. - dark: The dark version of the logo. Logo Fallback Options: - brandfetch: The Brandfetch logo (default). - transparent: A see-through placeholder for custom backgrounds. - lettermark: A square icon with the brand’s first letter (only for type=icon). - 404: HTTP status 404 and a see-through placeholder. ``` -------------------------------- ### Verify Webhook Signature and Timing Source: https://docs.brandfetch.com/docs/webhooks/best-practices This JavaScript function verifies the integrity and timeliness of incoming webhook payloads. It uses the `crypto` module to create an HMAC signature and compares it with the provided signature. It also checks if the timestamp is within a 2-minute tolerance to prevent replay attacks. ```JavaScript 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; } ``` -------------------------------- ### Brandfetch Webhook Delivery Behaviors Source: https://docs.brandfetch.com/docs/webhooks/delivery-behaviors Details the retry and disable behaviors for Brandfetch webhooks, including the exponential backoff strategy and email notifications for misconfigured endpoints. It also clarifies that event delivery order is not guaranteed and suggests using the API to fetch current data. ```APIDOC Webhooks - Delivery Behaviors Retry Behavior: Brandfetch attempts to deliver an event for up to 3 days with exponential backoff. Retries are prevented if the endpoint is disabled or deleted. Re-enabling an endpoint before a retry attempt allows future retries. Disable Behavior: Brandfetch sends email notifications for misconfigured endpoints that consistently fail to respond with a 2xx HTTP status code. The email will indicate when the endpoint will be automatically disabled. Event Ordering: Event delivery order is not guaranteed. Integrations should not depend on the order of events. For example, re-indexing a brand might generate 'brand.company.updated' and 'brand.updated' events, which may not be delivered in that sequence. Use the API to fetch current brand information if needed. ``` -------------------------------- ### Query by Financial Identifier Source: https://docs.brandfetch.com/docs/logo-link Illustrates how to query for brand logos using financial identifiers such as ISIN or Stock Ticker. ```APIDOC Query by ISIN: https://cdn.brandfetch.io/brandfetch.com?c={your-client-id-here}&isin={ISIN_CODE} Query by Stock Ticker: https://cdn.brandfetch.io/brandfetch.com?c={your-client-id-here}&ticker={STOCK_TICKER} ``` -------------------------------- ### Embed Logo with Logo Link Source: https://docs.brandfetch.com/docs/logo-link Demonstrates how to embed a brand logo using an img tag with a Logo Link CDN source. The src attribute includes a client ID for identification. ```HTML ``` -------------------------------- ### Brandfetch Transaction API Authentication Source: https://docs.brandfetch.com/docs/transaction-api Authenticates requests to the Brandfetch Transaction API by providing an API key as a Bearer token in the Authorization header. ```APIDOC Authorization: Bearer ``` -------------------------------- ### Brandfetch Webhook Event Types Source: https://docs.brandfetch.com/docs/webhooks/event-types This section details the various event types that can be subscribed to via Brandfetch webhooks. These events are triggered by specific actions related to brand data management. Webhooks are currently available only to Scale customers. ```APIDOC 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). ``` -------------------------------- ### Reporting Inaccurate Data Source: https://docs.brandfetch.com/docs/getting-started Users can report inaccurate data using a provided form. The Q&A team will review the submission and provide updates if records are changed. ```APIDOC Report Inaccurate Data: - Use the provided form. - Q&A team reviews submissions. - Updates will be provided if records change. ``` -------------------------------- ### Brandfetch Transaction API Usage Source: https://docs.brandfetch.com/docs/transaction-api The Transaction API identifies merchant brands from raw transaction data. It processes unstructured payment text, maps it to a domain, and returns brand details. The primary input is a `transactionLabel` and an optional `countryCode`. ```APIDOC Transaction API: Input: transactionLabel: The line-item text from a bank or credit card statement. countryCode: The locale of the merchant (e.g., "US"). Output: Brand details (name, logo, domain, industry, etc.). Example: transactionLabel: "STARBUCKS 1523 OMAHA NE" countryCode: "US" Features: - Global coverage - Real-time indexing for unrecognized brands ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.