Enrich companies and contacts

When a CRM creates a lead, use the work email to retrieve the associated Brand profile and fill missing company fields before the first sales touch. You’ll need a server-side API key from the Quickstart and a CRM webhook or background job. Each successful Brand lookup costs 10 credits.

This workflow enriches the company associated with an email. It does not verify the person’s identity, role, seniority, or employment. Use the People API when you need person-level data.

How it works

Run enrichment in a queue or background worker. CRM webhooks are commonly retried, and a synchronous handler can time out while the Brand lookup is still running.

Choose CRM fields

CRM field	Brand source	Important caveat
Company name	`brand.title`	Editable, not a legal-entity name.
Website	`brand.domain`	Useful as your company-level deduplication key.
Description	`brand.description`	Marketing description, not due-diligence evidence.
Logo	`brand.logos[]`	Choose by `type`, `mode`, and resolution; keep a fallback.
Industry	`brand.industries.eic[]`	Optional Context.dev classification.
Social URLs	`brand.socials[]`	Map by each item’s `type`.
Contact details	`brand.email`, `brand.phone`	Company-level contact data when discovered.
Physical address	`brand.address`	Not guaranteed to be a legal or headquarters address.

Do not create required CRM fields from optional API fields. Decide which data is informational and which data your team must confirm.

Look up the company

Choose your client for the API request. The PHP tab uses the SDK’s low-level Brand method.

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_email",
  "email": "[email protected]",
  "timeoutMS": 15000
}'

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]",
  timeoutMS: 15000,
});

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_email",
    email="[email protected]",
    timeout_ms=15000,
)

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_email",
    "email" => "[email protected]",
    "timeout_ms" => 15000,
  }
)

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"
    "github.com/context-dot-dev/context-go-sdk/v2/packages/param"
)

func main() {
    client := contextdev.NewClient(option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")))
    response, err := client.Brand.Get(context.Background(), contextdev.BrandGetParams{
        OfByEmail: &contextdev.BrandGetParamsBodyByEmail{
            Email:     "[email protected]",
            TimeoutMs: param.NewOpt(int64(15000)),
        },
    })
    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_email",
      "email" => "[email protected]",
      "timeoutMS" => 15000,
    ],
);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $data['brand']['title'] ?? 'No match', PHP_EOL;

Normalize the lookup result

This TypeScript adapter keeps the rest of your CRM integration independent of upstream error shapes:

type CompanyLookup =
  | { status: "matched"; brand: Record<string, unknown> }
  | { status: "unmatched" }
  | { status: "retryable"; retryAfterSeconds?: number }
  | { status: "error"; httpStatus: number; code?: string };

export async function lookupCompany(email: string): Promise<CompanyLookup> {
  const response = 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,
      timeoutMS: 15_000,
    }),
  });

  const payload = await response.json();

  if (response.ok && payload.brand) {
    return { status: "matched", brand: payload.brand };
  }

  if (
    response.ok ||
    response.status === 422 ||
    (response.status === 400 && payload.error_code === "NOT_FOUND")
  ) {
    return { status: "unmatched" };
  }

  if (![408, 429].includes(response.status) && response.status < 500) {
    return {
      status: "error",
      httpStatus: response.status,
      code: payload.error_code,
    };
  }

  const retryAfterHeader = response.headers.get("Retry-After");
  const retryAfter = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
  return {
    status: "retryable",
    retryAfterSeconds:
      Number.isFinite(retryAfter) && retryAfter >= 0 ? retryAfter : undefined,
  };
}

Free and disposable email addresses return 422; treat those as unmatched. Retry 408, 429, server errors, and network failures with a bounded policy. Authentication and input errors need correction before retrying. The worker should also catch fetch failures and record them as retryable.

Patch blank fields only

Make the mapping explicit and preserve anything a rep or another trusted system already entered:

function fillBlank<T>(current: T | null | undefined, candidate: T | undefined) {
  return current == null || (typeof current === "string" && current.trim() === "")
    ? candidate
    : current;
}

function buildCrmPatch(existing: any, brand: any) {
  const logo = brand.logos?.find(
    (item: any) => item.type === "logo" && item.mode === "light",
  );
  const linkedin = brand.socials?.find((item: any) => item.type === "linkedin");

  return {
    companyName: fillBlank(existing.companyName, brand.title),
    companyDomain: fillBlank(existing.companyDomain, brand.domain),
    companyDescription: fillBlank(existing.companyDescription, brand.description),
    companyLogoUrl: fillBlank(existing.companyLogoUrl, logo?.url),
    companyLinkedIn: fillBlank(existing.companyLinkedIn, linkedin?.url),
    industry: fillBlank(existing.industry, brand.industries?.eic?.[0]?.industry),
  };
}

Filter out undefined fields before sending the patch if your CRM interprets them as clears.

Handle duplicate events

Use the CRM event ID as an idempotency key. If the CRM does not provide one, derive a stable key from the object ID and event timestamp.

Acknowledge the webhook quickly after validating its signature.
Enqueue the CRM object ID, email, and event ID.
Skip event IDs already processed.
Cache matched profiles by normalized brand.domain, not by the full email address.
Retry transient failures with a bounded exponential backoff and jitter.
Send permanent misses to a completed state so the webhook is not retried forever.

Add person context when the workflow needs it

Use the People API for a person’s identity and profile, separately from the company Brand lookup. Send additive clues you actually have, such as a work email and a confirmed company domain:

People enrichment request body

{
  "email": "[email protected]",
  "company": { "domain": "example.com" }
}

Send this body to POST /people/enrich. Handle match.status as candidate or not_found, and review the returned identity match before writing person fields. The People identity match score is distinct from the Brand response, which has no public numeric match score. Neither a company email domain nor a marketing description establishes someone’s current role or employment. For a candidate, inspect match.person.current_role_status before using current_role. present means a role is populated, none means the available work history shows ended roles, and unknown means the current role could not be confirmed. Do not convert an unknown role into an unemployment claim. Keep your CRM contact ID and account ID as the durable identities. Domains can help deduplicate company candidates, but subsidiaries, rebrands, and shared domains may need separate account records.

Attach sourced account research

Use selected website pages or structured extraction for public product descriptions, announced updates, or hiring signals. With Extract, use nullable fields and factCheck: true; preserve the analyzed URLs and verify the supporting page before treating a signal as established. Keep the research layer separate from the fields your team maintains:

Context	Store with it	Refresh behavior
Brand profile	Lookup domain, retrieval time, mapped fields	Suggest updates without replacing confirmed edits.
Person candidate	Supplied clues, match outcome, review decision	Recheck identity before replacing role or profile fields.
Public website fact	Source URL, supporting excerpt, observation time	Create a new observation; retain prior evidence.
CRM conversation or rep note	Internal record ID, author, update time	Keep under the CRM’s access and edit rules.
Account score or outreach recommendation	Inputs and application scoring version	Recompute using your own logic.

A careers page can support a statement that a role was listed at an observation time. It does not establish a prospect’s budget, buying intent, or current headcount. Label inferences separately and keep failed checks distinct from a signal disappearing. The resulting account brief can power a personalized sales demo. Context.dev supplies source data; your application joins CRM history, computes an ICP score, and decides when to send outreach.

Keep records useful

Keep the API key in the worker’s server environment.
Verify the CRM webhook signature before accepting an event.
Minimize the email and company data written to logs.
Record the lookup time and source for fields that may become stale.
Give reps a way to correct enriched fields.
Re-enrich on an intentional schedule, not every time a lead record is read.

Retrieve a brand by email

Map work email addresses to company profiles.

Rate limits

Plan throughput and handle rate-limited requests.

API stability

Handle response changes and schema upgrades.

Personalized sales demos

Use reviewed account facts and branding in a prospect-specific preview.

Brand experiences

Sales and content

Web research

Enrich companies and contacts

How it works

Choose CRM fields

Look up the company

Normalize the lookup result

Patch blank fields only

Handle duplicate events

Add person context when the workflow needs it

Attach sourced account research

Keep records useful

Retrieve a brand by email

Rate limits

API stability

Personalized sales demos

​How it works

​Choose CRM fields

​Look up the company

​Normalize the lookup result

​Patch blank fields only

​Handle duplicate events

​Add person context when the workflow needs it

​Attach sourced account research

​Keep records useful

Retrieve a brand by email

Rate limits

API stability

Personalized sales demos

How it works

Choose CRM fields

Look up the company

Normalize the lookup result

Patch blank fields only

Handle duplicate events

Add person context when the workflow needs it

Attach sourced account research

Keep records useful