You have a spreadsheet of 500 Instagram handles from a discovery run, and every one of them is a dead end until you can reach a person. The bio says "collabs: link in bio", the link is a Linktree, the Linktree points to a website, and the address is on its contact page. Doing that by hand for 500 creators is a week of opening tabs.
/v1/contacts/find does that walk in one call. Send a handle (or a website, an email, a name), get back the creator's addresses ranked by type and confidence, each with the page it was found on and an MX check. This guide covers the two levels, how the stored answer works, how to run a list without overspending, and how to send the email without breaking the law.
What the endpoint looks for, in order
| Priority | Source | Where the address was found |
|---|---|---|
| 0 | bio | Written in the profile bio |
| 1 | platform_business_email | The platform's business or contact email field |
| 2 and up | discovered | A page the creator links to or owns: link-in-bio page, website, contact or legal page |
emails[] comes back ranked, so the first entry is the best one to use, and best_email names the first one you can contact. A business or management address the creator wrote out ranks above a support inbox found on a website.
An address needs proof before it is published
A page can list many addresses: the creator's, their agency's, a web designer's, a support desk. The finder returns an address only when its evidence ties it to the creator, and says whose it is in owner: the creator, a representative, a parent company. An address that no evidence ties to the creator is never returned, and an address nobody should write to, such as a no-reply, comes back with contactable: false. When nothing passes, best_email is null and the call is free.
Fast or thorough
| Level | Path | What it reads | Time | Cost |
|---|---|---|---|---|
| Fast | /v1/contacts/find/fast | The stored answer, the profile, the bio and the link pages the creator declares, typed by rule | within 2 s | $0.02 |
| Thorough | /v1/contacts/find/thorough | The fast read plus sibling accounts on other platforms, contact and legal pages on the creator's domain and one web search, ranked by one model call | within about 30 s | $0.05 |
The path picks the level: /v1/contacts/find/fast or /v1/contacts/find/thorough, and /v1/contacts/find-from-instagram/fast and its TikTok and YouTube siblings take one handle as q. The bill and the usage log name the operation that ran. On our hand-checked validation set of 60 creators (November 2026), fast found 52% of the addresses with no wrong one, and thorough found 77% at precision 0.97. Only thorough calls a model, once per lookup.
Look up one creator
q takes a username, an @handle, or a profile URL. platform is instagram (default), tiktok, or youtube. YouTube handles keep their case and also accept a UC... channel id.
curl "https://api.virev.ai/v1/contacts/find-from-instagram/thorough?q=mrbeast" \
-H "Authorization: Bearer $VIREV_API_KEY"const res = await fetch(
"https://api.virev.ai/v1/contacts/find-from-instagram/thorough?q=mrbeast",
{ headers: { Authorization: "Bearer kb_live_..." } }
);
const { data, meta } = await res.json();
console.log(data.best_email); // "chucky@mrbeastbusiness.com"
console.log(data.emails[0]);
// { address: "chucky@mrbeastbusiness.com", rank: 1, type: "business", contactable: true,
// confidence: 0.95, evidence: [{ url: "https://www.youtube.com/@mrbeast", where: "yt_about", ... }],
// verification: { mx: "present", smtp: "unchecked", ... } }
console.log(data.run.stored.hit); // false
console.log(meta.cost); // "$0.0500"Everything sits under data. outcome is found, none_found or unknown_subject, and best_email is the first active address you can contact. Each entry in emails[] has the address, its rank, its type (business, management, press, support, personal and so on), whether it is contactable, a confidence, its owner (the creator, their representative, a parent company), its evidence (each page with the quote it came from) and a verification object: mx (the mail-route check) and smtp (the mailbox probe). The answer also lists the creator's linked handles on other platforms, websites, link_pages and phones. run reports the level, the pages read, any model call with its cost, and the steps skipped.
Fast reads only what the creator declares, so a creator whose address sits on another platform comes back empty from fast. Thorough checks the same creator on YouTube and TikTok too, and finds a business address written on a channel page.
POST form
curl -X POST "https://api.virev.ai/v1/contacts/find/fast" \
-H "Authorization: Bearer $VIREV_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "handles": [{ "platform": "tiktok", "handle": "khaby.lame" }], "websites": ["khabylame.com"] }'The body is strict
The body is the subject: any of handles, urls, emails, websites, phones and name, plus freshness. Unknown fields are rejected with a 400, and validation runs before auth and billing, so a malformed request is never charged. One request looks up one creator; send one request per creator.
Cache and refresh
Every address we find is stored against the creator's profile, one entry per address, with the pages it came from. With freshness=auto (the default), a creator we already ran comes back from the stored answer when it is fresh enough, with run.stored.hit true and run.stored.last_run_at. No page is fetched. Pass freshness=refresh to run again, for example after a creator changes their link in bio, or freshness=stored to answer only from the store.
The price does not depend on the stored answer: a stored answer and a fresh run cost the same, and a lookup with no contactable email is free.
Pair it with the profile bundle
If you're building an outreach pipeline, /v1/intelligence/profile is the other half of the workflow. It returns the classification bundle (account_role, primary_niche, commercial_intent, brand_safety), which tells you whether to reach out. contact tells you where. Classify first, then look up contacts only for creators that fit.
import requests
HEADERS = {"Authorization": "Bearer kb_live_..."}
profile = requests.get(
"https://api.virev.ai/v1/intelligence/profile",
params={"q": "natgeo"},
headers=HEADERS,
).json()["data"]
if "travel" in (profile["primary_niche"] or "").lower():
contact = requests.get(
"https://api.virev.ai/v1/contacts/find-from-instagram/thorough",
params={"q": "natgeo"},
headers=HEADERS,
).json()["data"]
print(contact["best_email"]) # $0.05 spent only on a qualified leadEnrich a list without overspending
Real outreach starts from a list. One way to keep the bill down: run fast on every handle, then run thorough only on the handles where fast found nothing, which cost nothing the first time. Respect the 100 req/min default rate limit (a 429 carries a Retry-After header). A non-200 is never charged, so a failed lookup costs nothing and can be retried.
import requests, time
BASE = "https://api.virev.ai/v1/contacts/find-from-instagram"
HANDLES = ["natgeo", "nasa", "bbcearth"] # from your discovery run
HEADERS = {"Authorization": "Bearer kb_live_..."}
def lookup(handle, level):
while True:
res = requests.get(f"{BASE}/{level}", params={"q": handle}, headers=HEADERS)
if res.status_code == 429:
time.sleep(int(res.headers.get("Retry-After", 5)))
continue # a non-200 is not billed
if res.status_code != 200:
return None # log and move on; you were not billed
return res.json()["data"].get("best_email")
rows = []
for handle in HANDLES:
email = lookup(handle, "fast") # $0.02, free when it finds none
if email is None:
email = lookup(handle, "thorough") # $0.05, only on misses
rows.append({"handle": handle, "email": email})
print(f"Looked up {len(rows)} creators")Cost anchors for planning a run: 1,000 creators is at most $50 on thorough, or $20 on fast, and a lookup that finds no email is free. Fast first, then thorough on the misses, lands lower: if fast finds an address for 520 of the 1,000, the run costs $10.40 plus at most $24. Qualifying with /v1/intelligence/profile at $0.05 first shrinks the list before either. The starter offer, pay $1 and get a $5 balance, covers about 100 thorough lookups or 250 fast ones.
Send the email without getting burned
Finding the address is the easy part. These are business contact points creators published so brands could reach them, but publishing an address is not consent to receive bulk mail, and the law treats it that way.
- CAN-SPAM (US): use accurate
From/Subjectheaders, include a real physical mailing address, and provide a working unsubscribe that you honor within 10 business days. - GDPR (EU recipients): you can rely on legitimate interest for B2B outreach, but you must offer a clear opt-out and stop on request. Keep a record of why you contacted them.
- Relevance over volume: use the
brand_fit_summaryandcontent_tagsyou already pulled to send something specific. A creator who gets a personal, on-niche pitch replies; one who gets a mail-merge blast blocks you. - Verify before a big send: the MX check tells you the domain takes mail, not that the mailbox exists. Run the list through your ESP's validation step to catch bounces before they hurt your sender reputation.
Discovery gives you the address. Etiquette gives you the reply. Treat every send as if the creator will screenshot it.
Turn handles into inboxes
Pay $1, get a $5 balance: about 100 thorough contact lookups or 100 profile classifications. No subscription, no minimum.
Get your API key →