⚡ How Assignment Works
Understand the full assignment flow — from task creation through agent acceptance — and the difference between manual and automatic assignment.
The Assignment Flow
When a new delivery task is created, it goes through a structured assignment pipeline to find the right agent. The flow is the same regardless of whether assignment is manual or automatic — only the selection mechanism differs.
NEW — Task Created
A task is created via the dashboard or API. It enters the system in the NEW status. At this point, no agent is assigned and the task is queued for assignment processing.
AWAITING_ASSIGNMENT — Ready for Assignment
The task transitions to AWAITING_ASSIGNMENT, indicating it is eligible for agent matching. The system now evaluates the organization's active assignment configuration to determine how to proceed.
Algorithm Execution
The configured assignment algorithm runs. For manual assignment, the task waits for a dispatcher to select an agent. For automatic assignment, the algorithm evaluates available agents and selects the best match based on the algorithm type (nearest, load-balanced, etc.).
ASSIGNED — Agent Selected
An agent is assigned to the task. The agent receives a notification (in-app + push) and the task moves to ASSIGNED status. The agent now has the opportunity to accept or reject the assignment.
ACCEPTED — Agent Confirms
The agent accepts the task via the Deliverty Driver App. The task moves to ACCEPTED and the customer is notified. If the agent rejects, the system can retry with the next best agent (depending on configuration).
After the agent accepts, the task continues through the delivery lifecycle: ACCEPTED → IN_TRANSIT → COMPLETED. See Statuses & Flow for the complete status lifecycle.
Manual vs Automatic Assignment
Deliverty Hub supports two assignment modes. You can switch between them at any time from the organization settings.
| Aspect | Manual Assignment | Automatic Assignment |
|---|---|---|
| How it works | A dispatcher manually selects an agent from the dashboard | The system automatically selects the best agent using the configured algorithm |
| Speed | Depends on dispatcher availability | Near-instant (seconds) |
| Best for | Small teams, complex assignments requiring human judgment | High-volume operations, consistent distribution |
| Control | Full control — dispatcher chooses exactly who gets the task | Algorithm-driven — the system optimizes based on rules |
| Retry on rejection | Dispatcher must reassign manually | Configurable auto-retry with next best agent |
| Algorithm type | manual |
nearest, load-balanced, predictive, one-by-one, zone-based |
If you are new to Deliverty Hub, start with manual assignment to understand the flow, then switch to automatic assignment with the nearest algorithm once your fleet is established and agents are actively sharing their GPS location.
One Active Configuration Per Organization
Each organization can have only one active assignment configuration at any given time. You may create multiple configurations (e.g., one for "nearest" and one for "load-balanced") but only one can be marked as isActive: true.
When you activate a new configuration, the previously active one is automatically deactivated. Tasks that are already in AWAITING_ASSIGNMENT will be processed using the newly active configuration. Tasks that are already ASSIGNED or beyond are not affected.
Agent Eligibility
Not every agent in your fleet is eligible for every task. The assignment system considers the following factors when selecting an agent:
| Factor | Description |
|---|---|
| Active Status | The agent must be marked as active in the system |
| Online Status | The agent must be online (connected via the mobile app with GPS sharing enabled) |
| Current Load | The number of tasks currently assigned to the agent (used by load-balanced algorithm) |
| Distance | The agent must be within the configured maxSearchRadiusMeters of the task pickup location |
| Zone | For zone-based assignment, the agent must be assigned to the zone that covers the task location |
Rejection and Retry
When an agent rejects a task (or the acceptance times out), the system behavior depends on the assignment configuration:
- Manual mode: The task returns to
AWAITING_ASSIGNMENTand the dispatcher is notified to reassign manually. - Automatic mode: The algorithm runs again, excluding the agent who rejected. The next best eligible agent is selected.
- One-by-one mode: Agents are offered the task sequentially. If one rejects, the next agent in the queue is tried automatically.
If all eligible agents reject the task (or none are available within the search radius), the task remains in AWAITING_ASSIGNMENT and an admin notification is sent. A dispatcher can then intervene manually or wait for agents to come online.
Next Steps
- Learn about each algorithm and how to choose the right one
- Configure assignment settings for your organization
- Manage your agents to ensure they are eligible for assignment