Add and manage your riders from your system

Manage your own riders (outlet riders, delivery_mode: "OUTLET") through the API. Only riders mapped to your outlet are visible. Another outlet’s rider returns 404 NOT_FOUND. Every call needs Authorization: Bearer <access_token>; the outlet comes from the token. In every response, id is the rider id: use it in the /:id routes.

Set BASE_URL to the API address you were given. The examples below use $BASE_URL and $ACCESS_TOKEN.

What the rider does#

1. Installs the MiniDrop Rider app (use app_download_url from the create response when it is set).

2. Logs in with the email you sent and the temporary password from the onboarding email.

3. Changes the password when the app asks.

4. Goes Online. The rider then appears in GET /api/delivery-executives?online=true and can be selected for your trips.

If the email belongs to an existing MiniDrop rider, that rider keeps their current password and is only added to your outlet. Guide for the rider: Install the MiniDrop rider app and sign in.

Add a rider#

curl -X POST "$BASE_URL/api/delivery-executives" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{"name":"Ravi Kumar","phone":"+919876543210","email":"ravi@example.com","max_orders_per_trip":5}'

Response 201 Created:

{  "success": true,  "data": {    "id": "7c1f0e9a-3b2d-4e8f-9a6b-1d2c3e4f5a6b",    "name": "Ravi Kumar",    "phone": "+919876543210",    "email": "ravi@example.com",    "status": "APPROVED",    "max_orders_per_trip": 5,    "is_existing_account": false,    "work_online": false,    "app_download_url": "https://example.com/rider-app"  }}

• is_existing_account: false means a new login was created and the temporary password was emailed. true means an existing rider was mapped and their password is unchanged.

• app_download_url is null when no rider app link is configured.

Errors: 400 VALIDATION_ERROR (invalid phone, email or fields), 409 EMAIL_ROLE_MISMATCH (the email belongs to a non-rider account), 409 ALREADY_MAPPED (the rider is already on your outlet; error.details.id holds the rider id).

List riders#

curl "$BASE_URL/api/delivery-executives?online=true" \  -H "Authorization: Bearer $ACCESS_TOKEN"

• online=true: riders with work_online: true and a location received in the last 5 minutes.

• online=false: all other riders.

{  "success": true,  "data": [    {      "id": "7c1f0e9a-3b2d-4e8f-9a6b-1d2c3e4f5a6b",      "name": "Ravi Kumar",      "phone": "+919876543210",      "email": "ravi@example.com",      "status": "APPROVED",      "max_orders_per_trip": 5,      "work_online": true,      "location_fresh": true,      "active_trip_id": null,      "created_at": "2026-10-20T09:30:00.000Z"    }  ]}

• location_fresh: the rider’s location was received in the last 5 minutes.

• active_trip_id: the trip the rider is on now (status PENDING_APPROVAL, CREATED, ASSIGNED or STARTED), otherwise null.

• created_at: when the rider was added to your outlet.

Get, update and remove#

GET /api/delivery-executives/:id returns one rider with the same fields as the list (404 NOT_FOUND if the rider is not on your outlet).

PATCH /api/delivery-executives/:id: send at least one of name, phone, max_orders_per_trip. The phone is normalised as on create. The response is the updated rider. Errors: 400 VALIDATION_ERROR (no field sent, or an invalid value), 404 NOT_FOUND.

curl -X PATCH "$BASE_URL/api/delivery-executives/$DE_ID" \  -H "Authorization: Bearer $ACCESS_TOKEN" \  -H "Content-Type: application/json" \  -d '{"max_orders_per_trip":8}'

DELETE /api/delivery-executives/:id removes the rider from your outlet. The rider’s login is deleted only when the rider belongs to no other outlet and has no delivery history.

{  "success": true,  "data": {    "deleted_completely": false,    "message": "Rider removed from your outlet. Their platform account is unchanged because they are linked to other outlets or have delivery history."  }}

Errors: 404 NOT_FOUND, 409 RIDER_HAS_ACTIVE_TRIP (the rider has an active or pending trip for your outlet: complete it or release the orders first).