A weekly Keap cleanup desk for duplicate contacts and tag sprawl

Build me a Keap data hygiene workbench that my operations person opens for a weekly cleanup session. Keap's native merge tool makes you hunt down and review every duplicate by hand, so this app should do the hunting and the evidence gathering and leave the actual decision to a human. It has two tabs, Duplicates and Tags, plus a running audit log.

The Duplicates tab shows a queue of candidate duplicate pairs ranked by confidence, one card per pair. Each card puts the two contact records side by side and highlights the fields that differ, including email, phone, name, company and address, plus custom field values. Pull the contact data with List Contacts. Custom field values are read and written through the custom_fields array keyed by the field's numeric id, so discover those ids from the contact /model endpoint in order to label each custom field properly in the side by side diff.

Under each record on the card, show the evidence that tells the reviewer which one should survive. Use List orders to show how many orders that contact carries and their total value, List Opportunities to show open and won opportunities, and List Applied Tags (Contact) to show the tags applied to it. A record with order history is almost always the one to keep, so make that obvious at a glance instead of making the reviewer click into anything.

Each pair gets its own Merge button wired to Merge two Contacts. Before any merge runs, show a hard warning that Keap does not carry appointments or deals across a merge: contacts have to be manually added back to any deals, and upcoming appointments need to be cancelled and rescheduled. Where the app already knows about opportunities on the record being merged away, list them by name inside that warning so the reviewer sees exactly what will be lost. The reviewer must explicitly confirm which record is the primary. Never default the primary to the older contact id and never preselect one, and keep the merge button disabled until a primary is chosen. Also give me inline editing on each field wired to Update a Contact, so I can fix a typo or fill in a missing value on the surviving record before merging rather than after.

At the top of the Duplicates tab, a Find duplicates button kicks off a background agent that builds the queue. The agent pages through List Contacts using page_size and page_token, scores candidate pairs on email, phone, name and company similarity, and for each pair recommends a primary based on order history and overall record completeness with a short written reason. It writes the ranked queue back into the app for human approval and must never merge anything itself. Keap allows 1,500 requests per minute, so page steadily and back off exponentially on a 429. Show scan progress and the time of the last completed scan, and keep the previous queue usable while a new scan runs.

The Tags tab is for tag sprawl. List every tag category with List Tag Categories and group the account's tags underneath their category. Build the tag inventory from the applied tag records collected with List Applied Tags (Contact) while the scan pages through contacts, and use List Tagged Contacts when I drill into a single tag to get its exact contact count and the date it was most recently applied. Flag any tag nobody has applied in months as a cleanup candidate and call out tags with zero contacts. From here let me bulk clean: select a set of contacts and apply a standardized tag with Apply Tag, or strip a dead tag from everyone holding it with Remove Tags. The rule I want reflected in the UI is simple: if a tag does not change what happens next, it is clutter.

Every merge and every bulk tag change is appended to a Google Sheets audit log with Append Values, one row each, capturing the timestamp, the reviewer, the action, the contact ids involved, which record was kept and which was merged away, the tag affected and the number of contacts touched. This log is how I prove what changed, so write the row as part of the action, and if a merge or tag change fails, record the failure too rather than silently dropping it.

Persist the candidate queue, each pair's status (merged, dismissed as not a duplicate, or skipped for later) and the scan history inside the app, so a cleanup session can be paused and picked up the following week without rescanning from scratch. Pairs I dismiss as not duplicates should never come back in a later scan.