Bulk Contact Update & Merge documentation

Requirements

• A Freshdesk account on a plan with API access (Growth, Pro or Enterprise). The Free plan has no API access, so the application cannot work there.
• For installation: the API key of an agent with administrator rights (Profile settings, Your API key).
• To open the application: your agent email address on the application's allowed list.

Installation

The installation page asks for four settings: your Freshdesk domain (acme.freshdesk.com), an administrator's API key, the email addresses of the agents allowed to open the application, and how many API requests per minute it may use (default 40, at most 50).

The key is stored as a Freshworks secure installation parameter: the platform adds it to outbound request headers and it never reaches the browser. Anyone not on the allowed list sees only Access denied.

Bulk update

• Contacts: Load contacts reads every contact once (100 per request). On a large account this takes a few minutes; at most 30,000 contacts are loaded.
• Filter: add conditions on company, email domain, language, time zone, job title, name, email, phone, mobile, created or updated date, or a custom field. All conditions must match. Tags cannot be filtered on, because the contact list does not include them.
• Select all matching contacts or tick them one by one, choose the action and press Preview changes.
• The preview shows each change from the old to the new value, the skipped contacts and the reason, and the estimated time. Run starts the job; more than 50 contacts shows an extra warning.
• Tags and company ticket visibility: the application reads each selected contact first (one request per contact) so the change starts from the contact's real tags.

Jobs, undo and the change log

• A job writes one contact at a time and saves its progress every 10 contacts or 15 seconds. Pause stops at the next contact; Resume continues.
• If you close the tab, the job is shown as Interrupted under Jobs and Resume continues from the last saved contact.
• Undo this job writes the previous values back, only for contacts that were changed successfully. Undo is not offered for merges.
• Log downloads the change log of any job of the last 30 days as CSV: job, type, who ran it and when, contact ID, result, the new values and the previous values.

Duplicates and merge

• Duplicates searches the loaded contacts. Email addresses are unique in Freshdesk, so the rules are: same phone or mobile number, same name and same email domain (free mail domains are ignored), and same name and same company.
• Each group suggests the contact to keep: the one with the most filled-in fields, then the oldest, then the lowest ID. You can change it and untick contacts. One merge keeps one contact and merges at most five into it.
• Review selected merges reads every contact in the chosen groups again and shows each request: the values sent to Freshdesk (when phone, mobile, Twitter handle or external ID are set on both sides, Freshdesk requires one value and the kept contact's value is used; every email address is kept as an additional email) and the values that will not be kept.
• Download backup saves a CSV and a JSON file with the full records of every contact in the merges. Only then can you type MERGE, and only the exact word unlocks Merge contacts.
• After a merge, load contacts again before the next job.

Limits you should know

• Requests count against your Freshdesk account's API limit (for example 100 per minute on Growth). The application stays under the rate you set, pauses for a minute when less than 30% of the account limit is left, and waits as Freshdesk asks when it is rate limited.
• A job runs only while the tab is open. At 40 requests per minute, 300 contacts take about 8 minutes.
• Contacts that changed in Freshdesk after you loaded them are written from the values shown in the preview. Load again before a large job if others are editing contacts at the same time.
• Freshdesk merges cannot be reversed. Keep the backup files.