Screen new HubSpot contacts against OpenSanctions before sales picks up

Build an agent workflow that screens every new HubSpot contact against OpenSanctions before sales starts working the lead. The whole thing should run end to end without a human in the loop on clean passes, and only ping people when there is something to look at.

Trigger: a new contact being created in HubSpot. Fire on the HubSpot new-contact event so this runs in near real time. Pull the contact's first name, last name, email, country, and company association if present.

Screening step: call OpenSanctions Match Entities against the default collection with a single FollowTheMoney Person query containing the contact's name, email, country, and (when present) the associated company name. Use the default scoring algorithm (logic-v2). Remember that OpenSanctions auth is literally the header Authorization: ApiKey <key> (not Bearer), and that every property value in the request and response is an array of strings, not a bare string. If the response is a 308 redirect on an entity ID, follow the Location header to the canonical merged entity.

Interpret the scored matches into one of three buckets:

- clear: no candidate match scored at or above 0.55. - review: at least one candidate scored between 0.55 and 0.70 (borderline name match, needs a human). - hit: at least one candidate scored at or above 0.70 (the logic-v2 default threshold).

On a clear result, use HubSpot Update Contact to set a single custom property screening_status = clear and stop. Do not create a note and do not post to Slack on clean passes; the goal is no noise.

On a review or hit result, do three things:

1. Update Contact: set screening_status = review for borderline matches, or screening_status = flag for confirmed hits.

2. Create Note on the contact summarizing the top 3 candidate matches. For each one include the matched name, the score, the OpenSanctions datasets the entity appears on (sanctions, peps, debarment, crime, etc.), any schedule or program names attached to the sanction, and a direct OpenSanctions entity URL so a human can open the source. Make this note the audit trail.

3. Send a Message to the #compliance-alerts Slack channel that includes the contact's full name, the HubSpot deal owner (look up the owner via HubSpot if the contact has one assigned), the top match score, and a direct link to the HubSpot contact record. The message must make it obvious at a glance whether this is a hard sanctions or debarment or crime hit (treat as block until cleared) versus a PEP-only match (enhanced due diligence, not necessarily a block). Use clear emoji or label cues for the two categories.

Edge cases to handle gracefully:

- Contact with only an email and no name: still screen on the email and country, do not crash. - OpenSanctions returns 308 on a previously-cached entity ID: follow the redirect to the canonical entity before reading datasets or building the URL. - HubSpot rate-limit response (429): back off and retry rather than failing the run. - Custom property screening_status does not exist yet: write a friendly setup note explaining the user needs to create it on the contact object.

Wedge to highlight in the build: most HubSpot-native screening tools only check OFAC and UN sanctions. The point of using OpenSanctions here is that the same call also covers politically exposed persons, debarment lists, and wanted-criminal watchlists, which HubSpot users do not get out of the box.