Get work items in a queue
/v1/routing/queues/{id}/work-itemsorg.permission.queue.readorg.permission.routing.readorg.user.routing.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Retrieves a paginated list of work items.
Work items
A work item is routing's record of one conversation that needs an agent. It tracks which queue the conversation waits in, which agent it was offered to and accepted by, and how long each stage took.
Routing doesn't move conversations around directly; it moves work items. When a conversation needs an agent, Kustomer creates a work item for it (resource points at the conversation), places it in a queue, offers it to an available agent, and tracks it until the work is done. The routed conversations agents see arrive in the agent desktop are work items under the hood.
A conversation has at most one work item that isn't completed. Creating a work item for a conversation that already has one returns the existing item. Once an item is completed, a conversation that needs an agent again, for example after the customer replies, gets a new work item, so a conversation's history can hold several.
Lifecycle
status |
Meaning |
|---|---|
ivr |
Created, not yet in a queue. For a phone call, this covers time in the phone menu. |
queued |
Waiting in a queue. queuedCount counts how many times the item has entered a queue. |
routed |
Offered to one agent and waiting for them to accept. If they reject it or the offer times out, it goes back to queued and the agent is moved to an unavailable status. |
assigned |
Accepted. The agent is working on it, and it uses capacity on their work session. |
wrap-up |
The agent has finished the conversation and is doing after-contact work, such as notes. |
completed |
Done. The item no longer changes. |
The status enum also lists !wrap-up, which items never rest in. paused is separate from status: it's true while the conversation is snoozed, and a paused item uses no capacity and isn't routed.
Priority, size and timing
priority and itemSize are copied from the queue each time the item enters one. Routing offers the item with the lowest priority number first, then the one that has waited longest (firstEnterQueueAt). The ivr, handle and wrapUp objects record time and businessTime (time within business hours) for each stage, and lastRevision holds the latest queue entry, offer and acceptance, such as enteredQueueAt and acceptedAt.
Which endpoint to use
| To | Call |
|---|---|
| List work items across the org | GET /v1/routing/work-items |
| Read one work item | GET /v1/routing/work-items/{id} |
| Find the work items for a conversation | GET /v1/routing/conversations/{id}/work-items, filtered by status |
| See what's in a queue | GET /v1/routing/queues/{id}/work-items, with status=queued for waiting items |
| Peek at the item routing would hand out next | GET /v1/routing/queues/{id}/work-items/next |
| Create a work item, with a queue or an agent | POST /v1/routing/work-items |
| Move, assign, pause or finish an item | PUT /v1/routing/work-items/{id} |
Each PUT performs one change, chosen from the body: a queue moves the item to that queue (queue.id: null takes it out), assignedTo or accepted assigns it to an agent (assignedTo: null puts it back in its queue), status moves it to wrap-up or completed, and paused pauses or resumes it. Send the rev you last read; if the item changed since then, the request fails with 409 Conflict, so read it again and retry. The next-item endpoint only reads: it skips paused items, returns 404 when the queue is empty, and doesn't reserve the item for you.
Path parameters
Queue ID
"5f184e74c61792001af42e49"Query parameters
Page number to return.
1Number of records to return per page.
100Sort direction.
ascdescExample "desc"Filter work items by status. Supported values are ivr, queued, routed, assigned, wrap-up, !wrap-up, and completed.
ivrqueuedroutedassignedwrap-up!wrap-upcompletedExample "queued"Responses
OK