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

pip install context.dev

gem install context.dev

go get github.com/context-dot-dev/context-go-sdk

composer require context-dev/context-dev-php

One endpoint, six identifiers

POST /brand/retrieve is the unified lookup for domains, company names, work emails, stock tickers, card transaction descriptors, and direct URLs. Pass exactly one identifier in the body along with a type discriminator that tells the API which lookup to run.

Identifier	`type` value	Field to send
Domain	`by_domain`	`domain`
Name	`by_name`	`name` (3–30 characters)
Email	`by_email`	`email`
Ticker	`by_ticker`	`ticker`
Card txn	`by_transaction`	`transaction_info`
Direct URL	`by_direct_url`	`direct_url` (http(s) URL)

The response envelope is the same for every lookup, so downstream code only branches on the input, not the output.

by_direct_url fetches brand data only from the URL you provide — no domain resolution, database lookup, or cross-source enrichment runs. See Look up by direct URL for when to use it.

ISINs still have a dedicated endpoint: GET /brand/retrieve-by-isin.

Get a brand by domain

Send POST /brand/retrieve with type: "by_domain" and a domain field. The response is a full brand profile: logos, colors, description, socials, industry, address, and links.

curl -X POST https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_domain",
    "domain": "stripe.com"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_domain",
  domain: "stripe.com",
});

console.log(response.brand.title);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(type="by_domain", domain="stripe.com")

print(response.brand.title)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: { type: :by_domain, domain: "stripe.com" }
)

puts response.brand.title

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{
        OfByDomain: &contextdev.BrandGetParamsBodyByDomain{
            Domain: "stripe.com",
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Title)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    type: 'by_domain',
    domain: 'stripe.com',
);

echo $response->brand->title, PHP_EOL;

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
`type`	string	—	Required. Lookup discriminator. Use `by_domain` here. See the identifier table for the full list.
`domain`	string	—	Required. Domain to retrieve brand data for (e.g. `stripe.com`). Provide exactly one identifier field per request.
`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"

import ContextDev from "context.dev";

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

const response = await client.brand.retrieveSimplified({
  domain: "stripe.com",
});

console.log(response.brand.logos[0].url);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve_simplified(domain="stripe.com")

print(response.brand.logos[0].url)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve_simplified(domain: "stripe.com")

puts response.brand.logos.first.url

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.GetSimplified(context.TODO(), contextdev.BrandGetSimplifiedParams{
        Domain: "stripe.com",
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Logos[0].URL)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieveSimplified(domain: 'stripe.com');

if ($response->brand->logos) {
    echo $response->brand->logos[0]->url, PHP_EOL;
}

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

Send POST /brand/retrieve with type: "by_name" and a name (3–30 characters). Pass country_gl to bias the match toward a specific country when the name is ambiguous across markets.

curl -X POST https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_name",
    "name": "Airbnb"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_name",
  name: "Airbnb",
});

console.log(response.brand.domain);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(type="by_name", name="Airbnb")

print(response.brand.domain)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: { type: :by_name, name: "Airbnb" }
)

puts response.brand.domain

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{
        OfByName: &contextdev.BrandGetParamsBodyByName{
            Name: "Airbnb",
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Domain)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    type: 'by_name',
    name: 'Airbnb',
);

echo $response->brand->domain, PHP_EOL;

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
`type`	string	—	Required. Lookup discriminator. Use `by_name` here.
`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 POST /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

Send POST /brand/retrieve with type: "by_email" and an email field. The API extracts the domain, rejects personal-email providers (gmail, outlook, proton, etc.), then runs the same resolver as a domain lookup.

curl -X POST https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_email",
    "email": "[email protected]"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_email",
  email: "[email protected]",
});

console.log(response.brand.domain);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(
    type="by_email",
    email="[email protected]",
)

print(response.brand.domain)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: { type: :by_email, email: "[email protected]" }
)

puts response.brand.domain

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{
        OfByEmail: &contextdev.BrandGetParamsBodyByEmail{
            Email: "[email protected]",
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Domain)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    type: 'by_email',
    email: '[email protected]',
);

echo $response->brand->domain, PHP_EOL;

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
`type`	string	—	Required. Lookup discriminator. Use `by_email` here.
`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 POST /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

Send POST /brand/retrieve with type: "by_ticker" and a ticker field. The response populates the stock object with ticker and exchange.

curl -X POST https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_ticker",
    "ticker": "AAPL"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_ticker",
  ticker: "AAPL",
});

console.log(response.brand.stock);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(type="by_ticker", ticker="AAPL")

print(response.brand.stock)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: { type: :by_ticker, ticker: "AAPL" }
)

puts response.brand.stock.to_h

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{
        OfByTicker: &contextdev.BrandGetParamsBodyByTicker{
            Ticker: "AAPL",
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("%+v\n", response.Brand.Stock)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    type: 'by_ticker',
    ticker: 'AAPL',
);

print_r($response->brand->stock);

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
`type`	string	—	Required. Lookup discriminator. Use `by_ticker` here.
`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 POST /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 direct URL

Send POST /brand/retrieve with type: "by_direct_url" and a full http(s) direct_url. The API fetches brand fields (title, description, logos, socials, contact info, links) only from that URL — no domain resolution, database lookup, or cross-source enrichment runs. Use this when you want to point the API at a specific page — a subpath, a preview environment, a landing page, or a domain the API doesn’t yet have in its database — and get whatever that page exposes. Results are limited to what the single page contains, so expect fewer fields than a by_domain lookup.

curl -X POST https://api.context.dev/v1/brand/retrieve \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_direct_url",
    "direct_url": "https://stripe.com/enterprise"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_direct_url",
  direct_url: "https://stripe.com/enterprise",
});

console.log(response.brand.title, response.brand.logos[0]?.url);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(
    type="by_direct_url",
    direct_url="https://stripe.com/enterprise",
)

print(response.brand.title)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: {
    type: :by_direct_url,
    direct_url: "https://stripe.com/enterprise",
  }
)

puts response.brand.title

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Get(context.TODO(), contextdev.BrandGetParams{
        OfByDirectURL: &contextdev.BrandGetParamsBodyByDirectURL{
            DirectURL: "https://stripe.com/enterprise",
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Title)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    type: 'by_direct_url',
    directUrl: 'https://stripe.com/enterprise',
);

echo $response->brand->title, PHP_EOL;

10 credits per successful call

by_direct_url rejects maxSpeed, force_language, and maxAgeMs — the single-page scrape flow would ignore them. Only timeoutMS is accepted alongside direct_url.

Request Parameters

Parameter	Type	Default	Description
`type`	string	—	Required. Lookup discriminator. Use `by_direct_url` here.
`direct_url`	string	—	Required. Full http(s) URL to fetch (e.g. `https://stripe.com/enterprise`).
`timeoutMS`	integer	—	Abort with a 408 if the request exceeds this many milliseconds. Max `300000`.

Response

Returns the same envelope as POST /brand/retrieve, but the brand object only contains fields that could be extracted from the provided URL: domain, title, description, logos, socials, email, phone, and links. Fields backed by database enrichment — colors, backdrops, industries, stock, address — are not returned. If the URL can’t be fetched, the API responds with 400 and error_code: "WEBSITE_ACCESS_ERROR".

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"

import ContextDev from "context.dev";

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

const response = await client.brand.retrieveByIsin({ isin: "US0378331005" });

console.log(response.brand.domain, response.brand.stock);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve_by_isin(isin="US0378331005")

print(response.brand.domain, response.brand.stock)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve_by_isin(isin: "US0378331005")

puts "#{response.brand.domain} #{response.brand.stock.to_h}"

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.GetByIsin(context.TODO(), contextdev.BrandGetByIsinParams{
        Isin: "US0378331005",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("%s %+v\n", response.Brand.Domain, response.Brand.Stock)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieveByIsin(isin: 'US0378331005');

echo $response->brand->domain, ' ';
print_r($response->brand->stock);

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 POST /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

Send POST /brand/retrieve with type: "by_transaction" and a raw descriptor in transaction_info. Pass mcc, city, country_gl, or phone hints when you have them to improve accuracy on ambiguous descriptors.

curl https://api.context.dev/v1/brand/retrieve \
  -X POST \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "by_transaction",
    "transaction_info": "STARBUCKS STORE 12345",
    "country_gl": "us",
    "mcc": "5814"
  }'

import ContextDev from "context.dev";

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

const response = await client.brand.retrieve({
  type: "by_transaction",
  transaction_info: "STARBUCKS STORE 12345",
  country_gl: "us",
  mcc: "5814",
});

console.log(response.brand.domain);

import os
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

response = client.brand.retrieve(
    type="by_transaction",
    transaction_info="STARBUCKS STORE 12345",
    country_gl="us",
    mcc="5814",
)

print(response.brand.domain)

require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

response = client.brand.retrieve(
  body: {
    type: :by_transaction,
    transaction_info: "STARBUCKS STORE 12345",
    country_gl: :us,
    mcc: "5814",
  }
)

puts response.brand.domain

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk"
    "github.com/context-dot-dev/context-go-sdk/option"
    "github.com/context-dot-dev/context-go-sdk/packages/param"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    response, err := client.Brand.Retrieve(context.TODO(), contextdev.BrandRetrieveParams{
        TransactionInfo: "STARBUCKS STORE 12345",
        CountryGl:       contextdev.BrandRetrieveParamsCountryGlUs,
        Mcc:             param.NewOpt("5814"),
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Brand.Domain)
}

<?php

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$response = $client->brand->retrieve(
    transactionInfo: 'STARBUCKS STORE 12345',
    mcc: '5814',
    countryGl: 'us',
);

echo $response->brand->domain, ' ', $response->brand->title, PHP_EOL;

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
`type`	string	—	Required. Lookup discriminator. Use `by_transaction` here.
`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 the rest of POST /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 a `by_email` lookup.
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({ type: "by_domain", domain });
    } catch (err: any) {
      if (err.status === 429 && i < maxRetries - 1) {
        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
        continue;
      }
      throw err;
    }
  }
}

import os
import time
from context.dev import ContextDev, APIError

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

def retrieve_with_retry(domain, max_retries=3):
    for i in range(max_retries):
        try:
            return client.brand.retrieve(type="by_domain", domain=domain)
        except APIError as e:
            if e.status_code == 429 and i < max_retries - 1:
                time.sleep(2 ** i)
                continue
            raise

require "context_dev"

def retrieve_with_retry(domain, max_retries: 3)
  client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))
  max_retries.times do |i|
    return client.brand.retrieve(body: { type: :by_domain, domain: domain })
  rescue ContextDev::Errors::APIError => e
    raise unless e.status == 429 && i < max_retries - 1
    sleep(2 ** i)
  end
end

<?php

use ContextDev\Client;
use ContextDev\Core\Exceptions\APIStatusException;

function retrieveWithRetry(string $domain, int $maxRetries = 3) {
    $client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

    for ($i = 0; $i < $maxRetries; $i++) {
        try {
            return $client->brand->retrieve(type: 'by_domain', domain: $domain);
        } catch (APIStatusException $e) {
            if ($e->status === 429 && $i < $maxRetries - 1) {
                usleep((2 ** $i) * 1_000_000);
                continue;
            }
            throw $e;
        }
    }
}

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

​One endpoint, six identifiers

​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 direct URL

​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

One endpoint, six identifiers

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 direct URL

Request Parameters

Response

Look up by ISIN

Request Parameters

Response

Identify a card transaction

Request Parameters

Response

Handle errors

Use cases

Next steps