Duplicate Finder Setup

Detect and prevent duplicate contacts before they fragment your CRM data. This quick-start shows you how to look up contacts by email or phone, check business associations, and verify your deduplication logic.

Prerequisites

Before using the Duplicate Finder endpoints, confirm you have:

• A GoHighLevel sub-account with existing contacts that may contain duplicates
• A Private Integration Token with the contacts scope configured
• Known email addresses or phone numbers to test lookups against
• A REST client such as Postman, Insomnia, or curl

Set Up Authentication

Duplicate Finder uses the same authentication as all contact endpoints. You need a Private Integration Token (PIT) with the contacts scope.

If you already have a PIT from a previous setup, reuse it. Lookup operations are covered under the same contacts scope.

If you need a new token, navigate to Settings > Integrations > Private Integrations in your sub-account. Create a new integration, enable the contacts scope, save, and copy the token.

Set your Authorization header to Bearer {your-pit-token} for all requests. Your base URL is https://services.leadconnectorhq.com.

Make Your First Call

The primary endpoint for duplicate detection is contact lookup. Send a GET request to /contacts/lookup with an email or phone query parameter:

GET /contacts/lookup?locationId={locationId}&[email protected]
Authorization: Bearer {your-pit-token}

You can also search by phone:

GET /contacts/lookup?locationId={locationId}&phone=+15551234567

The locationId parameter is required to scope the search to your sub-account. The endpoint returns all contacts matching the provided email or phone, making it easy to spot duplicates.

To check a contact’s business association, use GET /contacts/business/{businessId}. To list a contact’s appointments (useful for verifying the right record), use GET /contacts/{contactId}/appointments.

Handle the Response

A successful lookup returns a 200 status with an array of matching contacts:

{
  "contacts": [
    {
      "id": "contact-abc123",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+15551234567",
      "dateAdded": "2026-01-15T10:00:00Z"
    },
    {
      "id": "contact-def456",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+15559876543",
      "dateAdded": "2026-02-20T14:30:00Z"
    }
  ]
}

If the array contains more than one contact, you have duplicates. Compare dateAdded to identify the original record. Check which record has more complete data (tags, notes, appointments) to decide which to keep as the primary.

Common errors: 400 means you are missing the locationId or both email and phone parameters. 401 means your token is invalid. An empty contacts array means no match was found, which confirms the contact is unique.

Test Your Setup

Run through this checklist to confirm duplicate detection is working:

1. Look up by email with GET /contacts/lookup?locationId={id}&[email protected] and check how many contacts match
2. Look up by phone with GET /contacts/lookup?locationId={id}&phone=+1555... and compare results
3. Cross-reference the results. If both lookups return different contact IDs for the same person, you have a fragmentation issue
4. Test a unique contact by looking up an email you know only exists once. Confirm the array contains exactly one result
5. Integrate with upsert by using POST /contacts/upsert for new contact creation. This prevents duplicates at the point of entry

Build duplicate detection into your intake flow. Before creating a contact via POST /contacts, run a lookup first. If matches exist, update the existing record instead of creating a new one, or use the upsert endpoint to handle this automatically.

Next Steps

Read the full Duplicate Finder Guide for advanced deduplication strategies and merge workflows. Combine lookup with Contact CRUD upsert to prevent duplicates automatically, or use Contact Fields to enrich the surviving record with data from duplicate entries.