Retrieve brand data

The Brand API turns one company identifier into a shared profile containing the data Context.dev found, such as names, logos, colors, descriptions, social profiles, website links, and EIC industry tags.

Choose a lookup

POST /brand/retrieve accepts exactly one lookup type:

Input you have	`type`	Required field	Guide
Domain	`by_domain`	`domain`	Retrieve by domain
Company name	`by_name`	`name`	Retrieve by company name
Work email	`by_email`	`email`	Retrieve by work email
Stock ticker	`by_ticker`	`ticker`	Retrieve by stock ticker
One specific webpage	`by_direct_url`	`direct_url`	Retrieve from a direct URL
Card transaction descriptor	`by_transaction`	`transaction_info`	Enrich a transaction

Every variant returns the same top-level Brand response shape. Fields can be absent when the source does not expose them, so downstream code should not assume a complete asset set.

Prerequisites

Create an API key in the dashboard and keep it in a server-side environment variable:

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

Install an SDK from the Quickstart, or call the HTTPS endpoint directly.

Get a brand by domain

A domain is the most direct lookup when your application already knows the company’s website.

curl https://api.context.dev/v1/brand/retrieve \
  --request POST \
  --header "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "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 if response.brand else None)

require "cgi/core"
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/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

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

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

    fmt.Println(response.Brand.Title)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

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

// Use the SDK's low-level request method until the Brand helper is fixed.
$raw = $client->request(
    method: 'post',
    path: 'brand/retrieve',
    body: [
        'type' => 'by_domain',
        'domain' => 'stripe.com',
    ],
);

$response = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $response['brand']['title'] ?? 'No brand found', PHP_EOL;

The PHP tab uses the SDK’s low-level request method because the 2.14.0 Brand helper requires conflicting lookup fields. See the PHP guide for details.

The endpoint costs 10 credits. The connection remains open until the lookup completes; there is no job to poll.

Read the profile

A successful response uses the same envelope for every identifier:

{
  "status": "ok",
  "code": 200,
  "brand": {
    "domain": "stripe.com",
    "title": "Stripe",
    "description": "Stripe builds economic infrastructure for the internet.",
    "colors": [
      { "hex": "#635BFF", "name": "Indigo", "source": "site" }
    ],
    "logos": [
      {
        "url": "https://media.brand.dev/example-logo.png",
        "mode": "light",
        "type": "logo",
        "resolution": { "width": 512, "height": 214, "aspect_ratio": 2.39 }
      }
    ],
    "socials": [
      { "type": "linkedin", "url": "https://www.linkedin.com/company/stripe" }
    ],
    "industries": {
      "eic": [
        { "industry": "Finance", "subindustry": "Payments & Money Movement" }
      ]
    }
  },
  "cache_metadata": {
    "status": "hit",
    "age_ms": 42000
  }
}

The sample is intentionally partial. Use the Brand API reference for the complete schema. When rendering a profile:

Check whether brand is present before reading nested fields.
Treat logos, colors, socials, and industries.eic as possibly empty.
Select a logo using type, mode, and resolution; do not assume the first asset fits every UI.
Treat address, employee count, contact fields, stock data, and website links as discovered data, not verified legal records.
Store the canonical brand.domain returned by the resolver alongside the identifier you submitted.

Tune the lookup

Most lookup variants accept these shared options:

Requirement	Parameter	Behavior
Prefer a shorter lookup	`maxSpeed=true`	Skips time-consuming work and can return less complete data.
Request a response language	`force_language`	Uses a supported language value where retrieval supports it.
Reuse recent data	`maxAgeMs`	Defaults to three months; zero requests fresh data, and positive sub-day values are accepted. Values clamp between zero and one year.
Bound request time	`timeoutOpts`	Set `milliseconds` up to 300,000. `behavior: "fail"` returns `408` at the deadline; `"return-partial"` can return completed fields with `partial: true`.
Attribute usage	`tags`	Adds request tags for usage analysis.

by_direct_url accepts only its URL, timeoutOpts, and tags. It does not accept the shared cache, speed, or language controls because it reads one page directly.

Handle expected failures

Status	Typical cause	Application behavior
`400`	Invalid input or no matching brand	Inspect `error_code`; treat a genuine no-match as an empty product result.
`401`	Missing or invalid API key	Stop and fix credentials.
`408`	Lookup exceeded `timeoutOpts`	Retry outside the user-facing path or prefetch supported identifiers.
`422`	Free or disposable email, or a cold-domain timeout that is too low	Change the input or timeout rather than repeating the same request.
`429`	Rate limit exceeded	Honor `Retry-After` and use bounded backoff.

See Troubleshooting for the current error-code catalog.

Next steps

Extract a design system

Retrieve detailed typography, spacing, and component tokens.

Display a company logo

Embed a hosted logo when an image URL fits better than a profile response.

Choose a classification system

Select EIC, NAICS, or SIC for your workflow.

Use timeouts and partial results to choose the deadline behavior. Partial Brand profiles omit fields that have not completed; retain partial: true instead of treating an incomplete profile as a complete cached record. For a profile assembled during the request, cache_metadata reflects contributing scrape caches: any miss makes the result a miss, while all hits use the oldest contributing age. A stored Brand-cache hit uses the stored profile age. See cache freshness.

Get started

Web data

Brand data

Automation

Account and billing

Production

Choose a lookup

Prerequisites

Get a brand by domain

Read the profile

Tune the lookup

Handle expected failures

Next steps

Extract a design system

Display a company logo

Choose a classification system

​Choose a lookup

​Prerequisites

​Get a brand by domain

​Read the profile

​Tune the lookup

​Handle expected failures

​Next steps

Extract a design system

Display a company logo

Choose a classification system

Choose a lookup

Prerequisites

Get a brand by domain

Read the profile

Tune the lookup

Handle expected failures

Next steps