Skip to main content

​
The Brand Data Model

When you request brand data for a domain, Brand.dev returns a comprehensive object containing:

​
Brand Assets

  • Logos - Multiple variants (icon, full logo, light mode, dark mode, transparent, opaque)
  • Colors - Brand color palette with hex codes and human-readable names
  • Backdrops - Background images and hero graphics

​
Company Information

  • Basic Details - Company name, description, slogan
  • Contact Info - Address, phone number
  • Social Links - X, LinkedIn, Facebook, YouTube profiles
  • Links - Careers page, blog, pricing, terms, privacy policy

​
Business Context

  • Industries - Industry classifications (EIC codes)
  • Financial - Stock ticker information (for public companies)
  • NAICS Codes - North American Industry Classification System codes

​
Understanding Logo Types

Brand.dev provides different logo variants to suit different use cases:
  • icon - Square or near-square logos, perfect for avatars and app icons (aspect ratio ~1:1)
  • logo - Horizontal logos, ideal for navigation bars and headers (aspect ratio >2:1)

​
Logo Mode: Light, Dark, and Transparency

  • light - Transparent logo designed for light backgrounds (dark text/graphics)
  • dark - Transparent logo designed for dark backgrounds (light text/graphics)
  • has_opaque_background - Logo includes its own background color
Pro tip: For navigation bars, look for logos with type: "logo", mode: "light", and aspect_ratio > 2. For user avatars, look for type: "icon" with aspect_ratio close to 1.

​
Color Extraction

Brand.dev extracts brand colors from verified sources and provides them in a structured format: 
{
  "hex": "#655ef3",
  "name": "Blue Hepatica"
}
Colors are typically ordered by importance, with the primary brand color first. Each color includes a human-readable name to help you understand its semantic meaning.
The color names are generated using a color-naming algorithm and may not always match official brand terminology.

​
Data Freshness & Caching

Brand.dev will only cache brand data for 3 months at most.
Brand.dev uses intelligent caching to provide fast responses while keeping data fresh:

​
Response Times

  • Warm hits (cached) - ~250ms p50 latency
  • Cold hits (new domain) - ~7 seconds p50 latency (first request)

​
Cache Strategy

When you request a domain for the first time, Brand.dev:
  1. Checks the cache for existing data
  2. If not cached, crawls verified sources in real-time
  3. Extracts and structures the brand data
  4. Stores the result for fast subsequent requests

​
Prefetching

Use the Prefetch by Email endpoint to warm the cache before the user needs the data: 
// Prefetch when user enters email (doesn't count against credits)
await client.utility.prefetchByEmail({
  email: "[email protected]",
});

// Later, retrieve is fast (~250ms)
const { brand } = await client.brand.retrieve({
  domain: "acme.com",
});

​
Data Sources & Verification

Brand.dev aggregates data from multiple verified sources to ensure accuracy:
  • Official company websites
  • Social media profiles (verified accounts)
  • Business registries and databases
  • Public company filings (for financial data)
All data is cleaned, standardized, and validated before being returned through the API.

​
API Response Structure

Every Brand.dev API response follows a consistent structure: 
{
  "status": "ok",
  "brand": {
    // Brand data object
  },
  "code": 200
}
  • status - Always "ok" for successful requests
  • brand - The complete brand data object
  • code - HTTP status code (200 for success)

​
Error Handling

When a request fails, Brand.dev returns structured error information: 
{
  "status": "error",
  "message": "Brand not found for domain",
  "code": 404
}
Common error codes:
  • 404 - Brand not found
  • 401 - Invalid API key
  • 429 - Rate limit exceeded
  • 422 - Invalid parameters (e.g., disposable email)

Error Handling Guide

Learn how to handle errors gracefully

​
Rate Limits

Brand.dev implements rate limits to ensure fair usage and system stability. Rate limits vary by plan tier and are measured in requests per minute. When you exceed your rate limit, you’ll receive a 429 status code with a Retry-After header indicating when you can retry.
The Prefetch by Email endpoint does not count against your rate limits or credit usage.

​
Best Practices

​
1. Cache Client-Side

Store brand data in your application cache to avoid repeated API calls: 
// Cache brand data for 24 hours
const CACHE_TTL = 24 * 60 * 60 * 1000;
const cache = new Map();

async function getBrandWithCache(domain: string) {
  const cached = cache.get(domain);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const { brand } = await client.brand.retrieve({ domain });
  cache.set(domain, { data: brand, timestamp: Date.now() });
  return brand;
}

​
2. Handle Missing Data Gracefully

Not all brands have all data fields. Always provide fallbacks: 
const logo = brand.logos[0]?.url || "/placeholder-logo.svg";
const primaryColor = brand.colors[0]?.hex || "#000000";

​
3. Use Prefetching for Better UX

Prefetch brand data as soon as you know the domain (e.g., when user types email): 
async function handleEmailChange(email: string) {
  if (email.includes("@")) {
    // Fire and forget - prefetch in background
    client.utility.prefetchByEmail({ email }).catch(() => {});
  }
}

Quickstart

Get started in 5 minutes

API Reference

Explore all endpoints

Use Cases

See real-world examples