Assignments
9 API calls in this section.
List Assignments
/delivery/assignments?page=1&limit=10&status=&driver_id=&delivery_id=&bulk_assignment_id=&sort_by=&sort_order=desc&column_filters=&tenant_id=&language=enGet a list of delivery assignments with pagination, filtering, sorting and stats. Admin users can view all assignments; drivers can only view their own.
1curl --request GET "$ONDI_BASE_URL/delivery/assignments?page=1&limit=10&status=&driver_id=&delivery_id=&bulk_assignment_id=&sort_by=&sort_order=desc&column_filters=&tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}"Query parameters
pageOptional1
Page number for pagination
limitOptional10
Number of items per page
statusOptionalFilter by assignment status (pending, accepted, rejected, completed)
driver_idOptionalFilter by driver ID (Admin only; drivers always see their own assignments)
delivery_idOptionalFilter by delivery ID
bulk_assignment_idOptionalFilter by bulk assignment ID
sort_byOptionalColumn to sort by. Allowed: assignment_time. Defaults to assignment_time desc when not provided.
sort_orderOptionaldesc
Sort direction: asc or desc (default: desc)
column_filtersOptionalJSON string of column filters. Supported keys: status, driver_id, vehicle_id, delivery_id, assigned_by, bulk_assignment_id, external_reference_id (string ILIKE), delivery_code (integer exact), assignment_time ({from?, to?} date range). Example: {"driver_id":"5c5cd7f0-2b31-402f-872d-81cf17058fe2","assigned_by":"e40f4705-361e-4fcf-a221-49857de4fa82"}
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Headers
AuthorizationOptionalBearer {{access_token}}
Responses
Create Assignment
/delivery/assignments?tenant_id=&language=enCreate a new delivery assignment. Only users with 'manage:operations:tenant' permission can create assignments. The assignment row, driver capacity, and directly-assigned delivery status are committed atomically. Google route calculation runs after creation and stores route_details asynchronously, so route availability does not delay or determine assignment success. Zone Validation: - Uses pickup_zone_id / dropoff_zone_id from delivery_list_view (persisted on deliveries) and always validates driver zone access (no silent skip) - If driver has all_zones = true, they can be assigned to any delivery - If driver has all_zones = false, they must have the pickup zone and/or delivery zone assigned via delivery_zone_drivers table - Errors: driver_not_allowed_in_pickup_zone, driver_not_allowed_in_delivery_zone, driver_not_allowed_in_zones, delivery_zone_validation_unavailable (row missing from view). On view query failure: internal_server_error (500)
1curl --request POST "$ONDI_BASE_URL/delivery/assignments?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "delivery_id": "uuid",7 "driver_id": "uuid",8 "vehicle_id": "uuid",9 "estimated_pickup_time": "2023-08-01T13:00:00Z",10 "estimated_delivery_time": "2023-08-01T14:00:00Z",11 "sequence_number": 1,12 "notes": "Please deliver with care"13}'1{2 "delivery_id": "uuid",3 "driver_id": "uuid",4 "vehicle_id": "uuid",5 "estimated_pickup_time": "2023-08-01T13:00:00Z",6 "estimated_delivery_time": "2023-08-01T14:00:00Z",7 "sequence_number": 1,8 "notes": "Please deliver with care"9}Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
delivery_idExampleExample field from the request body.
driver_idExampleExample field from the request body.
vehicle_idExampleExample field from the request body.
estimated_pickup_timeExampleExample field from the request body.
estimated_delivery_timeExampleExample field from the request body.
sequence_numberExampleExample field from the request body.
notesExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Create Bulk Assignments
/delivery/assignments/bulk?tenant_id=&language=enCreate multiple delivery assignments in a single request for a single driver. Only users with 'manage:operations:tenant' permission can create bulk assignments. Request Format: - driver_id (required): Single driver ID for all deliveries - delivery_ids (required): Array of delivery IDs to assign Parent/Leg Assignment Contract: - A staged or hybrid parent delivery ID is accepted as dispatcher input. - The backend resolves each parent to its first active non-terminal child leg by sequence_plan order and creates the assignment on that leg, never on the parent. - A child leg in draft status is not available for assignment and returns no_active_child_leg (400). Warehouse receiving/execution must activate that leg first. - If a parent and its active leg are both submitted, the resolved duplicate is rejected. - Successful responses include resolved_deliveries when parent IDs were redirected. Each item contains requested_delivery_id and assigned_delivery_id. Frontends should navigate to or refresh the assigned child leg. Validation: - All resolved deliveries must be in 'pending' status - All resolved deliveries must be internal carrier type - Driver must be active and have a vehicle assigned - Total unit size of all resolved deliveries must fit in driver's vehicle capacity - Every resolved delivery must appear in delivery_list_view for the tenant; otherwise deliveries_zone_context_incomplete (400) with delivery_ids missing from the view - Driver must have access to all required zones (pickup_zone_id / dropoff_zone_id on the resolved delivery when present) unless driver has all_zones enabled; otherwise driver_not_allowed_in_zones and optional missing_zones - No duplicate submitted or resolved delivery IDs allowed Response: - Returns assignment IDs, count, total units, driver capacity used, and optional parent-to-leg resolutions - Creates a single bulk realtime notification record in delivery_realtime_assignments table with: - is_bulk: true - bulk_assignment_id: Unique ID for this bulk operation - assignment_count: Number of deliveries assigned - total_units: Total units consumed - Sends single bulk notification to driver (not individual notifications) - Individual assignments are created in delivery_assignments table for querying
1curl --request POST "$ONDI_BASE_URL/delivery/assignments/bulk?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "driver_id": "uuid",7 "delivery_ids": [8 "uuid1",9 "uuid2"10 ]11}'1{2 "driver_id": "uuid",3 "delivery_ids": [4 "uuid1",5 "uuid2"6 ]7}Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
driver_idExampleExample field from the request body.
delivery_idsExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Bulk Accept/Reject Assignments
/delivery/assignments/bulk/:bulkAssignmentId?tenant_id=&language=enAccept or reject all assignments in a bulk operation. Only the assigned driver can accept/reject their own bulk assignments. Request Format: - action (required): "accept" or "reject" Validation: - Driver must be active - All assignments must belong to the specified bulk_assignment_id - All assignments must belong to the authenticated driver - All assignments must be in 'pending' status Accept Action: - Updates all assignments to 'accepted' status - Updates all delivery statuses to 'assigned' - Sends notification to dispatchers Reject Action: - Updates all assignments to 'rejected' status - Frees up driver capacity (total units released) - Sends notification to dispatchers - Deliveries remain in 'pending' status (can be reassigned) Response: - Returns assignment IDs, count, and total units freed (if rejected)
1curl --request PUT "$ONDI_BASE_URL/delivery/assignments/bulk/:bulkAssignmentId?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "action": "accept"7}'1{2 "action": "accept"3}Path parameters
bulkAssignmentIdRequireduuid
Bulk assignment ID from bulk assignment creation
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
actionExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Update Assignment
/delivery/assignments/:assignmentId?tenant_id=&language=enUpdate an existing delivery assignment. Admin users can update any assignment. Drivers can only update their own assignments and are restricted to updating status, actual_pickup_time, actual_delivery_time, notes, and reason (supported as an alias for notes when self-unassigning). When the assignment status is updated, the related delivery status is also updated automatically. Driver change restriction: If the delivery already has route_id or route_session_id, changing driver_id is rejected with cannot_switch_driver_for_routed_delivery. Drivers are also blocked from self-unassigning routed deliveries with cannot_self_unassign_routed_delivery. Zone validation (admin changing driver_id): Same rules as create assignment; failures return delivery_zone_validation_unavailable or driver zone messages (driver_not_allowed_in_*). View load errors return internal_server_error (500).
1curl --request PUT "$ONDI_BASE_URL/delivery/assignments/:assignmentId?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "status": "in_progress",7 "actual_pickup_time": "2023-08-01T13:05:00Z",8 "actual_delivery_time": null,9 "notes": "Customer called, will be home in 10 minutes"10}'1{2 "status": "in_progress",3 "actual_pickup_time": "2023-08-01T13:05:00Z",4 "actual_delivery_time": null,5 "notes": "Customer called, will be home in 10 minutes"6}Path parameters
assignmentIdRequireduuid
ID of the assignment to update
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
statusExampleExample field from the request body.
actual_pickup_timeExampleExample field from the request body.
actual_delivery_timeExampleExample field from the request body.
notesExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Unassign Assignment (Dispatcher)
/delivery/assignments/:assignmentId/unassign?tenant_id=&language=enDispatcher-only. Unassign the current driver from an assignment. If tenant setting assignment_change_settings.enabled is false, the request is rejected. If the assignment is post-pickup and allow_unassign_after_pickup is false, the request is rejected.
1curl --request POST "$ONDI_BASE_URL/delivery/assignments/:assignmentId/unassign?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "reason": "Operational change"7}'1{2 "reason": "Operational change"3}Path parameters
assignmentIdRequireduuid
Assignment ID
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
reasonExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Switch Assignment Driver (Dispatcher)
/delivery/assignments/:assignmentId/switch-driver?tenant_id=&language=enDispatcher-only. Switch the driver on an assignment using the same assignment record. Respects assignment_change_settings and validates driver zones, capacity, and primary vehicle. If the delivery already has route_id or route_session_id, the switch is rejected with cannot_switch_driver_for_routed_delivery.
1curl --request POST "$ONDI_BASE_URL/delivery/assignments/:assignmentId/switch-driver?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "driver_id": "uuid",7 "reason": "Driver changed"8}'1{2 "driver_id": "uuid",3 "reason": "Driver changed"4}Path parameters
assignmentIdRequireduuid
Assignment ID
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
driver_idExampleExample field from the request body.
reasonExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Update Assignment Route
/delivery/assignments/:assignmentId/route?tenant_id=&language=enUpdate the route details for an existing assignment. Admin users can update any assignment's route. Drivers can only update routes for their own assignments.
1curl --request POST "$ONDI_BASE_URL/delivery/assignments/:assignmentId/route?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}" \3 --header "Content-Type: application/json" \4 --header "Content-Type: application/json" \5 --data '{6 "route_details": {7 "distance": 18.5,8 "duration": 55,9 "polyline": "updated_encoded_polyline_string",10 "stops": [11 {12 "location": {13 "latitude": 37.7749,14 "longitude": -122.419415 },16 "sequence": 1,17 "estimated_arrival": "2023-08-01T13:00:00Z"18 },19 {20 "location": {21 "latitude": 37.7694,22 "longitude": -122.486223 },24 "sequence": 2,25 "estimated_arrival": "2023-08-01T13:30:00Z"26 }27 ]28 }29}'1{2 "route_details": {3 "distance": 18.5,4 "duration": 55,5 "polyline": "updated_encoded_polyline_string",6 "stops": [7 {8 "location": {9 "latitude": 37.7749,10 "longitude": -122.419411 },12 "sequence": 1,13 "estimated_arrival": "2023-08-01T13:00:00Z"14 },15 {16 "location": {17 "latitude": 37.7694,18 "longitude": -122.486219 },20 "sequence": 2,21 "estimated_arrival": "2023-08-01T13:30:00Z"22 }23 ]24 }25}Path parameters
assignmentIdRequireduuid
ID of the assignment to update route for
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Request body fields
route_detailsExampleExample field from the request body.
route_details.distanceExampleExample field from the request body.
route_details.durationExampleExample field from the request body.
route_details.polylineExampleExample field from the request body.
route_details.stopsExampleExample field from the request body.
route_details.stops.locationExampleExample field from the request body.
route_details.stops.sequenceExampleExample field from the request body.
route_details.stops.estimated_arrivalExampleExample field from the request body.
Headers
AuthorizationOptionalBearer {{access_token}}
Content-TypeOptionalapplication/json
Responses
Get Assignment
/delivery/assignments/:assignmentId?tenant_id=&language=enGet details for a specific delivery assignment. Admin users can view any assignment, while drivers can only view their own assignments.
1curl --request GET "$ONDI_BASE_URL/delivery/assignments/:assignmentId?tenant_id=&language=en" \2 --header "Authorization: Bearer {{access_token}}"Path parameters
assignmentIdRequireduuid
ID of the assignment to retrieve
Query parameters
tenant_idOptionalTenant ID (optional if in auth token)
languageOptionalen
Preferred language for response messages
Headers
AuthorizationOptionalBearer {{access_token}}