How to list details of duplicate contacts in Zoho Desk

Retrieving the details of a specific duplicate contact group in Zoho Desk is done through a single authenticated GET request to the deduplication endpoint, passing the relevant duplicate record identifier. Here at Beam Help — independent expert support for Zoho, not official Zoho support — we walk you through exactly how to do that below.

Why this matters

Zoho Desk's Deduplication feature lets you find and merge duplicate contact records in bulk, keeping your helpdesk data clean and well-organised.^[3] Before you can merge or act on duplicates, you often need to inspect the specific records that have been flagged as duplicates. The API endpoint described here gives you programmatic access to those details, which is essential for automation workflows, custom dashboards, or pre-merge validation scripts.

Step-by-step

Step 1. Ensure your OAuth token includes the correct Zoho Desk contacts scope. Your application must be authorised with at minimum Desk.contacts.READ to interact with contact-related endpoints.^[4] Without this scope, the API will reject the request with an authorisation error.

Step 2. Identify the duplicateId you want to inspect. This identifier corresponds to a specific duplicate group that Zoho Desk has already detected through its deduplication process. You can obtain this ID from a prior listing call or from the Deduplication section within your Zoho Desk portal.^[3]

Step 3. Make a GET request to the following endpoint, substituting {duplicateId} with the actual ID of the duplicate group you want to examine:^[1]

GET /api/v1/contactsDeduplication/{duplicateId}

Step 4. Optionally, pass the p parameter as a query parameter in your request. This parameter allows you to control pagination or additional filtering of the returned results.^[1]

Step 5. If you are using the Python client wrapper, call the method as shown below. The duplicateId argument is required; p is an optional dictionary for any additional query parameters:^[1]

result = client.list_details_of_duplicate_contacts(
    duplicateId="your_duplicate_id_here",
    p={"page": 1}  # optional
)

The method internally issues a GET request to /api/v1/contactsDeduplication/{duplicateId}, passing the p dictionary as query parameters and no request body.^[1]

Step 6. Parse the response payload. The returned data will contain the details of the contacts belonging to that duplicate group, which you can then use to decide whether to merge, ignore, or further investigate the records.^[3]

Common pitfalls

• Missing or incorrect scope. If Desk.contacts.READ is absent from your OAuth token, the API call will fail with a permissions error. Double-check your configured scopes before debugging the request itself.^[4]

• Invalid duplicateId. Passing an ID that does not correspond to an existing deduplication group will result in an error response. Always retrieve valid IDs from a prior deduplication listing call rather than constructing them manually.^[1]

• Confusing contact deduplication with ticket merging. The /api/v1/contactsDeduplication/ endpoint is specifically for contact records. Ticket-level duplicate handling is a separate concern and is not covered by this endpoint.^[3][6]

• Pagination not handled. If a duplicate group contains many associated records, results may be paginated. Use the p parameter to iterate through pages and ensure you retrieve the complete dataset.^[1]

What to check

• Scope verification: Confirm that Desk.contacts.READ (and any other required contact scopes) are present and active in your OAuth token before making the request.^[4]
• Valid duplicate ID: Verify that the duplicateId you are supplying was returned by a valid deduplication listing operation and corresponds to an existing group in your Zoho Desk organisation.^[1]
• Response completeness: If you supplied a p parameter for pagination, confirm that you have iterated through all available pages so no duplicate contact details are missed.^[1]