contact_data_enrichment

Enrich contact records with verified email addresses and phone numbers. Each contact enrichment consumes paid credits (1 credit per contact per data type), so this is the only OnFire MCP tool with a strict two-phase consent flow.

When to use it

• “Get emails for these 40 contacts.”
• “Pull email and phone for the prospects I just scored.”
• Standard follow-up after ai_prospecting — hand the run’s dataset_id straight in.

If rows don’t have LinkedIn URLs yet, run match_person first.

The two-phase consent flow (> 10 contacts)

Phase 1 — consent

Call with total_count=N and contacts=[] (empty list). The server returns a confirmation_required response:

{
  "status": "confirmation_required",
  "contact_count": 40,
  "credits_to_consume": 80,
  "data_types_requested": ["email", "phone"],
  "confirmation_token": "<opaque>",
  "max_batch_size": 20,
  "user_facing_message": "Enriching 40 contacts with email and phone data will consume 80 credits. Do you want to proceed?"
}

The agent must display user_facing_message verbatim and wait for an explicit user approval before continuing.

Phase 2 — batched enrichment

After approval, send contacts in batches of up to 20 per call. Each call must include confirmation_token and the matching total_count.

Small batches (≤ 10)

Skip phase 1 — just pass the contacts directly.

Inputs

Parameter	Type	Required	Description
contacts	object[]	Yes*	Up to 20 rows per call. Empty list for phase 1.
linkedin_url_column	string	Yes	Column in each row that holds the LinkedIn URL.
account_website_column	string	Yes	Column that holds the company website.
person_name_column	string	Yes	Column that holds the person’s full name.
include_email	boolean	No	Default true. At least one of include_email / include_phone must be true.
include_phone	boolean	No	Default true.
total_count	integer	Phase 1 + large batches	Total contacts to enrich.
confirmation_token	string	Large batches	The opaque token returned by phase 1.
dataset_id	string	Alt. to contacts	Handle to a dataset produced by a previous tool call.
offset	integer	Dataset mode	Starting row.
limit	integer	Dataset mode	Number of rows to pull. Capped at 20 per call.
target_tenant_id	string	No	Super tenants only.

* Use either contacts (inline) or dataset_id + offset / limit (server-side dataset), not both.

Returns

Phase 1. JSON envelope with status="confirmation_required", cost details, and the confirmation_token.

Phase 2. JSON with total_count, enriched_count, rows, and truncated. Each row is the original contact record with email and/or phone appended.

Notes & limits

• Max 20 contacts per call, enforced server-side.
• The confirmation token expires after roughly 5 minutes.
• Do not fabricate the token. Do not paraphrase user_facing_message. Do not treat the original user request as approval — only an explicit “yes” after seeing the cost counts.
• Dataset passthrough is the canonical path after an ai_prospecting run. Set total_count from the run’s filtered_prospects (or dataset.row_count).