Architecting Gamification Leaderboards Using External KPI Data via API

How-To-Articles
1

Architecting Gamification Leaderboards Using External KPI Data via API

Executive Summary & Architectural Context

Genesys Cloud’s native Gamification module is highly effective at driving agent performance using standard contact center KPIs (Average Handle Time, CSAT, Quality Scores).

However, in a Sales or Collections environment, AHT and QA scores are secondary. The only metric that truly matters is Revenue Generated or Deals Closed. Because revenue data lives in the CRM (Salesforce, Hubspot), the native Genesys Gamification engine is blind to it.

If you cannot display external revenue on the agent’s Gamification leaderboard, the feature loses its motivational power. The architectural solution is to use the External Metrics API to push custom CRM KPIs directly into the Genesys Cloud WEM engine, allowing you to build mixed-metric leaderboards (e.g., combining Genesys QA scores with Salesforce Revenue).

This masterclass details how to define external metrics, push data payloads via the API, and configure Gamification profiles to consume them.

Prerequisites, Roles & Licensing

  • Licensing: Genesys Cloud CX 3 (WEM Add-on).
  • Roles & Permissions:
    • Gamification > Profile > Edit
    • OAuth Client with gamification:readwrite.
  • Platform Dependencies:
    • A middleware script capable of extracting daily KPI aggregations from your CRM and pushing them to the Genesys Cloud REST API.

The Implementation Deep-Dive

1. Defining the External Metric

Before you can push data, Genesys Cloud needs to know what the metric is and how to score it.

  1. Navigate to Admin > Performance & Engagement > Gamification Metrics.
  2. Click Add External Metric.
  3. Name: Daily_Revenue_Closed
  4. Unit type: Currency (or Integer for total sales count).
  5. Objective type: Higher is Better.
  6. Save the metric. Note the generated UUID for this metric; you will need it for the API payload.

2. Creating the API Push Script (Middleware)

Your CRM does not know how to talk to Genesys Cloud. You must write an ETL script that runs nightly (or hourly) to sync the data.

  1. The script queries Salesforce: “Give me the total closed-won revenue for Agent John Doe today.”
  2. The script maps John Doe’s Salesforce ID to his Genesys Cloud userId.
  3. The script executes a POST to the Genesys Cloud API.

Endpoint: POST /api/v2/gamification/externalmetrics/data

Payload:

{
  "items": [
    {
      "metricId": "a1b2c3d4-external-metric-uuid",
      "userId": "99887766-genesys-user-id",
      "dateOccurred": "2026-05-14",
      "value": 15400.50,
      "count": 3
    }
  ]
}

Logic: This payload tells Genesys Cloud that on May 14th, John Doe closed 3 deals totaling $15,400.50.

3. Configuring the Gamification Profile

Now that the data is flowing into the Genesys backend, you must surface it to the agents.

  1. Navigate to Admin > Performance & Engagement > Gamification Profiles.
  2. Select your Sales Agent profile.
  3. In the Metrics configuration, click Add Metric.
  4. You will now see Daily_Revenue_Closed available in the list alongside native metrics like AHT.
  5. Add it to the profile.
  6. Set the Target: Define what “good” looks like. For example, set the objective to $10,000 to earn 100 points.
  7. Save and publish the profile.

4. The Agent Experience

When the agent opens their Genesys Cloud Workspace, their Gamification scorecard will immediately display their CRM revenue alongside their call metrics, and their ranking on the Leaderboard will dynamically shift based on the API data pushes.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Retrospective Data Corrections

If a CRM deal is marked “Closed-Won” on Tuesday, pushed to Genesys, and then cancelled by the customer on Thursday, the agent’s Tuesday revenue was artificially inflated.

  • Troubleshooting: You cannot use a DELETE method on gamification data. You must execute a new POST payload for the exact same dateOccurred with the corrected value (e.g., pushing 0 or the adjusted revenue). Genesys Cloud will overwrite the previous metric value for that date and instantly recalculate the agent’s points and leaderboard standing.

Edge Case 2: Timezone Mismatches

Gamification scores are calculated based on a strict midnight-to-midnight boundary defined by the Management Unit timezone.

  • The Trap: If your CRM exports daily revenue in UTC, but the agent’s WFM Management Unit is set to EST, pushing a dateOccurred string without explicit timezone awareness might credit a Friday sale to Saturday.
  • Solution: Always ensure your ETL script maps the CRM event timestamp to the exact timezone of the agent’s assigned Management Unit before grouping the data by date.

Official References