---
title: Enrich people and their photos
description: Optional enrichment for Venom People. "Enrich" on a person, or on many at once, asks the providers your organisation picks (Gravatar, Venom Search, Brave Search, People Data Labs, Apollo) for public facts and a photo, shown as suggestions you apply. Off by default; official APIs only.
section: cloud
order: 168
audience: [user, operator]
sources: ["services/nodejs-cloud/lib/people/enrich", "services/nodejs-cloud/lib/people/tools-enrich.ts", "services/nodejs-cloud/components/people/Enrich.tsx", "services/nodejs-cloud/components/people/EnrichSettings.tsx", "services/nodejs-cloud/app/(people)/people/settings", "services/nodejs-cloud/migrations/0224_people_enrichment.sql"]
features: [cloud.page-people, cloud.migrations]
---

People keeps what you know about someone. Enrichment fills gaps from public sources: their current job, company and
location, links to their public profiles, an About section, and a photo. It never changes a person by itself. What it
finds comes back as **suggestions**, each with the source that said it, and the person's owner applies the ones they want.

## It is off until an owner or admin turns it on

Every provider is a call to another company's API, so enrichment is off by default. An owner or admin turns it on under
**People → Settings** (`/people/settings`, **Enrichment**) or with the `people_enricher_set` tool. Until then
no person's details leave Venom, and the Enrich buttons are not shown.

On the same page they pick the providers, put them in the order they run, set a **daily cap** in US dollars, and store
the organisation's own People Data Labs and Apollo keys. Keys are sealed in the vault, write-only: the page shows only
their last 4 characters. Turning enrichment off deletes every suggestion not applied yet and stops bulk runs.

## The providers, and exactly what each one is sent

Only official APIs are used. No web page is scraped, LinkedIn included, and there is no adapter for a vendor whose data
is scraped from LinkedIn. Each provider is told only what this table says. Phone numbers, notes, tags, how you met and
your interactions are never sent.

| Provider | What it is sent | What it can give | Cost per call |
|---|---|---|---|
| Gravatar | The SHA-256 hash of each of the person's email addresses (up to 3). Not the address. | Photo, job title, company, location, verified accounts | Free |
| Venom Search | The text `<name> <company>`, to the engines your organisation has on in [Venom Search](/docs/cloud/search.md). It runs only while Venom Search is on. | Links to pages that name the person, a photo from a people source (Wikidata, GitHub), a location | What Venom Search books (Brave inside it, about $0.005) |
| Brave Search | The text `"<name>" <company>`, with your organisation's Brave key from Settings, Search, or Venom's key when "Use Venom's keys" allows it | Links to pages that name the person | About $0.005 |
| People Data Labs | Name, company, location, first email address, one profile link (LinkedIn, X or GitHub), with your own key | Current job, company, location, About, profile links | About $0.10 per match (no match is free) |
| Apollo | First and last name, company, first email address, LinkedIn link, with your own key. Personal emails and phone numbers are never asked for. | Title, company, location, photo, profile links | About $0.03 per match |

Search results count as being about the person only when their title or text names every word of the person's name.
A one-word name matches nobody.

The costs of People Data Labs and Apollo are estimates: they bill in credits on your own plan with them. Brave is
booked at its price per request.

## Enrich one person

On a person's page, **Enrich** sits at the top right next to **Add snapshots**. It asks each provider in your order and
opens the **Enrichment** section with what would change:

- a different role, company or location (changed values first, then new ones), new links (LinkedIn, X, websites) and an
  About section, each with the providers that said it;
- photo candidates as round thumbnails. Venom fetches them for you, so your browser never calls the provider's site.
  Click one to see it full size, tick the one to use.

Everything is ticked except the photo. Untick what you don't want and choose **Apply**, or **Dismiss**. When two
providers disagree on a role, the first in your order wins. Applying never clears a field. A photo you apply is fetched
once and kept with the person, like a card photo. Only the person's owner enriches them.

The suggestions stay on the person until you apply or dismiss them, or until the next Enrich replaces them.

## Enrich many people

Select people in the list (or **Select all N matching**), then **More → Enrich N people** (on a phone, **Actions**). The
dialog shows a progress bar, how many people have suggestions, what the run has cost and today's spend against the cap.
You can close it and keep working: the run goes on while the page is open, and a message says when it is done. When it
ends, it lists the people with suggestions; review each on their page. People someone else owns are left out.

A run stops when the daily cap is reached and every picked provider is paid. Free ones (Gravatar) keep going.

## A photo from a snapshot

When you read snapshots on a person's page (**Add snapshots**, **Read all**), the read also says where the person's own
profile photo is in a screenshot, such as the picture at the top of a LinkedIn profile or next to a name in a chat. The
page cuts it out in your browser and offers it as a **Photo** suggestion with the rest. It is ticked when the person has
no photo yet. This uses only images you already added: no call goes anywhere else. Agents set a photo with
`people_person_photo_set`.

## Spend and the daily cap

Each paid call is added to the organisation's day (UTC) and checked against the cap before it starts. Calls show in
Requests and Usage as `/people/enrich` (model `people-enrich`, the provider as upstream). Venom Search books its own
searches as `venom-search`.

## For agents and scripts

| Tool | REST | What it does |
|---|---|---|
| `people_enricher_get` | `GET /api/v1/people/enrichment/setting` | On or off, the providers in order with what each is sent, the cap, today's spend |
| `people_enricher_set` | `PUT /api/v1/people/enrichment/setting` | Owners and admins: switch, providers, cap, PDL and Apollo keys |
| `people_person_enrich` | `POST /api/v1/people/{person}/enrich` | Enrich one person; answers numbered suggestions and photo candidates |
| `people_enrichment_get` | `GET /api/v1/people/{person}/enrichment` | The pending suggestions |
| `people_enrichment_apply` | `POST /api/v1/people/{person}/enrichment/apply` | Apply `picks` (numbers) or `apply: "all"`, and optionally `photo` |
| `people_enrichment_dismiss` | `DELETE /api/v1/people/{person}/enrichment` | Dismiss them |
| `people_enrichment_run` | `POST /api/v1/people/enrichment/runs` | Start a run with `people`, continue it with `run` until it is done |
| `people_person_photo_set` | `PUT /api/v1/people/{person}/photo` | Set a photo: an image (base64) or a photo candidate's URL |

`people_person_enrich` and `people_enrichment_run` answer "off for this organisation" while enrichment is off, and send
nothing.
