Prefill and personalize onboarding

Ask for a work email once, retrieve the associated Brand profile on your server, and prefill the next onboarding step. Use the same confirmed identity to seed a workspace theme. The user should always be able to correct or skip the result. You’ll need a server-side API key from the Quickstart. Each successful Brand lookup costs 10 credits. The example uses a Next.js route, but the same request works from any backend.

Retrieve a company profile

Use any supported SDK for the underlying lookup. The PHP tab uses the SDK’s low-level Brand method; the backend and UI example below uses TypeScript and React.

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';

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

// Use the SDK's low-level request: its generated Brand helper cannot express this lookup.
$response = $client->request(
    method: 'post',
    path: 'brand/retrieve',
    body: [
      "type" => "by_domain",
      "domain" => "stripe.com",
    ],
);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $data['brand']['title'] ?? 'No match', PHP_EOL;

What to prefill

Form field	Brand field	Fallback
Company name	`brand.title`	Leave blank
Website	`brand.domain`	Derive the email domain for display only
Description	`brand.description`	Leave blank
Logo	A suitable item from `brand.logos[]`	Initials or a neutral icon
Industry	`brand.industries.eic[0]`	Ask the user
Social profile	Matching item in `brand.socials[]`	Omit the field

Every field is optional. A successful response can still contain a partial profile.

Look up the company

The browser calls your backend. Your backend validates the email and calls Context.dev with CONTEXT_DEV_API_KEY. Here is a Next.js route using the HTTPS API directly so the fallback behavior is explicit:

app/api/company-profile/route.ts

type BrandPayload = {
  brand?: {
    domain?: string;
    title?: string;
    description?: string;
    colors?: Array<{ hex: string; source: "site" | "logo" }>;
    logos?: Array<{ url: string; type?: string; mode?: string }>;
  };
  error_code?: string;
};

export async function POST(request: Request) {
  const { email } = (await request.json()) as { email?: string };

  if (typeof email !== "string" || !email.includes("@")) {
    return Response.json({ error: "Enter a valid email." }, { status: 400 });
  }

  const upstream = await fetch("https://api.context.dev/v1/brand/retrieve", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CONTEXT_DEV_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "by_email",
      email,
      timeoutOpts: { milliseconds: 10_000, behavior: "fail" },
    }),
  });

  const payload = (await upstream.json()) as BrandPayload;
  const noProfile =
    upstream.status === 422 ||
    (upstream.status === 400 && payload.error_code === "NOT_FOUND");

  if (noProfile) {
    return Response.json({ brand: null, reason: "no_business_profile" });
  }

  if (!upstream.ok) {
    return Response.json(
      { error: "Company details are temporarily unavailable." },
      { status: 503 },
    );
  }

  const brand = payload.brand;
  const accent = brand?.colors?.find(
    (color) => color.source === "site" && /^#[0-9a-f]{6}$/i.test(color.hex),
  )?.hex ?? null;
  const logoUrl = brand?.logos?.find(
    (logo) => logo.type === "logo" && logo.mode === "light" && logo.url.startsWith("https://"),
  )?.url ?? null;
  return Response.json({
    brand: brand
      ? {
          domain: brand.domain,
          title: brand.title,
          description: brand.description,
          branding: { accent, logoUrl },
        }
      : null,
  });
}

Do not return the upstream response wholesale. Send only the fields your form uses, and never expose the Context.dev API key or internal diagnostics to the browser.

Fill blank fields

Start the lookup when the user submits the email step. Fill only blank fields so a slow response cannot replace edits made while the request was running.

const response = await fetch("/api/company-profile", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email }),
});

if (response.ok) {
  const { brand } = await response.json();

  setForm((current) => ({
    ...current,
    companyName: current.companyName || brand?.title || "",
    website: current.website || brand?.domain || "",
    description: current.description || brand?.description || "",
  }));
}

Show the lookup as a convenience, not as verified user input:

Label the step “Confirm your company details.”
Make text fields editable and the logo replaceable.
Let the user continue when no profile is found.
Do not treat a physical address as a legal or headquarters address without separate verification.
Record which values the user confirmed if downstream logic depends on them.

Seed an editable workspace theme

After the user confirms the company, use brand.branding from the route above as suggestions for that tenant. Listener uses brand context for customer-specific experiences; the same pattern can personalize a workspace header or customer portal. Keep automatic candidates separate from saved user choices. A logo may belong to a parent brand or the platform hosting the website, so provide a replacement or Use no logo option.

workspace-theme.ts

type Branding = { accent: string | null; logoUrl: string | null };
type ThemeChoices = { accent?: string; logoUrl?: string | null };

export function workspaceTheme(suggested: Branding, saved: ThemeChoices) {
  const candidate = saved.accent ?? suggested.accent;
  const accent = candidate && /^#[0-9a-f]{6}$/i.test(candidate)
    ? candidate : "#334155";
  return {
    accent,
    background: "#ffffff",
    surface: "#f8fafc",
    text: "#171717",
    logoUrl: saved.logoUrl !== undefined ? saved.logoUrl : suggested.logoUrl,
  };
}

Map these roles to your component system rather than copying the whole extracted palette:

Workspace header

const theme = workspaceTheme(suggestedBranding, savedThemeChoices);

<header style={{
  background: theme.surface,
  color: theme.text,
  borderTop: `4px solid ${theme.accent}`,
  padding: 16,
}}>
  <h1>{confirmedCompanyName}</h1>
</header>

The accent above is decorative. Before using it behind text or on controls, choose a contrasting foreground and test the resulting states, as in the website theme recipe. Reserve dimensions and retain the company name when adding a logo. Save ThemeChoices against your tenant ID, independently from the automatic Brand snapshot. Refresh only the suggestions; reapply saved choices afterward. Do not apply a late lookup for an earlier email address to the current form or tenant: associate each response with the email and request that initiated it.

Condition	Signup behavior
Free or disposable email (`422`)	Continue with empty company fields.
No matching business (`NOT_FOUND`)	Continue with empty company fields.
Timeout or rate limit	Continue and offer a retry after signup.
Partial profile	Fill only present fields.
User edits a field	Preserve the user’s value.

If you know the email before the profile is needed, subscribers can queue a prefetch. Prefetch is an optimization, not a completion signal; the later Brand response remains the source of truth. Run email validation and abuse controls before the upstream call. Track matched, unmatched, partial, and failed lookups without logging full email addresses unnecessarily.

Retrieve a brand by email

Map work email addresses to company profiles.

Prefetching

Queue a lookup before the profile is needed.

Generate a branded website

Turn confirmed branding into a complete editable page theme.

Troubleshooting

Understand invalid email responses.

Brand experiences

Sales and content

Web research

Prefill and personalize onboarding

Retrieve a company profile

What to prefill

Look up the company

Fill blank fields

Seed an editable workspace theme

Retrieve a brand by email

Prefetching

Generate a branded website

Troubleshooting

​Retrieve a company profile

​What to prefill

​Look up the company

​Fill blank fields

​Seed an editable workspace theme

​Keep signup resilient

Retrieve a brand by email

Prefetching

Generate a branded website

Troubleshooting

Retrieve a company profile

What to prefill

Look up the company

Fill blank fields

Seed an editable workspace theme

Keep signup resilient