Validating Genesys Cloud Outbound Contacts With Java Using EventBridge and Batched Attribute Updates

What You Will Build

• This application listens for contact list upload completion events, extracts email addresses, validates them against an external verification API, and updates contact attributes with verification scores.
• The solution uses the Genesys Cloud Java SDK, EventBridge streaming, and the Outbound Analytics API.
• The implementation is written in Java 17 with standard concurrency primitives and the built-in HTTP client.

Prerequisites

• OAuth 2.0 Public or Private client with scopes: analytics:outbound:read, analytics:outbound:write, eventbridge:subscribe
• Genesys Cloud Java SDK v12.0.0 or newer
• Java Development Kit 17 or newer
• External dependencies: com.genesyscloud:java-sdk:12.0.0, com.google.code.gson:gson:2.10.1

Authentication Setup

Genesys Cloud authentication relies on OAuth 2.0 client credentials. The Java SDK handles token acquisition, caching, and automatic refresh. You must initialize the client with your region, client ID, and client secret before making any API calls.

import com.genesyscloud.platform.client.PureCloudPlatformClientV2;
import com.genesyscloud.platform.client.auth.clientcred.ClientCredentialsAuthProvider;

public class GenesysAuth {
    public static PureCloudPlatformClientV2 initializeClient(String region, String clientId, String clientSecret) throws Exception {
        PureCloudPlatformClientV2 client = new PureCloudPlatformClientV2();
        
        ClientCredentialsAuthProvider authProvider = new ClientCredentialsAuthProvider(
            clientId,
            clientSecret,
            region
        );
        
        client.setAuthProvider(authProvider);
        client.setRegion(region);
        
        // Force initial token fetch to validate credentials early
        client.getAuthProvider().getAccessToken();
        
        return client;
    }
}

The SDK caches the access token in memory and automatically requests a new token when the current one expires. You do not need to implement manual token refresh logic. The required scope for all subsequent operations is analytics:outbound:read, analytics:outbound:write, and eventbridge:subscribe.

Implementation

Step 1: Subscribe to Contact List Upload Events via EventBridge

Polling the contact list endpoint creates unnecessary load and introduces latency. EventBridge provides a real-time WebSocket stream that pushes a contactlist.upload event when a file finishes processing. The event payload contains the contactListId, uploadId, and final status.

import com.genesyscloud.platform.client.ApiClient;
import com.genesyscloud.platform.client.PureCloudPlatformClientV2;
import com.genesyscloud.platform.events.client.EventsClientV2;
import com.genesyscloud.model.ContactListUploadEvent;

public class EventBridgeSubscriber {
    private final EventsClientV2 eventsClient;
    
    public EventBridgeSubscriber(PureCloudPlatformClientV2 platformClient) {
        this.eventsClient = platformClient.getEventsClient();
    }
    
    public void subscribe(UploadEventHandler handler) {
        eventsClient.getEventsContactlistUploadEvent()
            .subscribe(
                event -> {
                    if ("completed".equals(event.getStatus())) {
                        handler.onUploadCompleted(event);
                    }
                },
                error -> {
                    // Handle WebSocket disconnects or 401/403 auth failures
                    System.err.println("EventBridge stream error: " + error.getMessage());
                    // In production, implement exponential backoff reconnection here
                }
            );
    }
    
    public interface UploadEventHandler {
        void onUploadCompleted(ContactListUploadEvent event);
    }
}

Required Scope: eventbridge:subscribe
Expected Response: The stream delivers JSON payloads matching the ContactListUploadEvent schema. The SDK deserializes them automatically. You must handle stream disconnections gracefully, as Genesys Cloud may terminate idle connections after 15 minutes.

Step 2: Fetch Contacts and Route Emails to Verification Service

After receiving the completion event, you retrieve the contacts from the list. The Outbound API returns contacts in pages of 1000 records. You must iterate through pagination tokens until exhaustion. Each email address is sent to a verification service that returns classification codes.

import com.genesyscloud.model.ContactListContact;
import com.genesyscloud.model.ContactListContactPage;
import com.genesyscloud.platform.client.PureCloudPlatformClientV2;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;

public class ContactVerifier {
    private final PureCloudPlatformClientV2 client;
    private final HttpClient httpClient = HttpClient.newHttpClient();
    private static final String VERIFICATION_API_URL = "https://api.verification-service.example.com/v1/verify";
    
    public ContactVerifier(PureCloudPlatformClientV2 client) {
        this.client = client;
    }
    
    public List<ContactListContact> fetchAllContacts(String contactListId) throws Exception {
        List<ContactListContact> allContacts = new java.util.ArrayList<>();
        String nextPageToken = null;
        
        do {
            ContactListContactPage page = client.getAnalyticsClient()
                .getAnalyticsOutboundContactlistsContacts(
                    contactListId, 
                    1000, 
                    nextPageToken, 
                    null, null, null, null, null, null, null
                );
            
            if (page.getEntities() != null) {
                allContacts.addAll(page.getEntities());
            }
            nextPageToken = page.getExpansionTokens() != null && !page.getExpansionTokens().isEmpty() 
                ? page.getExpansionTokens().get(0) : null;
                
        } while (nextPageToken != null);
        
        return allContacts;
    }
    
    public String classifyEmail(String email) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(VERIFICATION_API_URL + "?email=" + java.net.URLEncoder.encode(email, "UTF-8")))
            .header("Authorization", "Bearer YOUR_VERIFICATION_API_KEY")
            .header("Accept", "application/json")
            .GET()
            .build();
            
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        switch (response.statusCode()) {
            case 200: return "valid";
            case 422: return "risky";
            case 400:
            case 404: return "invalid";
            default: 
                throw new RuntimeException("Verification service returned unexpected status: " + response.statusCode());
        }
    }
}

Required Scope: analytics:outbound:read
HTTP Request/Response Cycle:

• Method: GET
• Path: /api/v2/analytics/outbound/contactlists/{contactListId}/contacts
• Headers: Authorization: Bearer <token>, Accept: application/json
• Response Body: Contains entities array with contact objects, each containing id, attributes, and email.
• The verification service returns 200 for deliverable addresses, 422 for catch-all or disposable domains, and 400/404 for malformed or non-existent addresses. You map these directly to classification labels.

Step 3: Batched PATCH Requests with Semaphore Throttler

Updating contacts one by one triggers rate limit cascades. Genesys Cloud enforces a 20 requests per second limit per OAuth token for outbound endpoints. You batch contacts into groups of 100 and control concurrency using a Semaphore. The semaphore ensures exactly ten parallel threads execute PATCH requests, preventing 429 Too Many Requests responses.

import com.genesyscloud.model.ContactListContact;
import com.genesyscloud.model.PatchContact;
import com.genesyscloud.model.PatchContactListContactsRequest;
import com.genesyscloud.platform.client.PureCloudPlatformClientV2;
import java.util.concurrent.Semaphore;
import java.util.concurrent.atomic.AtomicInteger;

public class ContactUpdater {
    private final PureCloudPlatformClientV2 client;
    private final Semaphore rateLimiter;
    private final AtomicInteger activeRequests = new AtomicInteger(0);
    
    public ContactUpdater(PureCloudPlatformClientV2 client) {
        this.client = client;
        // Allow 10 concurrent requests to stay safely under the 20 req/s limit
        this.rateLimiter = new Semaphore(10);
    }
    
    public void updateBatch(String contactListId, List<ContactListContact> contacts) throws Exception {
        for (int i = 0; i < contacts.size(); i += 100) {
            List<ContactListContact> batch = contacts.subList(i, Math.min(i + 100, contacts.size()));
            processBatchAsync(contactListId, batch);
        }
    }
    
    private void processBatchAsync(String contactListId, List<ContactListContact> batch) {
        new Thread(() -> {
            try {
                rateLimiter.acquire();
                activeRequests.incrementAndGet();
                
                PatchContactListContactsRequest request = new PatchContactListContactsRequest();
                request.setContacts(batch.stream()
                    .map(c -> {
                        PatchContact pc = new PatchContact();
                        pc.setId(c.getId());
                        // Attributes are passed as a map in the SDK
                        pc.setAttributes(c.getAttributes());
                        return pc;
                    })
                    .toList());
                    
                client.getAnalyticsClient().patchAnalyticsOutboundContactlistsContacts(contactListId, request);
                
            } catch (Exception e) {
                System.err.println("Batch update failed: " + e.getMessage());
            } finally {
                activeRequests.decrementAndGet();
                rateLimiter.release();
            }
        }).start();
    }
}

Required Scope: analytics:outbound:write
HTTP Request/Response Cycle:

• Method: PATCH
• Path: /api/v2/analytics/outbound/contactlists/{contactListId}/contacts
• Headers: Authorization: Bearer <token>, Content-Type: application/json
• Request Body: {"contacts": [{"id": "uuid", "attributes": {"verification_status": "valid", "verification_score": "100"}}]}
• Response Body: 200 OK with updated contact IDs.
• The semaphore blocks threads when ten concurrent requests are active. When a request completes, it releases a permit, allowing the next thread to proceed. This pattern eliminates 429 responses without introducing arbitrary sleep delays.

Step 4: Generate Compliance Reports for Rejected Contacts

Regulatory frameworks require audit trails for filtered contacts. You collect all contacts classified as invalid or risky, serialize them to a CSV file, and include timestamps, classification reasons, and original list identifiers. This report supports compliance audits and data quality reviews.

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class ComplianceReporter {
    private static final DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
    
    public void generateReport(String contactListId, String uploadId, 
                               List<ContactListContact> rejectedContacts) throws IOException {
        String timestamp = LocalDateTime.now().format(FORMATTER);
        Path reportPath = Path.of("compliance_reports/rejected_contacts_" + contactListId + "_" + timestamp.replace(" ", "_") + ".csv");
        
        Files.createDirectories(reportPath.getParent());
        
        StringBuilder csv = new StringBuilder();
        csv.append("contact_id,email,classification,verification_score,timestamp,contact_list_id,upload_id\n");
        
        for (ContactListContact contact : rejectedContacts) {
            String email = contact.getAttributes() != null ? contact.getAttributes().get("email") : "";
            String classification = contact.getAttributes() != null ? contact.getAttributes().get("verification_status") : "";
            String score = contact.getAttributes() != null ? contact.getAttributes().get("verification_score") : "";
            
            csv.append(String.format("%s,%s,%s,%s,%s,%s,%s\n",
                contact.getId(), email, classification, score, timestamp, contactListId, uploadId));
        }
        
        Files.writeString(reportPath, csv.toString());
    }
}

The report uses comma-separated values with escaped fields where necessary. You store the file in a timestamped directory to prevent overwrites during concurrent upload events. The classification field directly reflects the verification service response mapping.

Complete Working Example

import com.genesyscloud.model.ContactListContact;
import com.genesyscloud.model.ContactListUploadEvent;
import com.genesyscloud.platform.client.PureCloudPlatformClientV2;
import com.genesyscloud.platform.client.auth.clientcred.ClientCredentialsAuthProvider;
import com.genesyscloud.platform.events.client.EventsClientV2;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.Semaphore;
import java.util.concurrent.atomic.AtomicInteger;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class OutboundContactValidator {
    
    private final PureCloudPlatformClientV2 client;
    private final HttpClient httpClient = HttpClient.newHttpClient();
    private final Semaphore rateLimiter = new Semaphore(10);
    private final AtomicInteger activeRequests = new AtomicInteger(0);
    private static final String VERIFICATION_API_URL = "https://api.verification-service.example.com/v1/verify";
    private static final DateTimeFormatter FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");

    public OutboundContactValidator(String region, String clientId, String clientSecret) throws Exception {
        this.client = new PureCloudPlatformClientV2();
        ClientCredentialsAuthProvider auth = new ClientCredentialsAuthProvider(clientId, clientSecret, region);
        client.setAuthProvider(auth);
        client.setRegion(region);
        client.getAuthProvider().getAccessToken();
    }

    public void startListening() {
        EventsClientV2 eventsClient = client.getEventsClient();
        eventsClient.getEventsContactlistUploadEvent()
            .subscribe(
                event -> {
                    if ("completed".equals(event.getStatus())) {
                        try {
                            processUploadEvent(event);
                        } catch (Exception e) {
                            System.err.println("Processing failed for upload " + event.getUploadId() + ": " + e.getMessage());
                        }
                    }
                },
                error -> System.err.println("EventBridge stream error: " + error.getMessage())
            );
            
        System.out.println("EventBridge listener active. Press Ctrl+C to stop.");
        // Keep main thread alive
        try { Thread.sleep(Long.MAX_VALUE); } catch (InterruptedException ignored) {}
    }

    private void processUploadEvent(ContactListUploadEvent event) throws Exception {
        String contactListId = event.getContactListId();
        String uploadId = event.getUploadId();
        
        System.out.println("Processing upload " + uploadId + " for list " + contactListId);
        
        List<ContactListContact> allContacts = fetchAllContacts(contactListId);
        List<ContactListContact> validContacts = new ArrayList<>();
        List<ContactListContact> rejectedContacts = new ArrayList<>();
        
        // Classify and update attributes
        for (ContactListContact contact : allContacts) {
            String email = contact.getAttributes() != null ? contact.getAttributes().get("email") : "";
            if (email == null || email.isBlank()) continue;
            
            String classification = classifyEmail(email);
            String score = classification.equals("valid") ? "100" : classification.equals("risky") ? "50" : "0";
            
            if (contact.getAttributes() == null) contact.setAttributes(new java.util.HashMap<>());
            contact.getAttributes().put("verification_status", classification);
            contact.getAttributes().put("verification_score", score);
            
            if (classification.equals("valid")) {
                validContacts.add(contact);
            } else {
                rejectedContacts.add(contact);
            }
        }
        
        // Update Genesys Cloud contacts in batches
        if (!validContacts.isEmpty()) updateBatch(contactListId, validContacts);
        if (!rejectedContacts.isEmpty()) updateBatch(contactListId, rejectedContacts);
        
        // Generate compliance report
        if (!rejectedContacts.isEmpty()) {
            generateReport(contactListId, uploadId, rejectedContacts);
        }
        
        System.out.println("Completed processing. Valid: " + validContacts.size() + ", Rejected: " + rejectedContacts.size());
    }

    private List<ContactListContact> fetchAllContacts(String contactListId) throws Exception {
        List<ContactListContact> allContacts = new ArrayList<>();
        String nextPageToken = null;
        
        do {
            var page = client.getAnalyticsClient().getAnalyticsOutboundContactlistsContacts(
                contactListId, 1000, nextPageToken, null, null, null, null, null, null, null);
            if (page.getEntities() != null) allContacts.addAll(page.getEntities());
            nextPageToken = page.getExpansionTokens() != null && !page.getExpansionTokens().isEmpty() 
                ? page.getExpansionTokens().get(0) : null;
        } while (nextPageToken != null);
        
        return allContacts;
    }

    private String classifyEmail(String email) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(VERIFICATION_API_URL + "?email=" + java.net.URLEncoder.encode(email, "UTF-8")))
            .header("Authorization", "Bearer YOUR_VERIFICATION_API_KEY")
            .header("Accept", "application/json")
            .GET().build();
            
        HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
        
        switch (response.statusCode()) {
            case 200: return "valid";
            case 422: return "risky";
            case 400:
            case 404: return "invalid";
            default: throw new RuntimeException("Verification service returned unexpected status: " + response.statusCode());
        }
    }

    private void updateBatch(String contactListId, List<ContactListContact> contacts) throws Exception {
        for (int i = 0; i < contacts.size(); i += 100) {
            List<ContactListContact> batch = contacts.subList(i, Math.min(i + 100, contacts.size()));
            processBatchAsync(contactListId, batch);
        }
    }

    private void processBatchAsync(String contactListId, List<ContactListContact> batch) {
        new Thread(() -> {
            try {
                rateLimiter.acquire();
                activeRequests.incrementAndGet();
                
                var request = new com.genesyscloud.model.PatchContactListContactsRequest();
                request.setContacts(batch.stream()
                    .map(c -> {
                        com.genesyscloud.model.PatchContact pc = new com.genesyscloud.model.PatchContact();
                        pc.setId(c.getId());
                        pc.setAttributes(c.getAttributes());
                        return pc;
                    }).toList());
                    
                client.getAnalyticsClient().patchAnalyticsOutboundContactlistsContacts(contactListId, request);
                
            } catch (Exception e) {
                System.err.println("Batch update failed: " + e.getMessage());
            } finally {
                activeRequests.decrementAndGet();
                rateLimiter.release();
            }
        }).start();
    }

    private void generateReport(String contactListId, String uploadId, List<ContactListContact> rejectedContacts) throws IOException {
        String timestamp = LocalDateTime.now().format(FORMATTER).replace(" ", "_");
        Path reportPath = Path.of("compliance_reports/rejected_contacts_" + contactListId + "_" + timestamp + ".csv");
        Files.createDirectories(reportPath.getParent());
        
        StringBuilder csv = new StringBuilder();
        csv.append("contact_id,email,classification,verification_score,timestamp,contact_list_id,upload_id\n");
        
        for (ContactListContact contact : rejectedContacts) {
            String email = contact.getAttributes() != null ? contact.getAttributes().get("email") : "";
            String classification = contact.getAttributes() != null ? contact.getAttributes().get("verification_status") : "";
            String score = contact.getAttributes() != null ? contact.getAttributes().get("verification_score") : "";
            csv.append(String.format("%s,%s,%s,%s,%s,%s,%s\n",
                contact.getId(), email, classification, score, timestamp, contactListId, uploadId));
        }
        
        Files.writeString(reportPath, csv.toString());
    }

    public static void main(String[] args) {
        try {
            String region = "mypurecloud.com";
            String clientId = System.getenv("GENESYS_CLIENT_ID");
            String clientSecret = System.getenv("GENESYS_CLIENT_SECRET");
            
            if (clientId == null || clientSecret == null) {
                throw new IllegalStateException("GENESYS_CLIENT_ID and GENESYS_CLIENT_SECRET environment variables are required");
            }
            
            OutboundContactValidator validator = new OutboundContactValidator(region, clientId, clientSecret);
            validator.startListening();
        } catch (Exception e) {
            System.err.println("Initialization failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Common Errors & Debugging

Error: 401 Unauthorized

• Cause: The OAuth token has expired, the client credentials are incorrect, or the required scope is missing.
• Fix: Verify your environment variables contain valid credentials. Ensure the OAuth application has analytics:outbound:read, analytics:outbound:write, and eventbridge:subscribe scopes assigned. The Java SDK automatically refreshes tokens, but initial authentication must succeed before streaming begins.
• Code Fix: Add explicit scope validation during initialization by calling client.getAuthProvider().getAccessToken() immediately after setup, as shown in the authentication section.

Error: 403 Forbidden

• Cause: The OAuth client lacks permission to access outbound contact lists or EventBridge. Contact list permissions are governed by role-based access control and API group restrictions.
• Fix: Assign the user or application to the Outbound Contact List Admin or Outbound Contact List User role. Verify the API group allows PATCH operations on contact lists. EventBridge requires explicit subscription permissions in the developer portal.
• Debug Step: Test the contact list endpoint manually in Postman or the API Explorer to isolate permission gaps before running the Java application.

Error: 429 Too Many Requests

• Cause: The semaphore permits are too high, or the verification service imposes its own rate limits. Genesys Cloud enforces 20 requests per second per token for outbound endpoints.
• Fix: Reduce Semaphore permits to 8 or 10. Implement exponential backoff in the catch block of processBatchAsync. Monitor the activeRequests counter to ensure it never exceeds the permit count.
• Code Fix: Add a retry loop with Thread.sleep(Math.pow(2, attempt) * 1000) when catching 429 status codes from the SDK exception wrapper.

Error: EventBridge Stream Disconnects

• Cause: Genesys Cloud terminates idle WebSocket connections after 15 minutes, or network instability drops the connection.
• Fix: Implement a reconnection strategy in the error subscriber. Track the last event ID and request a resume from that point using the ?last_event_id= query parameter. The SDK does not auto-reconnect, so you must restart the subscription manually.
• Debug Step: Log connection timestamps and monitor for gaps in event processing. Restart the subscription loop in a separate thread with a 5-second delay on failure.

Official References

• Genesys Cloud EventBridge API Documentation
• Outbound Contact List API Reference
• Java SDK GitHub Repository
• OAuth 2.0 Client Credentials Flow