Lead Enrichment Automation with Salesforce Agentforce & Apollo.io

public class ApolloEnrichmentParser {

    public class ApolloResponse {
        public PersonData person;
        public OrgData organization;
    }

    public class PersonData {
        public String title;
        public String linkedin_url;
    }

    public class OrgData {
        public String name;
        public String industry;
        public Integer num_employees;
        public Decimal annual_revenue;
        public String country;
        public String id;
        public List<String> technologies;
    }

    // Static utility method: takes input, returns output, holds no state.
    public static Lead parseToLead(String jsonBody, Id leadId) {
        ApolloResponse resp = (ApolloResponse)
            JSON.deserialize(jsonBody, ApolloResponse.class);

        Lead l = new Lead(Id = leadId);

        if (resp.person != null) {
            if (resp.person.title != null)
                l.Title = resp.person.title;
            if (resp.person.linkedin_url != null)
                l.LinkedIn_URL__c = resp.person.linkedin_url;
        }

        if (resp.organization != null) {
            OrgData o = resp.organization;
            if (o.name != null)           l.Company = o.name;
            if (o.industry != null)       l.Industry = o.industry;
            if (o.country != null)        l.Country = o.country;
            if (o.id != null)             l.Apollo_Organization_Id__c = o.id;
            if (o.num_employees != null)  l.NumberOfEmployees = o.num_employees;
            if (o.annual_revenue != null) l.AnnualRevenue = o.annual_revenue;
            if (o.technologies != null)
                l.Tech_Stack__c = String.join(o.technologies, ', ');
        }

        l.Enrichment_Status__c = 'Enriched';
        l.Enrichment_Last_Run__c = System.now();

        return l;
    }
}

public class LeadScoringService {

    private static final Set<String> ICP_INDUSTRIES = new Set<String>{
        'Technology', 'Financial Services', 'Healthcare',
        'Manufacturing', 'Retail'};

    private static final Set<String> ICP_COUNTRIES = new Set<String>{
        'United Arab Emirates', 'Saudi Arabia', 'United States',
        'Canada', 'United Kingdom', 'Germany', 'France',
        'Netherlands', 'Switzerland', 'Australia', 'Japan', 'Singapore'};

    private static final Set<String> SENIOR_TITLES = new Set<String>{
        'ceo', 'cto', 'cfo', 'vp', 'vice president',
        'director', 'head of', 'chief'};

    private static final Set<String> PERSONAL_DOMAINS = new Set<String>{
        'gmail.com', 'yahoo.com', 'hotmail.com',
        'outlook.com', 'icloud.com'};

    // Hard disqualifiers, no positive signals can override these.
    // A student at Google with a business email is still not a buyer.
    private static final Set<String> DISQUALIFY_TITLES = new Set<String>{
        'intern', 'student', 'trainee'};

    public static Integer calculateScore(Lead l) {
        Integer score = 0;

        if (l.Title != null && isDisqualifiedTitle(l.Title)) return 0;

        if (l.Industry != null && ICP_INDUSTRIES.contains(l.Industry))
            score += 20;

        if (l.NumberOfEmployees != null && l.NumberOfEmployees >= 200)
            score += 15;

        if (l.Title != null && isSeniorTitle(l.Title))
            score += 20;

        if (l.Country != null && ICP_COUNTRIES.contains(l.Country))
            score += 15;

        if (l.AnnualRevenue != null && l.AnnualRevenue >= 10000000)
            score += 20;

        // Email: business domain earns points, personal domain loses them.
        if (l.Email != null && isPersonalEmail(l.Email)) {
            score -= 10;
        } else if (l.Email != null) {
            score += 10;
        }

        // Confirmed micro-company is an active negative signal.
        if (l.NumberOfEmployees != null && l.NumberOfEmployees < 20)
            score -= 10;

        // Clamp to 0-100. Penalties could theoretically push below 0.
        return Math.min(100, Math.max(0, score));
    }

    public static String getTier(Integer score) {
        if (score >= 80) return 'Immediate Action';
        if (score >= 60) return 'Hot';
        if (score >= 40) return 'Warm';
        return 'Cold';
    }

    private static Boolean isPersonalEmail(String email) {
        return PERSONAL_DOMAINS.contains(
            email.substringAfter('@').toLowerCase());
    }

    private static Boolean isSeniorTitle(String title) {
        String t = title.toLowerCase();
        for (String kw : SENIOR_TITLES) {
            if (t.contains(kw)) return true;
        }
        return false;
    }

    private static Boolean isDisqualifiedTitle(String title) {
        String t = title.toLowerCase();
        for (String kw : DISQUALIFY_TITLES) {
            if (t.contains(kw)) return true;
        }
        return false;
    }
}

public class LeadEnrichmentService {

    public static void handleResponse(
        Id leadId, Integer statusCode, String body) {

        Lead_Enrichment_Log__c log = new Lead_Enrichment_Log__c(
            Lead__c = leadId,
            HTTP_Status_Code__c = statusCode,
            Timestamp__c = System.now()
        );

        if (statusCode == 200) {
            Lead enriched = ApolloEnrichmentParser.parseToLead(body, leadId);
            enriched.ICP_Score__c = LeadScoringService.calculateScore(enriched);
            enriched.ICP_Tier__c = LeadScoringService.getTier(
                (Integer) enriched.ICP_Score__c);
            update enriched;
            log.Status__c = 'Success';

        } else if (statusCode == 429) {
            // HTTP 429 = Too Many Requests (Apollo rate limit).
            // Re-enqueue rather than marking as failed.
            log.Status__c = 'API Error';
            log.Error_Message__c = 'Rate limited. Re-queued.';
            System.enqueueJob(
                new LeadEnrichmentQueueable(new List<Id>{ leadId }));

        } else {
            log.Status__c = 'API Error';
            log.Error_Message__c =
                'HTTP ' + statusCode + ': ' + body.left(500);
            update new Lead(
                Id = leadId,
                Enrichment_Status__c = 'Failed');
        }

        insert log;
    }
}

public class LeadEnrichmentQueueable implements Queueable, Database.AllowsCallouts {

    private List<Id> leadIds;

    public LeadEnrichmentQueueable(List<Id> leadIds) {
        this.leadIds = leadIds;
    }

    public void execute(QueueableContext ctx) {
        if (leadIds.isEmpty()) return;

        Id currentLeadId = leadIds.remove(0);

        try {
            Lead l = [SELECT Id, Email FROM Lead
                      WHERE Id = :currentLeadId LIMIT 1];

            String apiKey = Apollo_Config__c.getOrgDefaults().API_Key__c;

            HttpRequest req = new HttpRequest();
            req.setEndpoint('callout:Apollo_NC/v1/people/match?email='
                + EncodingUtil.urlEncode(l.Email, 'UTF-8'));
            req.setMethod('GET');
            req.setHeader('Content-Type', 'application/json');
            req.setHeader('X-Api-Key', apiKey);
            req.setTimeout(10000); // 10 seconds

            HttpResponse res = new Http().send(req);

            LeadEnrichmentService.handleResponse(
                currentLeadId, res.getStatusCode(), res.getBody());

        } catch (Exception e) {
            // Catch-all: query failures, network issues, unexpected exceptions.
            // We still write a log so nothing fails silently.
            insert new Lead_Enrichment_Log__c(
                Lead__c = currentLeadId,
                Status__c = 'API Error',
                Error_Message__c = e.getMessage().left(255),
                Timestamp__c = System.now()
            );
            update new Lead(
                Id = currentLeadId,
                Enrichment_Status__c = 'Failed');
        }

        // Chain: each chained job gets fresh governor limits.
        if (!leadIds.isEmpty()) {
            System.enqueueJob(new LeadEnrichmentQueueable(leadIds));
        }
    }
}

trigger LeadEnrichmentTrigger on Lead (after insert) {

    List<Id> toEnrich = new List<Id>();

    for (Lead l : Trigger.new) {
        if (String.isNotBlank(l.Email)
            && l.Enrichment_Status__c != 'Enriched') {
            toEnrich.add(l.Id);
        }
    }

    if (!toEnrich.isEmpty()) {
        System.enqueueJob(new LeadEnrichmentQueueable(toEnrich));
    }
}