Get Brand Data - Context.dev

Context.dev’s Brand API turns any of the following identifiers into a full brand profile with logos, colors, slogans, description, social media handles, address, industry, and website page links:

Brand domain (e.g., stripe.com)
Company name (e.g., “Stripe Inc”)
A work email (e.g., [email protected])
A stock ticker (e.g., AAPL)
An ISIN (e.g., US0378331005)

Integrate Context.dev's Brand resolution endpoints

Open in Cursor

Prerequisites

A Context.dev API key. Sign up at context.dev/signup, copy the key from the dashboard (prefix ctxt_secret_), and export it:
```
export CONTEXT_DEV_API_KEY="ctxt_secret_..."
```
An SDK (optional). Install for your language, or skip the install and call directly with curl:
npm install context.dev

Get a brand by domain

GET /brand/retrieve takes a domain and returns a full brand profile: logos, colors, description, socials, industry, address, and links.

curl -G https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=stripe.com"

10 credits per successful call The connection stays open while the lookup runs, so there’s no need to poll. Repeated lookups for the same domain within maxAgeMs return the cached record.

Request Parameters

Parameter	Type	Default	Description
`domain`	string	—	Required. Domain to retrieve brand data for (e.g. `stripe.com`). Use `/brand/retrieve-by-name` or `/brand/retrieve-by-ticker` when you have a company name or ticker instead.
`force_language`	string	—	Force the language of the retrieved brand data. Accepts a SupportedLanguage code.
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster response, at the cost of less comprehensive data.
`maxAgeMs`	integer	`7776000000` (90d)	Max cache age before a hard refresh. Clamped to `[86400000, 31536000000]` (1 day – 1 year).
`timeoutMS`	integer	—	Abort the request with a 408 if it exceeds this many milliseconds. Max `300000` (5 min).

Response

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "stripe.com",
    "title": "Stripe",
    "description": "Stripe is a global financial-infrastructure platform that helps businesses accept payments, manage subscriptions, issue cards, and build custom revenue models…",
    "slogan": "Financial infrastructure to grow your revenue.",
    "colors": [
      { "hex": "#543cfb", "name": "Meteor Shower" },
      { "hex": "#a498ec", "name": "Dull Lavender" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/5d83eab0-8041-4c39-a30d-84e6a0c5c461.jpg",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [{ "hex": "#543cfb", "name": "Meteor Shower" }],
        "resolution": { "width": 512, "height": 512, "aspect_ratio": 1 }
      }
    ],
    "backdrops": [
      {
        "url": "https://media.brand.dev/a0a5ce89-982c-4e3d-9def-8db3e19c6294.jpg",
        "colors": [
          { "hex": "#f57b2d", "name": "Iceland Poppy" },
          { "hex": "#f4bc8c", "name": "Brandy Butter" }
        ],
        "resolution": { "width": 1000, "height": 169, "aspect_ratio": 5.92 }
      }
    ],
    "socials": [
      { "type": "x", "url": "https://x.com/stripe" },
      { "type": "github", "url": "https://github.com/stripe" },
      { "type": "facebook", "url": "https://facebook.com/StripeHQ" },
      { "type": "linkedin", "url": "https://linkedin.com/company/stripe" },
      { "type": "youtube", "url": "https://youtube.com/stripe" }
    ],
    "address": {
      "street": "354 Oyster Point Blvd",
      "city": "South San Francisco",
      "state_province": "California",
      "state_code": "CA",
      "country": "United States",
      "country_code": "US",
      "postal_code": "94080"
    },
    "industries": {
      "eic": [
        { "industry": "Finance", "subindustry": "Payments & Money Movement" },
        {
          "industry": "Finance",
          "subindustry": "Financial Infrastructure & APIs"
        }
      ]
    },
    "links": {
      "blog": "https://stripe.com/blog",
      "login": null,
      "signup": null,
      "careers": "https://stripe.com/jobs",
      "contact": "https://stripe.com/contact/sales",
      "privacy": "https://stripe.com/privacy",
      "terms": "https://stripe.com/legal",
      "pricing": "https://stripe.com/pricing"
    },
    "primary_language": "english",
    "is_nsfw": false
  }
}

Field	Type	Description
`status`	string	`"ok"` on success, `"error"` on a non-2xx.
`code`	integer	HTTP status code, echoed in the body for convenience.
`brand.domain`	string	The brand’s canonical domain.
`brand.title`	string	Company name.
`brand.description`	string	One-paragraph company description.
`brand.slogan`	string	Marketing tagline, if available.
`brand.colors[]`	array	Brand colors ordered by visual prominence. Each has `hex` and a human-readable `name`. Index 0 is the primary.
`brand.logos[]`	array	Logo variants. Each has `url`, `mode` (`light`, `dark`, `has_opaque_background`), `type` (`logo` or `icon`), `colors`, and `resolution.{width, height, aspect_ratio}`.
`brand.backdrops[]`	array	Hero / backdrop imagery. Same color and resolution structure as logos.
`brand.socials[]`	array	Social profile URLs. `type` is one of `x`, `facebook`, `instagram`, `linkedin`, `youtube`, `tiktok`, `github`, and 20+ more.
`brand.address`	object	HQ address: `street`, `city`, `state_province`, `state_code`, `country`, `country_code`, `postal_code`.
`brand.stock`	object	`ticker` and `exchange`. `null` for private companies.
`brand.industries.eic[]`	array	EIC industry tags with `industry` and `subindustry`. For NAICS or SIC codes, call `/web/naics` or `/web/sic`.
`brand.links`	object	Non-social URLs the resolver was able to discover. Common keys include `blog`, `pricing`, `careers`, `contact`, `privacy`, `terms`, `login`, `signup`. Values are `null` when the resolver couldn’t find a URL for that key.
`brand.email`	string	Public contact email, when discoverable.
`brand.phone`	string	Public contact phone, when discoverable.
`brand.primary_language`	string	Detected language of the brand’s website (e.g. `english`, `spanish`).
`brand.is_nsfw`	boolean	Safe-content flag.

The colors returned by this API are extracted from the brand’s logos. To get pixel-perfect colors as they appear on a website, use the Styleguide API instead.

Get a lighter response

If you need only domain, title, colors, logos, and backdrops, you can use GET /brand/retrieve-simplified.

curl -G https://api.context.dev/v1/brand/retrieve-simplified \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "domain=stripe.com"

10 credits per successful callRequest Parameters

Parameter	Type	Default	Description
`domain`	string	—	Required. Domain to retrieve simplified brand data for.
`maxAgeMs`	integer	`7776000000`	Max cache age before a hard refresh. Clamped to `[86400000, 31536000000]`.
`timeoutMS`	integer	—	Abort the request with a 408 if it exceeds this many milliseconds. Max `300000`.

Response

{
  "status": "ok",
  "brand": {
    "domain": "stripe.com",
    "title": "Stripe",
    "colors": [
      { "hex": "#543cfb", "name": "Meteor Shower" },
      { "hex": "#a498ec", "name": "Dull Lavender" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/5d83eab0-8041-4c39-a30d-84e6a0c5c461.jpg",
        "mode": "has_opaque_background",
        "type": "icon",
        "resolution": { "width": 512, "height": 512, "aspect_ratio": 1 }
      }
    ],
    "backdrops": [
      {
        "url": "https://media.brand.dev/a0a5ce89-982c-4e3d-9def-8db3e19c6294.jpg",
        "resolution": { "width": 1024, "height": 768, "aspect_ratio": 1.33 }
      }
    ]
  }
}

Look up by company name

GET /brand/retrieve-by-name resolves a company name (3–30 characters) to a brand. Pass country_gl to bias the match toward a specific country when the name is ambiguous across markets.

curl -G https://api.context.dev/v1/brand/retrieve-by-name \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "name=Airbnb"

10 credits per successful call Name must be 3–30 characters. Pass country_gl as a lowercase ISO 3166-1 alpha-2 code to narrow the match when the name could resolve to multiple brands across markets.

Request Parameters

Parameter	Type	Default	Description
`name`	string (3–30 chars)	—	Required. Company name (e.g. `Apple Inc`, `Microsoft Corporation`).
`country_gl`	string (ISO 3166-1 alpha-2, lowercase)	—	Two-letter country code to bias the match toward (e.g. `us`, `gb`, `de`).
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster, less complete response.
`force_language`	string	—	Force the language of the retrieved brand data.
`maxAgeMs`	integer	`7776000000`	Max cache age before a hard refresh.
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as GET /brand/retrieve; see the response field table above.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "airbnb.com",
    "title": "Airbnb",
    "description": "Airbnb is a global online community marketplace that connects hosts with guests, offering unique stays and experiences…",
    "slogan": "Belong Anywhere",
    "colors": [
      { "hex": "#fc3c5c", "name": "Radical Red" },
      { "hex": "#fc9cb4", "name": "Saira Red" },
      { "hex": "#fb5c74", "name": "Ponceau" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/4ae9a10b-ffde-45c8-b5c1-c1e7cef5b716.png",
        "mode": "light",
        "type": "icon",
        "colors": [{ "hex": "#fc3c5c", "name": "Radical Red" }],
        "resolution": { "width": 250, "height": 250, "aspect_ratio": 1 }
      }
    ],
    "stock": { "ticker": "ABNB", "exchange": "NASDAQ" },
    "industries": {
      "eic": [
        {
          "industry": "Hospitality & Tourism",
          "subindustry": "Vacation Rentals & Short-Term Stays"
        },
        {
          "industry": "Technology",
          "subindustry": "eCommerce & Marketplace Platforms"
        }
      ]
    }
  }
}

Look up by work email

GET /brand/retrieve-by-email extracts the domain from an email address, filters out personal-email providers (gmail, outlook, proton, etc.), then runs the same resolver as /brand/retrieve.

curl -G https://api.context.dev/v1/brand/retrieve-by-email \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "[email protected]"

10 credits per successful call Personal-email addresses on common consumer providers (*@gmail.com, *@outlook.com, *@proton.me, and others) return a 422 with error_code: "FREE_EMAIL_DETECTED", which is useful for onboarding flows that should only enrich on a work email.

Request Parameters

Parameter	Type	Default	Description
`email`	string	—	Required. Email address (e.g. `[email protected]`).
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster, less complete response.
`force_language`	string	—	Force the language of the retrieved brand data.
`maxAgeMs`	integer	`7776000000`	Max cache age before a hard refresh.
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as GET /brand/retrieve; see the response field table above.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "stripe.com",
    "title": "Stripe",
    "slogan": "Financial infrastructure to grow your revenue.",
    "colors": [
      { "hex": "#543cfb", "name": "Meteor Shower" },
      { "hex": "#a498ec", "name": "Dull Lavender" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/5d83eab0-8041-4c39-a30d-84e6a0c5c461.jpg",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [{ "hex": "#543cfb", "name": "Meteor Shower" }],
        "resolution": { "width": 512, "height": 512, "aspect_ratio": 1 }
      }
    ],
    "industries": {
      "eic": [
        { "industry": "Finance", "subindustry": "Payments & Money Movement" },
        {
          "industry": "Finance",
          "subindustry": "Financial Infrastructure & APIs"
        }
      ]
    }
  }
}

Look up by stock ticker

GET /brand/retrieve-by-ticker resolves a stock ticker to a brand and populates the stock object with ticker and exchange.

curl -G https://api.context.dev/v1/brand/retrieve-by-ticker \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "ticker=AAPL"

10 credits per successful call Pass ticker_exchange to constrain the lookup to a specific exchange (NASDAQ, NYSE, LON, XETR, TYO, and 60+ others) when the bare symbol is ambiguous.

Request Parameters

Parameter	Type	Default	Description
`ticker`	string	—	Required. Stock ticker symbol (e.g. `AAPL`, `MSFT`).
`ticker_exchange`	string (enum)	—	Exchange code to disambiguate (`NASDAQ`, `NYSE`, `LON`, `XETR`, `TYO`, and 60+ others).
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster, less complete response.
`force_language`	string	—	Force the language of the retrieved brand data.
`maxAgeMs`	integer	`7776000000`	Max cache age before a hard refresh.
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as GET /brand/retrieve; see the response field table above. The stock object is populated for ticker lookups.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "apple.com",
    "title": "Apple",
    "slogan": "Think Different",
    "stock": { "ticker": "AAPL", "exchange": "NASDAQ" },
    "colors": [
      { "hex": "#7c7c7c", "name": "Namara Grey" },
      { "hex": "#656565", "name": "Hard Coal" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/08f7d41a-ef7b-4d83-aff6-e7f67408b85d.png",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [{ "hex": "#656565", "name": "Hard Coal" }],
        "resolution": { "width": 302, "height": 302, "aspect_ratio": 1 }
      }
    ],
    "industries": {
      "eic": [
        {
          "industry": "Technology",
          "subindustry": "Hardware & Semiconductors"
        },
        { "industry": "Technology", "subindustry": "Software (B2C)" }
      ]
    }
  }
}

Look up by ISIN

GET /brand/retrieve-by-isin resolves an International Securities Identification Number (ISIN), the 12-character identifier used in financial data feeds, to a brand and populates the stock object.

curl -G https://api.context.dev/v1/brand/retrieve-by-isin \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "isin=US0378331005"

10 credits per successful call Use this when you’re working with financial data feeds keyed by ISIN. Malformed ISINs return a 400.

Request Parameters

Parameter	Type	Default	Description
`isin`	string	—	Required. 12-character ISIN (e.g. `US0378331005` for Apple Inc.).
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster, less complete response.
`force_language`	string	—	Force the language of the retrieved brand data.
`maxAgeMs`	integer	`7776000000`	Max cache age before a hard refresh.
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as GET /brand/retrieve; see the response field table above. The stock object is populated with the resolved ticker.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "apple.com",
    "title": "Apple",
    "stock": { "ticker": "AAPL", "exchange": "NASDAQ" },
    "colors": [{ "hex": "#7c7c7c", "name": "Namara Grey" }],
    "logos": [
      {
        "url": "https://media.brand.dev/08f7d41a-ef7b-4d83-aff6-e7f67408b85d.png",
        "mode": "has_opaque_background",
        "type": "icon",
        "resolution": { "width": 302, "height": 302, "aspect_ratio": 1 }
      }
    ]
  }
}

Identify a card transaction

GET /brand/transaction_identifier takes a raw transaction descriptor and returns the merchant’s brand profile. Pass mcc, city, country_gl, or phone hints when you have them to improve accuracy on ambiguous descriptors.

curl -G https://api.context.dev/v1/brand/transaction_identifier \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --data-urlencode "transaction_info=STARBUCKS STORE 12345" \
  --data-urlencode "country_gl=us" \
  --data-urlencode "mcc=5814"

10 credits per successful call Descriptors the API can’t match with confidence return a 400 with error_code: "NOT_FOUND". Setting high_confidence_only: true makes the API return that 400 instead of a low-confidence match.

Request Parameters

Parameter	Type	Default	Description
`transaction_info`	string	—	Required. Raw transaction descriptor (e.g. `STARBUCKS STORE 12345`).
`country_gl`	string (lowercase ISO 3166-1 alpha-2)	—	Country hint (e.g. `us`, `gb`).
`city`	string	—	City hint (e.g. `San Francisco`).
`mcc`	string	—	Merchant Category Code (e.g. `5814`).
`phone`	number	—	Merchant phone hint, when present on the descriptor.
`high_confidence_only`	boolean	`false`	Return a 400 with `error_code: "NOT_FOUND"` instead of a low-confidence match.
`maxSpeed`	boolean	`false`	Skip time-consuming operations for a faster, less complete response.
`force_language`	string	—	Force the language of the retrieved brand data.
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as GET /brand/retrieve; see the response field table above.

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "starbucks.com",
    "title": "Starbucks",
    "slogan": "Inspiring and nurturing the human spirit — one person, one cup",
    "stock": { "ticker": "SBUX", "exchange": "NASDAQ" },
    "colors": [
      { "hex": "#0bac66", "name": "Secret Garden" },
      { "hex": "#7cd4b4", "name": "Seafoam Blue" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/67dc7846-2ca2-4a7b-9877-6bb5a5e2c0e0.png",
        "mode": "has_opaque_background",
        "type": "icon",
        "colors": [{ "hex": "#0bac66", "name": "Secret Garden" }],
        "resolution": { "width": 180, "height": 180, "aspect_ratio": 1 }
      }
    ],
    "industries": {
      "eic": [
        {
          "industry": "Retail & E-commerce",
          "subindustry": "Omnichannel & In-Store Retail"
        }
      ]
    }
  }
}

Handle errors

Not every input resolves. The API returns a non-2xx response with a message, status: "error", and an error_code:

{
  "message": "Transaction could not be identified.",
  "status": "error",
  "error_code": "NOT_FOUND"
}

Common cases:

Status	`error_code`	When
400	`WEBSITE_ACCESS_ERROR`	Domain can’t be resolved or fetched (DNS failure, hostile WAF).
400	`INPUT_VALIDATION_ERROR`	Required parameter missing or malformed.
400	`NOT_FOUND`	Lookup ran but no brand was matched.
408	`REQUEST_TIMEOUT`	Request exceeded `timeoutMS` or the platform max.
422	`FREE_EMAIL_DETECTED`	Personal-email provider on `/brand/retrieve-by-email`.
429	`RATE_LIMITED`	Rate limit hit.

Treat NOT_FOUND responses as a normal outcome, not an error. For high-volume pipelines, cache misses for at least 24 hours so you don’t re-resolve the same dead identifier on every retry. Rate limits surface as HTTP 429. Back off exponentially:

import ContextDev from "context.dev";

const client = new ContextDev({ apiKey: process.env.CONTEXT_DEV_API_KEY });

async function retrieveWithRetry(domain: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.brand.retrieve({ domain });
    } catch (err: any) {
      if (err.status === 429 && i < maxRetries - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw err;
    }
  }
}

For the full catalog of error codes, see Troubleshooting.

Use cases

Pre-fill onboarding forms with logo, name, and colors when a user signs up with a work email.
Enrich CRM leads with industry, socials, address, and logos for outbound playbooks.
Resolve card transaction descriptors to canonical merchant brands for spend analytics.
Power “trusted by” logo strips and customer-wall sections with live brand data.
Pull public-company profiles from a ticker or ISIN for investor-facing dashboards.

Next steps

Prefetch for Faster Response

Hide cold-hit latency from your users.

Handle Rate Limits

Backoff strategies, client cache, and prefetch fallbacks.

Best Practices

Caching, error handling, and key hygiene.

Troubleshooting

Status codes, retry patterns, and common errors.

​Prerequisites

​Get a brand by domain

​Request Parameters

​Response

​Look up by company name

​Request Parameters

​Response

​Look up by work email

​Request Parameters

​Response

​Look up by stock ticker

​Request Parameters

​Response

​Look up by ISIN

​Request Parameters

​Response

​Identify a card transaction

​Request Parameters

​Response

​Handle errors

​Use cases

​Next steps

Prefetch for Faster Response

Handle Rate Limits

Best Practices

Troubleshooting

Prerequisites

Get a brand by domain

Request Parameters

Response

Look up by company name

Request Parameters

Response

Look up by work email

Request Parameters

Response

Look up by stock ticker

Request Parameters

Response

Look up by ISIN

Request Parameters

Response

Identify a card transaction

Request Parameters

Response

Handle errors

Use cases

Next steps