Documentation
Confidence and provenance
What field_provenance contains, what each source class means, and how to decide whether to act on a field.
Every field the API returns is accompanied by an entry in field_provenance describing where the value came from, when it was last seen, and how many independent sources agree. A record without that context is a guess presented as a fact, and this API will not hand you one.
"field_provenance": {
"title": { "sources": 3, "class": "corroborated", "last_seen": "2026-08-14" },
"work_email": { "sources": 2, "class": "verified", "last_seen": "2026-08-19" },
"headcount": { "sources": 1, "class": "single-source", "last_seen": "2026-02-03" }
}Source classes
| Class | What it means | How to treat it |
|---|---|---|
| verified | The value passed an active check against the thing itself — for an address, a deliverability check rather than a pattern guess. | The strongest class. Act on it. |
| corroborated | Two or more independent sources produced the same value. | Strong. Independence is the point: three copies of one upstream feed is still one source. |
| single-source | One source, no agreement, no active check. | Usable, but check last_seen before acting. This is where staleness hides. |
| inferred | Derived from a pattern rather than observed — an address built from a company's known format, for example. | A hypothesis. Never present it to a person as a verified fact. |
Recency matters more than the class for some fields
Different fields go stale at different speeds. A job title is worth roughly what it was worth a month ago and much less than that a year on, because people change roles. A company's registered country effectively never changes. Read last_seen against the field, not against a single global threshold.
A rule of thumb
- Verified or corroborated, seen in the last 90 days — act on it.
- Single-source, seen in the last 90 days — act on it where a wrong answer is cheap; verify first where it is not.
- Anything older than a year — treat as a lead to re-check, not as a fact.
- Inferred — never send an email to an inferred address without verifying it first. That is precisely the path that produces bounces.
Why we publish this at all
Two reasons, and neither is marketing. A buyer who cannot distinguish our fresh, corroborated data from a competitor's stale bulk file has no reason to prefer either, so the distinction has to be legible from outside. And provenance is the first question a regulator asks: a field we cannot source is a field we should not be storing.