Creating and Routing Custom Workitems using the Workload Management API
What This Guide Covers
This guide details the architectural and implementation steps required to define custom workitem types, submit workitem payloads via the Genesys Cloud Workload Management API, and trigger deterministic routing to agents. By the end of this document, you will have a production-ready integration that ingests non-telephony tasks, applies skill-based routing rules, and manages routing state transitions without bypassing WFM capacity calculations.
Prerequisites, Roles & Licensing
- Licensing Tier: Genesys Cloud CX 2 or higher. Workitem routing requires the WFM add-on or a CX 3/4 tier that includes WFM capabilities.
- User Permissions:
Workitem > Type > CreateWorkitem > Type > EditWorkitem > CreateRouting > Workitem > Edit
- OAuth Scopes:
workitemtype:create,workitemtype:edit,workitem:create,workitem:edit,routing:workitem - External Dependencies: REST API client or middleware service capable of handling async state polling, idempotency key generation, and JSON payload serialization. Network egress to
api.us.genesyscloud.com(or regional equivalent) on port 443.
The Implementation Deep-Dive
1. Defining the Workitem Type and Custom Field Schema
Workitems in Genesys Cloud are not generic containers. They are strongly-typed objects governed by a Workitem Type definition. The schema you define dictates routing rule evaluation, capacity calculation triggers, and downstream reporting. You must establish the type before submitting any payloads.
Submit a POST request to /api/v2/workitemtypes to create the definition. The payload requires a unique name, description, and an array of customFields. Each field must declare a type (string, number, date, dropdown, checkbox) and a displayName. Critical routing fields must be marked with "isRoutingField": true if you intend to use them in routing rule conditions.
POST /api/v2/workitemtypes
Authorization: Bearer <access_token>
Content-Type: application/json
{
"name": "LoanApplicationReview",
"description": "Custom workitem for mortgage loan document verification",
"customFields": [
{
"name": "applicantId",
"displayName": "Applicant ID",
"type": "string",
"isRoutingField": false
},
{
"name": "loanAmount",
"displayName": "Loan Amount USD",
"type": "number",
"isRoutingField": true
},
{
"name": "documentType",
"displayName": "Document Category",
"type": "dropdown",
"isRoutingField": true,
"options": [
"Paystub",
"TaxReturn",
"BankStatement"
]
},
{
"name": "priorityLevel",
"displayName": "Processing Priority",
"type": "number",
"isRoutingField": true
}
],
"routingEnabled": true,
"maxCapacity": 1,
"routingRuleId": null
}
The Trap: Defining custom fields after workitems are already in flight, or omitting the isRoutingField flag on attributes you plan to use in routing conditions. The routing engine only evaluates fields explicitly marked as routing fields. If you add a field later, existing workitems will not populate it, causing routing rule conditions to evaluate as null and fail. Furthermore, dropdown fields with missing options in the payload will trigger a validation rejection at the API layer.
Architectural Reasoning: We enforce schema immutability in production environments. The WFM engine caches workitem type definitions to optimize routing evaluation performance. Dynamic schema changes force cache invalidation across the routing cluster, introducing latency spikes during peak ingestion windows. You design the schema to match your longest-term routing strategy, not your current sprint backlog. The maxCapacity field controls how many workitems of this type an agent can hold simultaneously. Setting it to 1 enforces single-task focus, which reduces context switching penalties for high-complexity reviews.
2. Submitting the Workitem Payload via the WFM API
Once the type exists, you ingest workitems through POST /api/v2/workitems. The payload must reference the workitemTypeId and provide values for all non-nullable custom fields. The API returns a 201 Created response with the generated workitemId and an initial routingState of unrouted.
You must include the Idempotency-Key header on every request. This header accepts a UUID v4 or a deterministic hash of your source system record ID. Genesys Cloud uses this key to deduplicate requests within a 24-hour window.
POST /api/v2/workitems
Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: a3f7c912-4b8e-4d2a-9c1f-8876543210ab
{
"workitemTypeId": "e8f7d6c5-b4a3-2190-8765-43210fedcba9",
"customFields": {
"applicantId": "APP-2024-9981",
"loanAmount": 425000.00,
"documentType": "TaxReturn",
"priorityLevel": 3
},
"routingData": {
"queueId": null,
"routingRuleId": null,
"skills": [
{
"skillId": "skill-mortgage-review",
"proficiency": 5
}
]
},
"source": "LoanPortalIntegration",
"priority": 3
}
The Trap: Overriding queueId directly in the routingData object while simultaneously expecting skill-based distribution to occur. When you hardcode a queueId, the WFM engine bypasses the routing rule evaluation and skill-matching algorithms. The workitem drops directly into the specified queue and distributes based on standard queue settings (longest idle, round robin, etc.), completely negating the purpose of custom workitem routing. Additionally, omitting the Idempotency-Key header during transient network failures causes middleware retry logic to spawn duplicate workitems, inflating queue metrics and causing agent capacity exhaustion.
Architectural Reasoning: We separate ingestion from distribution. The routingData block in the creation payload is optional for initial submission. You can submit the workitem first to guarantee data persistence, then trigger routing asynchronously. This decoupling prevents routing engine backpressure from blocking your ingestion pipeline. If your middleware experiences a 503 Service Unavailable during creation, the idempotency header ensures safe retries without data duplication. The priority field at the root level influences queue sorting, but it does not override routing rule conditions. You use priority for queue ordering and routingData.skills for agent targeting.
3. Configuring and Triggering Routing Rules
Workitems do not route automatically unless you attach a routing rule to the type or explicitly trigger routing via POST /api/v2/workitems/{id}/routing. For production integrations, you configure routing rules in the Admin console or via the Routing API, then reference the routingRuleId in the workitem type definition.
When a workitem enters the unrouted state, the WFM engine evaluates the attached routing rule. The rule checks custom field conditions, matches agent skills, calculates available capacity, and transitions the workitem to queued. If you prefer explicit control, you submit a routing trigger request:
POST /api/v2/workitems/a3f7c912-4b8e-4d2a-9c1f-8876543210ab/routing
Authorization: Bearer <access_token>
Content-Type: application/json
{
"routingRuleId": "rule-mortgage-doc-routing",
"queueId": null,
"skills": [
{
"skillId": "skill-mortgage-review",
"proficiency": 5
}
]
}
The Trap: Configuring routing rules with overlapping conditions and failing to set a strict evaluationOrder. When multiple rules match a workitem, the engine applies the rule with the lowest evaluationOrder value. If you leave evaluation order unset or duplicate it across rules, routing becomes non-deterministic. Workitems will bounce between queues or route to agents with incorrect skill proficiencies. Another frequent misconfiguration is ignoring agent availability states. The routing engine respects Available, Not Available, and In Queue states, but it does not route to agents marked as Offline or Lunch. If your business logic expects immediate routing, you must ensure target agents are logged in and available.
Architectural Reasoning: We rely on deterministic rule evaluation order and explicit skill proficiency thresholds. The WFM routing engine operates on a priority queue model. It calculates a routing score based on skill proficiency, historical performance, and current capacity. By setting proficiency in the routingData block, you guide the score calculation. The engine prefers agents with higher proficiency scores for that specific skill. We avoid hardcoding queueId in routing triggers because queues act as fallback buffers, not primary distribution targets. Routing rules push work to agents; queues hold work when no agent meets the criteria. This separation maintains accurate SLA tracking and prevents queue congestion from masking skill gaps.
Validation, Edge Cases & Troubleshooting
Edge Case 1: Routing State Stuck in Queued Without Agent Assignment
The Failure Condition: Workitems transition to queued but never reach assigned or accepted. Queue metrics show growing backlog, but agent dashboards display zero pending workitems.
The Root Cause: The routing rule successfully matched a queue, but no agent possesses the required skill with a proficiency level that meets the rule threshold. Alternatively, all matching agents have reached their maxCapacity for this workitem type. The WFM engine places the workitem in the queue but cannot offer it to any agent.
The Solution: Audit agent skill assignments and proficiency levels. Verify that the maxCapacity on the workitem type aligns with business expectations. If capacity is set to 1 and agents are already processing one workitem, new workitems will queue indefinitely. Adjust the routing rule to include a fallback queue with broader skill requirements, or implement a capacity override for high-priority workitems using the priority field combined with a separate routing rule that bypasses strict proficiency thresholds.
Edge Case 2: Custom Field Type Mismatch on API Submission
The Failure Condition: The API returns 400 Bad Request with a validation error indicating an invalid custom field value. The workitem is not created.
The Root Cause: The payload contains a data type that conflicts with the workitem type definition. Common examples include submitting a string where a number is expected, or providing a dropdown value that does not exactly match the case-sensitive options defined in the type schema. The WFM API enforces strict schema validation before persistence.
The Solution: Implement client-side schema validation before API submission. Map your source system data types to Genesys Cloud types explicitly. For dropdown fields, maintain a lookup table that syncs with the Genesys Cloud workitem type options. If your source system introduces new values, update the workitem type definition first via PATCH /api/v2/workitemtypes/{id}, then resume ingestion. Never attempt to coerce types at runtime, as this causes silent data corruption or routing rule failures.
Edge Case 3: Idempotency Key Collision During High-Volume Ingestion
The Failure Condition: Middleware processes a batch of 500 workitems. Ten requests fail with 503 Service Unavailable. The retry logic resubmits the same payloads, but Genesys Cloud returns 409 Conflict for some, while others create duplicates.
The Root Cause: The idempotency key generation logic is inconsistent. If your middleware generates a new UUID on each retry instead of preserving the original key, Genesys Cloud treats retries as new requests. Conversely, if you hash the payload and two payloads differ only by timestamp but share the same business record ID, you may collide keys unintentionally. The 24-hour window is strict but not infinite.
The Solution: Derive the idempotency key from a stable business identifier, not a transient UUID. Combine the source system record ID with a hash of the critical routing fields. Store the key in your middleware database alongside the Genesys Cloud workitemId once creation succeeds. On retry, read the stored key instead of regenerating it. Implement exponential backoff with jitter for 429 Too Many Requests and 503 errors. Monitor the X-Genesys-Request-Id response header to correlate retries with original requests during debugging.