contact_data_enrichment

contact_data_enrichment takes contact rows — from ask_onfire, an ai_prospecting run, a CRM export, or a single named person — and appends verified professional emails and phone numbers.

This is a paid tool. Above 10 contacts it enforces a two-phase consent flow that the agent must complete before any contacts are sent.

When to use it

• The user asks for emails or phones for a list of people.
• As the standing follow-up to a prospecting run — hand the run’s dataset_id straight to this tool instead of rebuilding contact dicts.

Inputs

Parameter	Type	Required	Description
contacts	object[]	Yes*	Contact dicts, max 20 per call. Empty list for the phase-1 consent call.
dataset_id	string	Yes*	Enrich straight from a dataset instead of passing contacts.
offset	integer	No	Pagination offset into the dataset. Default 0.
limit	integer	No	Max rows to enrich from the dataset in one call. Capped at 20.
linkedin_url_column	string	No	Column holding LinkedIn URLs. Auto-detected when omitted.
account_website_column	string	No	Column holding company websites.
person_name_column	string	No	Column holding person full names.
linkedin_url	string	No	Single-contact shortcut — one LinkedIn profile URL.
account_website	string	No	Single-contact shortcut — one company website.
person_name	string	No	Single-contact shortcut — one person’s full name.
include_email	boolean	No	Append an email column. Default true.
include_phone	boolean	No	Append a phone column. Default true.
total_count	integer	No	Total contacts to enrich. Required for phase 1 and every phase-2 batch.
confirmation_token	string	No	Server-issued token from phase 1. Required for phase-2 batches when the total is >10.
continuation_token	string	No	Resume handle from a still_running response.
target_tenant_id	string	No	Super tenants only.

* Provide contacts, dataset_id, or the single-contact shortcut fields.

The single-contact shortcut needs all three of linkedin_url, account_website, and person_name — a LinkedIn URL alone cannot be enriched.

The consent flow

10 contacts or fewer — skip both phases. Pass contacts directly, no token needed.

More than 10 contacts:

1. Phase 1 (consent). Call with contacts=[] and total_count=N. The response is confirmation_required with a user_facing_message and a confirmation_token. The agent must show that message verbatim, stop, and wait for an explicit approval. The original request is not approval.
2. Phase 2 (batches). Send contacts in batches of 20 or fewer, passing the confirmation_token and total_count on every call, until done.

Confirmation tokens are valid for about five minutes and must never be fabricated. Batches over 20 are rejected.

Async runs

A call that can’t finish inside the request budget returns {"status": "still_running", "continuation_token": "..."}. Call again with the same contacts / column arguments plus that token to resume the same run.

Returns

• Phase 1: confirmation_required, with the cost details and the token.
• Phase 2 / small batch: total_count, enriched_count, rows, truncated. Each row is the original contact data plus email and/or phone.

Notes & limits

• Paid per contact per data type. Frame volume to the user as batch size, never as cost or credits.
• Max 20 contacts per call; larger jobs are chunked after the consent step.