Building Automated Offboarding Scripts for Agent Termination using the Users API

How-To-Articles
1

Building Automated Offboarding Scripts for Agent Termination using the Users API

What This Guide Covers

You are building an automated offboarding pipeline that, upon HR system trigger, deactivates a departed agent in Genesys Cloud: removing them from all queues, revoking roles, clearing their active skills, and optionally anonymizing their PII - all via the Users and Routing APIs. When working, an agent’s last day termination triggers a chain of API calls that fully decouples them from the ACD within minutes, with no manual admin steps and a full audit trail.

Prerequisites, Roles & Licensing

  • Licensing: Any Genesys Cloud CX tier (Users API is available on all tiers)
  • OAuth Client permissions required (for the offboarding service account):
    • Authorization > Role > View
    • Authorization > DivisionPermission > View
    • People > User > Edit
    • Routing > Queue > Edit (to remove queue memberships)
    • Routing > RoutingSkill > Edit (to remove skill assignments)
    • Audit > Audit > View (to confirm actions were logged)
  • OAuth scopes: users, routing, authorization
  • External dependencies: HR system (Workday, SAP SuccessFactors, or BambooHR) with webhook or API outbound capability; optionally a secrets manager (AWS Secrets Manager, HashiCorp Vault) for service account credential storage

The Implementation Deep-Dive

1. Designing the Offboarding Event Trigger

The offboarding pipeline must be triggered by an authoritative HR event, not a manual ticket. The typical integration pattern:

[HR System: Workday] 
  --> Termination Event Webhook (POST to your middleware)
    --> Offboarding Service (Python/Node.js)
      --> Genesys Cloud Users API (deactivate)
      --> Routing API (remove from queues)
      --> Authorization API (remove roles)
      --> Audit log confirmation
      --> HR System: mark offboarding_complete = true

Your middleware receives a payload like:

{
  "event": "worker.terminated",
  "workerId": "WRK-12345",
  "email": "jane.doe@company.com",
  "terminationDate": "2025-06-30",
  "terminationType": "voluntary"
}

The email field is your join key to find the Genesys Cloud userId. Never hardcode userId in HR system payloads - emails are more stable identifiers across system migrations.

The Trap - acting on the event immediately for same-day terminations: If an agent is terminated mid-shift, deactivating them instantly drops their active call. Build a grace period check: if the termination date is today and the agent is currently in an ON_QUEUE or INTERACTING state, queue the offboarding for end-of-shift (e.g., 30 minutes after their scheduled end time) or route the decision to a supervisor. Force-deactivation during an active interaction creates a poor customer experience and an orphaned conversation record.

2. Resolving the Genesys Cloud User ID

The first API call translates the departed agent’s email to their Genesys userId:

import requests

def get_user_by_email(email: str, access_token: str, base_url: str) -> dict:
    headers = {"Authorization": f"Bearer {access_token}"}
    params = {
        "email": email,
        "expand": "authorization,routingStatus,presence"
    }
    resp = requests.get(f"{base_url}/api/v2/users", headers=headers, params=params)
    resp.raise_for_status()
    data = resp.json()
    
    if data.get("total", 0) == 0:
        raise ValueError(f"No Genesys Cloud user found for email: {email}")
    
    return data["entities"][0]

The expand=routingStatus,presence parameters give you the agent’s current ACD state before you proceed. Check user["routingStatus"]["status"] - if it’s INTERACTING, implement the grace period logic from Step 1.

3. Removing Queue Memberships

An inactive agent who remains in queues can still receive callbacks if the queue is configured to route to [INACTIVE] users (the default behavior does not route to inactive users, but explicit queue membership can cause edge cases with some routing configurations). Remove all queue memberships explicitly.

Step 1: Fetch all queues the agent belongs to

The Users API provides this directly:

GET /api/v2/users/{userId}/queues?pageSize=100&joined=true
Authorization: Bearer {access_token}

Response:

{
  "entities": [
    { "id": "queue-uuid-001", "name": "Tier 1 Support" },
    { "id": "queue-uuid-002", "name": "Billing" }
  ]
}

Step 2: Remove from each queue

def remove_from_all_queues(user_id: str, access_token: str, base_url: str) -> list:
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    # Fetch memberships
    resp = requests.get(
        f"{base_url}/api/v2/users/{user_id}/queues",
        headers=headers,
        params={"pageSize": 100, "joined": True}
    )
    queues = resp.json().get("entities", [])
    removed = []
    
    for queue in queues:
        queue_id = queue["id"]
        # PATCH the user's membership to joined=false
        patch_resp = requests.patch(
            f"{base_url}/api/v2/routing/queues/{queue_id}/members/{user_id}",
            headers=headers,
            json={"joined": False}
        )
        if patch_resp.status_code == 200:
            removed.append(queue_id)
        else:
            # Log and continue - don't fail the whole offboarding on one queue
            print(f"WARN: Could not remove {user_id} from queue {queue_id}: {patch_resp.text}")
    
    return removed

The Trap - using DELETE vs. PATCH for queue membership: DELETE /api/v2/routing/queues/{queueId}/members/{userId} removes the user from the queue roster entirely. PATCH with joined: false sets them as inactive but retains the membership record (useful if they might return). For terminated agents, use DELETE to keep queue rosters clean. On high-volume queues with hundreds of members, the difference matters for admin UI performance.

4. Revoking Roles and Access

Deactivating the user account (state: inactive) prevents login but does not remove role assignments. Roles must be explicitly revoked to prevent re-activation with stale permissions.

Step 1: Fetch current role grants

GET /api/v2/authorization/subjects/{userId}/divisions/all/roles
Authorization: Bearer {access_token}

This returns all division-scoped role grants:

{
  "roles": [
    { "id": "role-uuid-agent", "name": "Agent", "division": { "id": "div-uuid-001" } },
    { "id": "role-uuid-supervisor", "name": "Supervisor", "division": { "id": "div-uuid-002" } }
  ]
}

Step 2: Remove each role grant

def revoke_all_roles(user_id: str, roles: list, access_token: str, base_url: str):
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    
    for role in roles:
        role_id = role["id"]
        div_id = role["division"]["id"]
        
        resp = requests.delete(
            f"{base_url}/api/v2/authorization/subjects/{user_id}/divisions/{div_id}/roles/{role_id}",
            headers=headers
        )
        if resp.status_code not in (200, 204):
            print(f"WARN: Role revocation failed for role {role_id} in div {div_id}: {resp.text}")

Step 3: Deactivate the user account

PATCH /api/v2/users/{userId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "state": "inactive"
}

This prevents all login attempts and removes the agent from any UI supervisor views that filter on active agents.

The Trap - deactivating before revoking roles: If you deactivate the user first and then attempt to revoke roles, the Authorization API may return 404 for inactive users on some permission endpoints. Always revoke roles before deactivating the account.

5. Removing Skills and Clearing Routing Settings

Active skill assignments persist on inactive users and can cause routing issues if the account is ever reactivated for a different employee (some orgs recycle accounts). Clear them:

def clear_routing_skills(user_id: str, access_token: str, base_url: str):
    headers = {"Authorization": f"Bearer {access_token}"}
    
    # Fetch current skills
    resp = requests.get(
        f"{base_url}/api/v2/users/{user_id}/routingskills",
        headers=headers,
        params={"pageSize": 100}
    )
    skills = resp.json().get("entities", [])
    
    if not skills:
        return
    
    # Build bulk removal payload
    removal_payload = [{"id": s["id"]} for s in skills]
    
    # DELETE via routing skills bulk endpoint
    requests.delete(
        f"{base_url}/api/v2/users/{user_id}/routingskills/bulk",
        headers={**headers, "Content-Type": "application/json"},
        json=removal_payload
    )

Also clear the routing utilization settings if the agent had a custom utilization override:

DELETE /api/v2/users/{userId}/routingutilization
Authorization: Bearer {access_token}

This resets the agent to the org-level utilization policy, which is cleaner than a stale custom override.

6. Logging and Audit Confirmation

Every step of the offboarding must be logged with timestamps, success/failure status, and the userId and email for traceability. Store the log in a durable store (database, S3, or your SIEM):

import json
from datetime import datetime

offboarding_log = {
    "timestamp": datetime.utcnow().isoformat() + "Z",
    "email": email,
    "userId": user_id,
    "terminationType": termination_type,
    "actions": {
        "queuesRemoved": removed_queue_ids,
        "rolesRevoked": revoked_role_ids,
        "skillsCleared": len(skills),
        "accountDeactivated": True
    },
    "errors": error_list
}

with open(f"offboarding_logs/{user_id}_{datetime.utcnow().date()}.json", "w") as f:
    json.dump(offboarding_log, f, indent=2)

Confirm via Genesys Audit API that the actions were recorded:

GET /api/v2/audits/queryexecution?interval=2025-06-30T00:00:00Z/2025-06-30T23:59:59Z&entityType=User&entityId={userId}
Authorization: Bearer {access_token}

This confirms that Genesys Cloud’s own audit system recorded the deactivation, role removals, and queue changes - essential for SOX, HIPAA, or ISO 27001 compliance audits.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Agent Has Active Callbacks Queued

If the terminated agent has future callbacks scheduled in their name (via the POST /api/v2/conversations/callbacks endpoint with an explicit routingData.userId), those callbacks will fail to route after deactivation. Query the callbacks API before offboarding:

GET /api/v2/conversations/callbacks?userId={userId}&status=QUEUED

Re-assign outstanding callbacks to a team queue or a supervisor before proceeding.

Edge Case 2: Agent is a Queue Owner / Supervisor in Routing Rules

Some Architect flows or routing rules reference specific userId values (e.g., “escalate to supervisor Jane Doe”). After deactivation, any rule referencing Jane’s userId will silently fail or fall to an error path. Run a grep/search of all Architect flows for the terminated agent’s userId before completing offboarding, and update or remove those references.

Edge Case 3: GDPR Right to Erasure (PII Anonymization)

For EU-based tenants, a departed agent may invoke GDPR Article 17 (Right to Erasure). The Users API supports anonymization:

PATCH /api/v2/users/{userId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Former Employee",
  "email": "anonymized_{userId}@redacted.internal",
  "title": "",
  "department": ""
}

Note: Genesys Cloud does not automatically scrub the agent’s name from historical conversation records or analytics - those are immutable audit records. Anonymization only affects the user profile. Document this limitation in your GDPR response procedures.

Edge Case 4: Bulk Offboarding (Layoffs, Restructuring)

For bulk operations (20+ agents), rate limiting becomes relevant. The Users API enforces rate limits of approximately 300 requests/minute per OAuth client. Implement exponential backoff and parallelize cautiously - use asyncio or threading with a semaphore limiting concurrent requests to 5-10.

Official References