city
# Update Operating City
Updates the designated operational city and state for the authenticated driver.
---
### Endpoint Overview
- **Method:** `PATCH`
- **Route:** `/api/v1/driver/city`
- **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 |
| --- | --- | --- | --- | --- | --- |
| `city` | `string` | **Yes** | — | Min length 1 (e.g. `"Bengaluru"`, `"Delhi NCR"`, `"Mumbai"`) | Name of operating city |
| `state` | `string` | No | `null` | Any string or `null` | State or province |
#### Example Request Body
``` json
{
"city": "Bengaluru",
"state": "Karnataka"
}
```
---
### Response Body Schema (`200 OK`)
| Top-Level Key | Data Type | Description |
| --- | --- | --- |
| `message` | `string` | Confirmation message (`"Operating city updated successfully"`) |
| `city` | `string` | Updated operating city name |
| `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 account ID |
| `name` | `string` | Yes | Any string | Full name of driver |
| `phone` | `string` | No | E.164 string format | Registered phone number |
| `is_phone_verified` | `boolean` | No | `true`, `false` | Phone verification flag |
| `email` | `string` | Yes | Valid email | Registered email address |
| `is_email_verified` | `boolean` | No | `true`, `false` | Email verification flag |
| `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 | `"PENDING_ONBOARDING""PENDING_APPROVAL""APPROVED""REJECTED""SUSPENDED""BLOCKED"` | Onboarding & verification state |
| `duty_status` | `enum` | No | `"OFFLINE""ONLINE""ON_TRIP"` | Real-time driver operational state |
| `rejection_reason` | `string` | Yes | Any string | Rejection reason if status is `REJECTED` |
| `rating` | `string` | No | Decimal string (e.g. `"4.85"`) | Driver rating |
| `total_trips` | `integer` | No | `>= 0` | Total completed trips count |
| `wallet_balance` | `string` | No | Decimal string (e.g. `"3250.00"`) | Driver wallet balance |
| `service_category` | `enum` | No | `"BIKE""CAB""AMBULANCE""LOGISTICS"` | Operating service domain |
| `city` | `string` | No | String | Updated operating city |
| `state` | `string` | Yes | String | Updated operating state |
| `language` | `string` | No | Default: `"en"` | Preferred interface language |
| `own_referral_code` | `string` | Yes | Prefixed with `CAP_` | Unique referral code |
| `referred_by_code` | `string` | Yes | String | Referral code used during signup |
| `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 brand |
| `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` — Success
``` json
{
"message": "Operating city updated successfully",
"city": "Bengaluru",
"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": "OFFLINE",
"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:08:45.000Z"
}
}
```
#### 2\. `400 Bad Request` — Validation Error (Missing `city`)
``` json
{
"success": false,
"message": "Validation failed: city: City name is required",
"errors": [
{
"field": "city",
"message": "City name is required"
}
]
}
```
#### 3\. `401 Unauthorized` — Token Missing / Expired / Session Revoked
``` json
{
"error": "Unauthorized",
"message": "Invalid or expired driver access token."
}
```
#### 4\. `403 Forbidden` — Account Blocked / Deactivated
``` json
{
"error": "Forbidden",
"message": "Driver account is blocked or deactivated."
}
```
#### 5\. `404 Not Found` — Driver Not Found
``` json
{
"error": "Driver not found"
}
```
#### 6\. `500 Internal Server Error`
``` json
{
"error": "Failed to update operating city"
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Operating city successfully updated in database and returned with driver profile. |
| **`400 Bad Request`** | Missing or empty `city` field in body. |
| **`401 Unauthorized`** | Missing, invalid, expired token or session revoked. |
| **`403 Forbidden`** | Driver account is deactivated or blocked. |
| **`404 Not Found`** | Driver ID from token does not exist in database. |
| **`500 Internal Server Error`** | Server or database query failure. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.