Contact Reveal (Contact Enrichment)

Contact Enrichment is the motion that turns a known person (identified by a LinkedIn URL) into their verified contact details — work email, personal email, and phone number. It's the step that comes after discovery: you've found the right people (via search, or you already have their LinkedIn URLs), and now you need a way to actually reach them.

The core promise: high-quality contacts that won't bounce. Fiber doesn't just return the first email it finds — it gathers candidates from many sources and then validates them before surfacing them to you.

How contact discovery works

Contact Enrichment isn't a single-database lookup. Fiber blends broad, industry-tuned data coverage with proprietary lookup methods, so the chance of finding each person's real contact info beats any single provider. Just as important: results aren't passed through raw — every email and phone number is validated before it reaches you, so the contacts you receive are ones you can actually use.

This design surfaces one honest tradeoff: speed vs. coverage. A faster, shallower pass costs less; the deepest pass checks everything. Fiber exposes that choice directly through tiers (below), so you pick the right balance for each job.

Enrichment tiers (speed vs. coverage tradeoff)

There are four ways to enrich contacts, from fastest/shallowest to deepest/most-thorough. They share the same inputs (a LinkedIn URL + an enrichmentType selection) and the same per-contact pricing — they differ in latency, coverage, and how many identifiers they handle at once.

Quick Reveal — the standard tier

syncQuickContactReveal — synchronous, balanced speed and cost, ideal for 1–5 profiles at a time. This is the default choice for single-contact lookups.

import { syncQuickContactReveal } from "@fiberai/sdk";

const result = await syncQuickContactReveal({
  body: {
    apiKey: process.env.FIBER_API_KEY!,
    linkedinUrl: "https://www.linkedin.com/in/example",
    enrichmentType: {
      getWorkEmails: true,
      getPersonalEmails: false,
      getPhoneNumbers: true,
    },
  },
});

console.log("Emails:", result.data?.output.profile.emails);
console.log("Phones:", result.data?.output.profile.phoneNumbers);
console.log("Cost:", result.data?.chargeInfo); // authoritative charge

Turbo — the premium fast tier

syncTurboContactEnrichment — synchronous, premium tier optimized for the absolute-fastest response, at the highest cost. Use it when latency matters more than cost (e.g., a live, user-facing reveal where someone is waiting on the result).

Exhaustive — the maximum-coverage pass

triggerExhaustiveContactEnrichment + pollExhaustiveContactEnrichmentResult — an asynchronous flow that runs the deepest, most thorough pass for maximum coverage. You trigger the job, then poll for the result.

Use it as the fallback when the sync tiers (Quick, Turbo) return nothing and you still need contacts — Exhaustive checks the most ground, trading latency for the best possible hit rate.

trigger → (the job runs in the background) → poll until done

Batch — many identifiers at once

startBatchContactDetails + pollBatchContactDetails — an asynchronous batch flow for 10–2,000 identifiers in a single job. Start the batch, then poll for progress/results (or receive a webhook on completion).

Use Batch instead of looping single-reveal calls when you have tens to thousands of rows. For even larger jobs (hundreds/thousands of rows that also need search + export), prefer the Audience workflow, which is purpose-built to scale and control cost/progress.

Enrichment types (what you can request)

Every reveal lets you choose which kinds of contact data to fetch, via the enrichmentType object. This matters for both cost (you only pay for what you ask for and find) and compliance (request only what you need):

"enrichmentType": {
  "getWorkEmails": true,
  "getPersonalEmails": false,
  "getPhoneNumbers": true
}

Returned contacts are typed so you know what you got:

• Emails carry a type such as "work" or "personal".
• Phone numbers carry a type such as "mobile".

A single reveal can return multiple emails and phone numbers per person (e.g., a work email and a personal email), each tagged with its type.

Validation & quality

Fiber validates candidates before returning them, so you're not paying for (or emailing) addresses that bounce.

Email validation — bounce detection

• Every candidate email passes layered validation — Fiber's own algorithms plus independent verification — so only good-quality, deliverable emails are allowed through.
• This dramatically reduces bounce rates on outbound campaigns and protects sender reputation.
• Email bounce detection is also available as a standalone capability (the validation module) for checking emails you already hold.

Phone validation — HLR / CNAM and related lookups

• Phone numbers are validated using HLR (Home Location Register) lookups, CNAM (Caller ID Name) lookups, and other checks to confirm the number is live and well-formed.
• This filters out disconnected or invalid numbers before they reach your dialers.

Contacts that pass validation are the only ones you receive — quality over raw quantity.

Reverse Email Lookup

Capability: resolve an email address → the person's LinkedIn profile (the inverse of normal enrichment). Built on one of the largest verified email↔identity maps in the industry plus proprietary matching, it delivers a 70%+ hit rate on work emails at up to ~3,000 requests/minute for high-volume customers. A reverse phone lookup is also available. See Reverse Email Lookup for the variants (single / bulk / lite), pricing behavior, and advice on getting the best match rates.

Async delivery — webhooks vs. polling

The sync tiers (Quick, Turbo) return inline. The async tiers (Exhaustive, Batch) run in the background — consume their results in one of two ways:

• Poll the corresponding poll… operation until the job is done.
• Webhooks — subscribe to completion events so you don't have to poll:
  • reveal.completed — fires when a contact reveal (email/phone) finishes.
  • batch_contact_enrich.completed — fires when a batch contact enrichment job finishes.

reveal.completed payload (example):

{
  "task_id": "abc123",
  "success": true,
  "emails": [{ "emailAddress": "jane@company.com", "type": "work" }],
  "phone_numbers": [{ "phoneNumber": "+1-555-0100", "type": "mobile" }],
  "linkedin_url": "https://www.linkedin.com/in/jane-doe"
}

Webhooks are delivered signed and auto-retried. See Webhooks & Notifications for setup, the full event catalog, signature verification, and retry behavior.

Credit costs

Contact enrichment is priced per contact found, by data type:

• You pay per contact found, per type. A reveal that returns a work email and a phone number costs 2 + 3 = 5 credits; one that finds nothing for the requested types costs accordingly less.
• Tiers don't change per-contact price. Quick, Turbo, Exhaustive, and Batch use the same per-contact rates above.
• chargeInfo is authoritative. Every response includes output.chargeInfo — always surface that as the real amount charged rather than estimating.
• Check credits first. Use GET /v1/get-org-credits?apiKey=xxx (free) before large jobs.

Choosing the right tier (decision ladder)

For a single known LinkedIn URL:

syncQuickContactReveal           (standard — balanced speed/cost; start here)
   └─ need it faster? →  syncTurboContactEnrichment      (premium, fastest)
   └─ got nothing & need max coverage? →
        triggerExhaustiveContactEnrichment → pollExhaustiveContactEnrichmentResult

For 10–2,000 identifiers:

startBatchContactDetails → pollBatchContactDetails   (async batch)

For hundreds/thousands of rows with search + export:

Use the Audience workflow (createAudience → … → triggerEnrichment → export)

Rules of thumb:

• Start cheap and fast (Quick Reveal); escalate only when needed.
• Escalate to Turbo when latency is the priority (live, user-facing reveals).
• Fall back to Exhaustive only when sync tiers return nothing — it's the deepest (and slowest) pass.
• Batch beats looping single reveals for any meaningful volume.
• Audiences beat raw batch when you also need discovery, live enrichment, validation, and CSV/ad-format exports in one managed pipeline.