Weekly phone enrichment for new sales-qualified leads

Build an agent workflow that fills in missing phone numbers for our SDR team's outbound dial list. Run it on a cron trigger every Thursday at 9:00 AM America/New_York.

Step 1: pull the target contacts from HubSpot. Use HubSpot Search Contacts with these filters: lifecyclestage equals salesqualifiedlead AND phone is null AND createdate is within the last 60 days. Request these properties at minimum: email, firstname, lastname, company, linkedin_url (or hs_linkedin_url if that is what the portal uses), phone, mobilephone, phone_source, phone_enriched_at, hubspot_owner_id, and associated deal info if available. Paginate until you have the full set. The CRM search endpoint is capped around 10,000 results, which is plenty for this use case.

Step 2: filter out anyone already enriched recently. Skip any contact whose phone_enriched_at timestamp is within the last 30 days. If the property does not exist yet, treat it as unset and proceed.

Step 3: enrich each remaining contact with Waterfall.io Phone Enrichment. Waterfall.io evaluates only ONE identifier per request, so pick the highest-priority one available per contact in this order: (1) email, (2) LinkedIn URL, (3) full name plus company domain (derive the company domain from the contact's email if the company field is missing). Phone Enrichment is async and is charged only when a phone is actually returned. Use the webhook_url parameter if convenient, otherwise poll the finder endpoint with light exponential backoff.

Step 4: respect Waterfall.io's rate limit of 50 requests per 60 seconds. Group contacts by company and pace requests so we never exceed the budget. On any 429 response, honor the Retry-After header. If a job comes back FAILED or TIMED_OUT, retry once with backoff; if it still fails, count it as a miss and move on.

Step 5: write back to HubSpot. When Waterfall.io returns a phone number with high confidence, call HubSpot Update Contact and set: phone (use the best direct-dial number, or the mobile if that's all we have), mobilephone (the mobile number if returned), phone_source = "Waterfall.io", and phone_enriched_at = the current ISO 8601 timestamp. Do not overwrite phone or mobilephone if they are already non-empty. If only mobile came back, fill mobilephone and leave phone untouched. If the confidence is low or no phone is returned, do not update anything.

Step 6: post a single end-of-run summary using Slack Bot Send a Message to the #sdr-ops channel. The summary should include: total contacts considered, count enriched (split into direct dial vs mobile-only), count with no phone returned, count skipped because they were already enriched in the last 30 days, and a top 5 list of "newly dialable accounts" ranked by the highest associated open deal value. For each top account, show the company name, the contact name, the new number, and the deal value. Format the message with Slack mrkdwn (bold headers, bullet points) so it is easy to scan.

Notes for the agent:

- If the HubSpot account does not yet have phone_source and phone_enriched_at custom properties on contacts, surface a clear setup error in the run log so the user can create them once. Do not attempt to create the properties automatically.

- Be conservative with credit spend: never re-enrich a contact you already processed in the same run, even if it appeared twice.

- The whole run should complete in well under an hour for a typical SDR queue (a few hundred contacts). If the lead set ever exceeds a few thousand, batch and continue across the rate-limit window rather than failing.