Skip to main content
GHL MCP Guide
DUP

Duplicate Finder

Contacts & CRM · Basic · Updated March 2026

Look up contacts by email or phone to detect duplicates before creation. Essential for clean CRM data across imports and integrations.

Duplicate contacts are the silent killer of CRM data quality. Two records for the same person means split communication history, missed automation triggers, and inaccurate reporting. The Duplicate Finder lets you check whether a contact already exists before creating a new one, keeping your data clean from the start.

What This MCP Tool Does

This tool provides lookup endpoints to find existing contacts by email address, phone number, or business association. Before creating a new contact through Contact CRUD, you can check whether that person is already in the system. It also lets you retrieve a contact’s appointment history, giving you context on their engagement level.

Endpoint Reference

Look up by email or phone: GET /contacts/lookup Searches for contacts matching the provided email address or phone number. Returns the full contact record if found.

Look up by business: GET /contacts/business/{businessId} Finds contacts associated with a specific business/company record.

Get appointment history: GET /contacts/{contactId}/appointments Retrieves all appointments associated with a contact, providing a full booking history.

Authentication

Requires a Private Integration Token (PIT) with the contacts scope enabled.

Key Parameters

For lookup:

  • email — email address to search for
  • phone — phone number to search for (include country code for best matching)

For appointment history:

  • contactId — the contact’s ID

Important Notes

The lookup endpoint is a simpler, faster alternative to the full contact search when you just need to know if someone exists. Use it before creating contacts from external sources like form submissions, webhook events, or import operations.

If you’re doing high-volume operations, consider using the upsert endpoint on Contact CRUD instead of lookup-then-create. Upsert handles the duplicate check and creation/update in a single call, which is more efficient and eliminates race conditions.

Phone number matching can be tricky. GHL normalizes phone numbers, but inconsistencies in formatting (with or without country code, dashes, spaces) can cause missed matches. Normalize phone numbers to E.164 format before lookup for the most reliable results.

Common Questions

Should I use lookup or upsert to prevent duplicates? If you just need to check existence, use lookup. If you need to create-or-update in one step, use upsert on Contact CRUD. For most integrations, upsert is the better choice because it handles both scenarios atomically.

Can I search by name instead of email or phone? Not through this tool. Name-based searching requires the full contact search endpoint on Contact CRUD with the query parameter.

What happens if there are multiple contacts with the same email? GHL returns all matches. It’s then your responsibility to determine which record is the correct one and handle any necessary merging.

Does this work across sub-accounts? No. Lookups are scoped to a single location/sub-account. If you manage multiple locations, you need to check each one separately.

Back to GHL MCP Guide