duty-status
duty-status
# Update Driver Duty Status (Go Online / Offline)
Toggles the real-time availability and duty state of the driver (`ONLINE`, `OFFLINE`, or `ON_TRIP`).
> **⚠️ Business Rule:** A driver can **only go** **`ONLINE`** **if their account status is** **`APPROVED`**. If the account status is `PENDING_ONBOARDING`, `PENDING_APPROVAL`, `REJECTED`, or `SUSPENDED`, the backend rejects the request with HTTP `403 APPROVAL_REQUIRED`.
---
### Endpoint Overview
- **Method:** `PATCH`
- **Route:** `/api/v1/driver/duty-status`
- **Authentication:** `Bearer Token (Driver JWT)`
- **Content-Type:** `application/json`
---
### Request Headers
| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | **Yes** | Format: `Bearer` |
| `Content-Type` | `string` | **Yes** | Must be `application/json` |
---
### Request Body Schema
| Field | Data Type | Required | Default | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `duty_status` | `enum` | **Yes** | — | `"ONLINE""OFFLINE""ON_TRIP"` | Target duty status |
#### Example Request Body (Going Online)
``` json
{
"duty_status": "ONLINE"
}
```
#### Example Request Body (Going Offline)
``` json
{
"duty_status": "OFFLINE"
}
```
---
### Response Body Schema (`200 OK`)
| Top-Level Key | Data Type | Description |
| --- | --- | --- |
| `message` | `string` | Status confirmation (e.g. `"Duty status updated to ONLINE"`) |
| `duty_status` | `enum` | Updated duty status (`"ONLINE"`, `"OFFLINE"`, `"ON_TRIP"`) |
| `driver` | `object` | Complete updated driver profile |
#### `driver` Object Fields
| Field | Data Type | Nullable | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | No | Prefixed with `drv_` | Unique driver ID |
| `name` | `string` | Yes | String | Driver full name |
| `phone` | `string` | No | E.164 string | Registered phone number |
| `is_phone_verified` | `boolean` | No | `true`, `false` | Phone verification status |
| `email` | `string` | Yes | Valid email | Registered email |
| `is_email_verified` | `boolean` | No | `true`, `false` | Email verification status |
| `gender` | `enum` | Yes | `"MALE"`, `"FEMALE"`, `null` | Driver gender |
| `date_of_birth` | `string` | Yes | ISO 8601 Timestamp | Driver date of birth |
| `profile_image_url` | `string` | Yes | Valid URL | Avatar image URL |
| `is_profile_complete` | `boolean` | No | `true`, `false` | Profile completion status |
| `status` | `enum` | No | `"APPROVED"` (or current status) | Onboarding & approval state |
| `duty_status` | `enum` | No | `"ONLINE"`, `"OFFLINE"`, `"ON_TRIP"` | Updated real-time duty state |
| `rejection_reason` | `string` | Yes | String | Rejection reason if status is `REJECTED` |
| `rating` | `string` | No | Decimal string (e.g. `"4.85"`) | Driver rating |
| `total_trips` | `integer` | No | `>= 0` | Completed trips count |
| `wallet_balance` | `string` | No | Decimal string (e.g. `"3250.00"`) | Current wallet balance |
| `service_category` | `enum` | No | `"BIKE"`, `"CAB"`, `"AMBULANCE"`, `"LOGISTICS"` | Operational category |
| `city` | `string` | No | String | Operating city |
| `state` | `string` | Yes | String | Operating state |
| `language` | `string` | No | String | Preferred interface language |
| `own_referral_code` | `string` | Yes | Prefixed with `CAP_` | Unique referral code |
| `referred_by_code` | `string` | Yes | String | Inviter referral code |
| `vehicle_name` | `string` | Yes | String | Vehicle make/brand |
| `vehicle_model` | `string` | Yes | String | Vehicle model |
| `vehicle_color` | `string` | Yes | String | Vehicle color |
| `number_plate` | `string` | Yes | String | Registration plate number |
| `vehicle` | `object` | Yes | Sub-object or `null` | Vehicle details |
| `vehicle.id` | `string` | No | Prefixed with `veh_` | Vehicle ID |
| `vehicle.name` | `string` | No | String | Vehicle name |
| `vehicle.model` | `string` | No | String | Vehicle model |
| `vehicle.color` | `string` | No | String | Vehicle color |
| `vehicle.number_plate` | `string` | No | String | Plate number |
| `is_active` | `boolean` | No | `true`, `false` | System active status |
| `is_blocked` | `boolean` | No | `true`, `false` | Account blocked flag |
| `last_login_at` | `string` | Yes | ISO 8601 Timestamp | Timestamp of last login |
| `created_at` | `string` | No | ISO 8601 Timestamp | Account registration timestamp |
| `updated_at` | `string` | No | ISO 8601 Timestamp | Timestamp of this update |
---
### Response Examples
#### 1\. `200 OK` — Duty Status Updated (Online)
``` json
{
"message": "Duty status updated to ONLINE",
"duty_status": "ONLINE",
"driver": {
"id": "drv_8a7b6c5d4e",
"name": "Ravi Kumar",
"phone": "+919876543210",
"is_phone_verified": true,
"email": "ravi.kumar@example.com",
"is_email_verified": true,
"gender": "MALE",
"date_of_birth": "1992-05-15T00:00:00.000Z",
"profile_image_url": "https://example.com/profiles/ravi.jpg",
"is_profile_complete": true,
"status": "APPROVED",
"duty_status": "ONLINE",
"rejection_reason": null,
"rating": "4.85",
"total_trips": 142,
"wallet_balance": "3250.00",
"service_category": "CAB",
"city": "Bengaluru",
"state": "Karnataka",
"language": "en",
"own_referral_code": "CAP_8X9K2",
"referred_by_code": null,
"vehicle_name": "Maruti Suzuki",
"vehicle_model": "Swift Dzire",
"vehicle_color": "White",
"number_plate": "KA-01-AB-1234",
"vehicle": {
"id": "veh_1a2b3c4d5e",
"name": "Maruti Suzuki",
"model": "Swift Dzire",
"color": "White",
"number_plate": "KA-01-AB-1234"
},
"is_active": true,
"is_blocked": false,
"last_login_at": "2026-09-21T04:45:00.000Z",
"created_at": "2026-08-10T12:00:00.000Z",
"updated_at": "2026-09-21T05:15:00.000Z"
}
}
```
#### 2\. `403 Forbidden` — Approval Required to Go Online
Returned when an unapproved driver (e.g. `PENDING_ONBOARDING` or `PENDING_APPROVAL`) attempts to set `duty_status: "ONLINE"`:
``` json
{
"error": "APPROVAL_REQUIRED",
"message": "Driver status is currently 'PENDING_ONBOARDING'. Your profile and documents must be APPROVED by admin before going online."
}
```
#### 3\. `400 Bad Request` — Validation Error (Invalid Duty Status)
``` json
{
"success": false,
"message": "Validation failed: duty_status: Invalid enum value. Expected 'OFFLINE' | 'ONLINE' | 'ON_TRIP', received 'BUSY'",
"errors": [
{
"field": "duty_status",
"message": "Invalid enum value. Expected 'OFFLINE' | 'ONLINE' | 'ON_TRIP', received 'BUSY'"
}
]
}
```
#### 4\. `401 Unauthorized` — Missing / Expired Token / Session Revoked
``` json
{
"error": "Unauthorized",
"message": "Invalid or expired driver access token."
}
```
#### 5\. `404 Not Found` — Driver Not Found
``` json
{
"error": "Driver not found"
}
```
#### 6\. `500 Internal Server Error`
``` json
{
"error": "Failed to update duty status"
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Duty status updated successfully and returned with updated driver profile. |
| **`400 Bad Request`** | Missing `duty_status` or value not in `["OFFLINE", "ONLINE", "ON_TRIP"]`. |
| **`401 Unauthorized`** | Missing, invalid, expired token or session revoked. |
| **`403 Forbidden`** | Driver is not `APPROVED` while attempting to go `ONLINE`, or account is blocked. |
| **`404 Not Found`** | Driver ID in token does not match any record. |
| **`500 Internal Server Error`** | Server or database update error. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.