Contact Enrich

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Use only after contact_search (2 credits per call) has identified the person — do not use for open-ended discovery. Enrich a KNOWN person: return their email, phone, seniority/title, social profiles, and employment history. Sourced from EXTERNAL contact providers — Apollo and ZoomInfo — NOT the HG Insights data API. Requires an Apollo or ZoomInfo integration; provider availability is org-specific (commonly Apollo only). Leave provider on 'auto' (default); naming an unconfigured provider returns a hard error, so check the response's availableProviders. Use this when you already have a specific contact and want their missing details — pass a contactId from contact_search (most accurate), an email, a LinkedIn URL, or a first+last name with company domain/name. Batch up to 25 people via contacts for bulk enrichment. Do NOT use this to DISCOVER people you don't know yet (e.g. "find the VPs of Marketing at Cisco") — use contact_search for that, then enrich the best matches by id. BULK omits unmatched contacts from the returned array entirely (no placeholder) — read metadata.matchCount and compare results by id/name, never by array position. USES CREDITS, billed per requested reveal, per MATCHED contact: 0.2 per email + 2 per phone. revealPhone defaults to TRUE, so unless you pass revealPhone:false every matched contact is billed 2.2 (10x an email reveal) — set revealPhone:false when you only need email/firmographic data. No-match calls cost 0; response metadata.dynamicCreditCost reports the actual charge. Do NOT re-enrich a contact already in context — credits are charged per call regardless of whether data changed.

Credits

0.2 / 2 — 0.2 per email reveal, 2 per phone reveal (phone is opt-in). See the full credit table for how AI Credits work.

Parameters

Name	Type	Default	Description
contactId	string	-	Provider contact ID returned by contact_search — a 24-character hex string (e.g. '54a797027468696b7f8f9d42'). Most accurate identifier: resolves an exact person with no matching ambiguity. Reuse the id from search rather than constructing one, and pass the same provider that produced it.
firstName	string	-	Contact's first (given) name. Combine with lastName and a company domain/name so the provider can resolve the right person.
lastName	string	-	Contact's last (family) name. Combine with firstName and a company domain/name so the provider can resolve the right person.
email	string	-	Contact's work or personal email, if known. A strong standalone matcher — sufficient on its own to reverse-lookup the rest of the profile.
companyDomain	string	-	Current employer's website domain (e.g. 'stripe.com'). Pair with firstName+lastName to disambiguate common names; preferred over companyName. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
companyName	string	-	Current employer's name (e.g. 'Stripe'). Use only when the domain is unknown — companyDomain resolves more reliably.
linkedinUrl	string	-	Contact's LinkedIn profile URL. A strong standalone matcher — sufficient on its own to identify the person.
contacts	array	-	Array of known contacts to enrich in one call (max 25), each identified the same ways as a single enrichment (id, email, linkedinUrl, or name + company). Cheaper and faster than one call per person; mutually exclusive with the single-contact fields above. Unmatched rows are omitted from the returned array — compare results by id/name, never by array position.
contacts[].id	string	-	Provider contact ID (from contact_search) for this row. Most accurate matcher for a bulk item.
contacts[].firstName	string	-	Contact's first (given) name; pair with lastName and a company domain/name.
contacts[].lastName	string	-	Contact's last (family) name; pair with firstName and a company domain/name.
contacts[].email	string	-	Contact's email, if known — a strong standalone matcher for this row.
contacts[].companyDomain	string	-	This contact's current employer domain (e.g. 'salesforce.com'); preferred over companyName. Protocol prefixes (http://, https://), leading www., and trailing paths/queries/fragments are accepted and stripped automatically; case is normalized.
contacts[].companyName	string	-	This contact's current employer name; use only when the domain is unknown.
contacts[].linkedinUrl	string	-	Contact's LinkedIn profile URL — a strong standalone matcher for this row.
revealEmail	boolean	true	Whether to reveal email addresses (default: true)
revealPhone	boolean	true	Whether to attempt a phone reveal. Defaults to TRUE, so a default enrich call is billed the 2-credit phone fee on every matched contact (10x an email reveal), charged for the attempt whether or not a phone value is returned. Pass false when you only need email/firmographic data.
provider	string	auto	Contact data provider. Prefer "auto" (default), which selects an available provider. "apollo" or "zoominfo" target a specific provider, but requesting one your org has not configured returns a hard error rather than falling back — check availableProviders in the response.

Required Integrations

This tool is only available when your organization has the following integrations configured in the Phoenix Integrations settings:

• Apollo.io (apollo)
• ZoomInfo (zoominfo)

Use Cases

• I have a contactId from contact_search — get this person's email and phone
• Enrich a known person by first+last name plus their company domain (e.g. Jane Doe at cisco.com)
• Reverse-lookup a person from just their email address to fill in title, company, and LinkedIn
• Enrich a batch of up to 25 known contacts in one call instead of enriching one at a time
• Get only email/firmographic data without paying the phone fee (set revealPhone: false)

Example Usage

Enrich by contactId from contact_search (most accurate)

{
  "tool": "contact_enrich",
  "arguments": {
    "contactId": "54a797027468696b7f8f9d42"
  }
}

Enrich by name + company domain, email only (skip the phone fee)

{
  "tool": "contact_enrich",
  "arguments": {
    "firstName": "Jane",
    "lastName": "Doe",
    "companyDomain": "cisco.com",
    "revealPhone": false
  }
}

Reverse-lookup by email, include phone

{
  "tool": "contact_enrich",
  "arguments": {
    "email": "jane.doe@cisco.com",
    "revealPhone": true
  }
}

Response Format

Field	Type	Description
contact	object	Enriched contact data (single enrichment)
contact.id	string	Contact ID
contact.firstName	string | null	First name
contact.lastName	string | null	Last name
contact.name	string | null	Full name
contact.title	string | null	Job title
contact.seniority	string | null	Seniority level
contact.email	string | null	Email address (if revealed)
contact.emailStatus	string | null	Email verification status
contact.personalEmails	array | null	Personal email addresses
contact.phone	string | null	Primary phone number
contact.mobilePhone	string | null	Mobile phone number
contact.corporatePhone	string | null	Corporate phone number
contact.linkedinUrl	string | null	LinkedIn profile URL
contact.twitterUrl	string | null	Twitter/X profile URL
contact.facebookUrl	string | null	Facebook profile URL
contact.githubUrl	string | null	GitHub profile URL
contact.organization	object	Organization information
contact.organization.id	string	Organization ID
contact.organization.name	string	Company name
contact.organization.domain	string | null	Company domain
contact.organization.industry	string | null	Industry
contact.organization.employeeCount	number | null	Employee count
contact.organization.revenue	number | null	Annual revenue
contact.organization.location	string | null	Company location
contact.organization.linkedinUrl	string | null	Company LinkedIn URL
contact.organization.website	string | null	Company website
contact.employmentHistory	array	Employment history
contact.employmentHistory[].organizationName	string | null
contact.employmentHistory[].title	string | null
contact.employmentHistory[].startDate	string | null
contact.employmentHistory[].endDate	string | null
contact.employmentHistory[].isCurrent	boolean
contact.city	string | null	City
contact.state	string | null	State/Region
contact.country	string | null	Country
contacts	array	Enriched contacts (bulk enrichment)
contacts[].id	string	Contact ID
contacts[].firstName	string | null	First name
contacts[].lastName	string | null	Last name
contacts[].name	string | null	Full name
contacts[].title	string | null	Job title
contacts[].seniority	string | null	Seniority level
contacts[].email	string | null	Email address (if revealed)
contacts[].emailStatus	string | null	Email verification status
contacts[].personalEmails	array | null	Personal email addresses
contacts[].phone	string | null	Primary phone number
contacts[].mobilePhone	string | null	Mobile phone number
contacts[].corporatePhone	string | null	Corporate phone number
contacts[].linkedinUrl	string | null	LinkedIn profile URL
contacts[].twitterUrl	string | null	Twitter/X profile URL
contacts[].facebookUrl	string | null	Facebook profile URL
contacts[].githubUrl	string | null	GitHub profile URL
contacts[].organization	object	Organization information
contacts[].organization.id	string	Organization ID
contacts[].organization.name	string	Company name
contacts[].organization.domain	string | null	Company domain
contacts[].organization.industry	string | null	Industry
contacts[].organization.employeeCount	number | null	Employee count
contacts[].organization.revenue	number | null	Annual revenue
contacts[].organization.location	string | null	Company location
contacts[].organization.linkedinUrl	string | null	Company LinkedIn URL
contacts[].organization.website	string | null	Company website
contacts[].employmentHistory	array	Employment history
contacts[].employmentHistory[].organizationName	string | null
contacts[].employmentHistory[].title	string | null
contacts[].employmentHistory[].startDate	string | null
contacts[].employmentHistory[].endDate	string | null
contacts[].employmentHistory[].isCurrent	boolean
contacts[].city	string | null	City
contacts[].state	string | null	State/Region
contacts[].country	string | null	Country
metadata	object	Enrichment metadata
metadata.creditsUsed	number	Credits consumed (equals dynamicCreditCost)
metadata.dynamicCreditCost	number	Credits actually charged (matches × 3; 0 on no-match)
metadata.matchConfidence	string	Match confidence level
metadata.enrichedAt	string	ISO timestamp of enrichment
metadata.noMatchReason	string	Reason when no matching contact was found
metadata.enrichmentType	string	Type of enrichment performed
metadata.provider	string	Contact data provider used (e.g., apollo, zoominfo)
metadata.usedProvider	string	Which provider fulfilled this request
metadata.availableProviders	array	Providers configured for the organization

Related Tools

contact_search, company_firmographic, search_companies