signin
# Driver Sign-in / Register
Authenticate an existing driver or register a new driver using their mobile phone number. On registration, a new driver record, referral code, and auth session tokens are generated.
---
### Endpoint Overview
- **Method:** `POST`
- **Route:** `/api/v1/driver/signin`
- **Authentication:** `None (Public)`
- **Content-Type:** `application/json`
---
### Request Headers
| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Content-Type` | `string` | **Yes** | Must be `application/json` |
| `User-Agent` | `string` | No | Client device info (used for session tracking) |
| `X-Forwarded-For` | `string` | No | Client IP address (used for session logging) |
---
### Request Body Schema
| Field | Data Type | Required | Default | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `phone` | `string` | **Yes** | — | Min length 1 | Driver's phone number with country code (e.g. `+919876543210`) |
| `name` | `string` | No | `null` | Any string | Full name of the driver |
| `email` | `string` | No | `null` | Valid email format | Email address |
| `gender` | `enum` | No | `null` | `"MALE"`, `"FEMALE"` | Driver gender |
| `profile_image_url` | `string` | No | `null` | Valid URL format | Hosted profile picture URL |
| `service_category` | `enum` | No | `"CAB"` | `"BIKE"`, `"CAB"`, `"AMBULANCE"`, `"LOGISTICS"` | Primary operational vehicle category |
| `city` | `string` | No | `"DEFAULT"` | Any string | Operating city name |
| `state` | `string` | No | `null` | Any string | Operating state/province |
| `language` | `string` | No | `"en"` | e.g. `"en"`, `"hi"` | Preferred app language code |
| `referred_by_code` | `string` | No | `null` | Existing referral code | Referral code of inviter (strictly validated on signup) |
| `is_phone_verified` | `boolean` | No | `true` | `true`, `false` | Status of client-side OTP verification |
| `device_id` | `string` | No | `null` | Any unique device ID | Device identifier used for single-device session tracking |
#### Request Body Example
``` json
{
"phone": "+919876543210",
"name": "Ravi Kumar",
"email": "ravi.kumar@example.com",
"gender": "MALE",
"profile_image_url": "https://example.com/profiles/ravi.jpg",
"service_category": "CAB",
"city": "Bengaluru",
"state": "Karnataka",
"language": "en",
"referred_by_code": "CAP_XYZ12",
"is_phone_verified": true,
"device_id": "d1234567-89ab-cdef-0123-456789abcdef"
}
```
---
### Response Body Schema (`200 OK`)
#### Top-Level Response Fields
| Field | Data Type | Description |
| --- | --- | --- |
| `message` | `string` | Status message (`"Signed in successfully"`) |
| `driver` | `object` | Complete driver profile details (see sub-fields below) |
| `accessToken` | `string` | JWT access token to send in `Authorization: Bearer` (expires in 1h) |
| `refreshToken` | `string` | Opaque refresh token string to rotate tokens via `/driver/refresh-token` (expires in 30d) |
#### `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 | Unique string | Registered mobile phone number |
| `is_phone_verified` | `boolean` | No | `true`, `false` | Whether phone number is verified via OTP |
| `email` | `string` | Yes | Valid email string | Registered email address |
| `is_email_verified` | `boolean` | No | `true`, `false` | Whether email is verified |
| `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` | Onboarding profile completion indicator |
| `status` | `enum` | No | `"PENDING_ONBOARDING""PENDING_APPROVAL""APPROVED""REJECTED""SUSPENDED""BLOCKED"` | Operational & verification state |
| `duty_status` | `enum` | No | `"OFFLINE""ONLINE""ON_TRIP"` | Real-time driver availability status |
| `rejection_reason` | `string` | Yes | Any string | Reason provided by admin if status is `REJECTED` |
| `rating` | `string` | No | Decimal string (default: `"5.00"`) | Average driver customer rating |
| `total_trips` | `integer` | No | `>= 0` (default: `0`) | Total number of completed trips |
| `wallet_balance` | `string` | No | Decimal string (default: `"0.00"`) | Current driver wallet balance |
| `service_category` | `enum` | No | `"BIKE""CAB""AMBULANCE""LOGISTICS"` | Registered domain of service |
| `city` | `string` | No | Default: `"DEFAULT"` | Operating city |
| `state` | `string` | Yes | Any string | Operating state/province |
| `language` | `string` | No | Default: `"en"` | Driver app interface language |
| `own_referral_code` | `string` | Yes | Prefixed with `CAP_` (e.g. `CAP_8X9K2`) | Unique code for inviting other drivers/riders |
| `referred_by_code` | `string` | Yes | Any string | Referral code used when registering |
| `vehicle_name` | `string` | Yes | Any string (e.g. `"Maruti Suzuki"`) | Flattened vehicle brand/make |
| `vehicle_model` | `string` | Yes | Any string (e.g. `"Swift Dzire"`) | Flattened vehicle model |
| `vehicle_color` | `string` | Yes | Any string (e.g. `"White"`) | Flattened vehicle paint color |
| `number_plate` | `string` | Yes | Any string (e.g. `"KA-01-AB-1234"`) | Flattened vehicle license registration number |
| `vehicle` | `object` | Yes | Sub-object or `null` | Nested vehicle details (null if not registered) |
| `vehicle.id` | `string` | No | Prefixed with `veh_` | Unique vehicle ID |
| `vehicle.name` | `string` | No | Any string | Vehicle make/brand name |
| `vehicle.model` | `string` | No | Any string | Vehicle model name |
| `vehicle.color` | `string` | No | Any string | Vehicle color |
| `vehicle.number_plate` | `string` | No | Any string | Vehicle license number plate |
| `is_active` | `boolean` | No | `true`, `false` | Whether driver is active in platform |
| `is_blocked` | `boolean` | No | `true`, `false` | Whether driver has been blocked |
| `last_login_at` | `string` | Yes | ISO 8601 Timestamp | Timestamp when driver last authenticated |
| `created_at` | `string` | No | ISO 8601 Timestamp | Record creation timestamp |
| `updated_at` | `string` | No | ISO 8601 Timestamp | Record last update timestamp |
---
### Response Examples
#### 1\. `200 OK` — Successful Registration (New Driver, No Vehicle Yet)
``` json
{
"message": "Signed in successfully",
"driver": {
"id": "drv_8a7b6c5d4e",
"name": "Ravi Kumar",
"phone": "+919876543210",
"is_phone_verified": true,
"email": "ravi.kumar@example.com",
"is_email_verified": false,
"gender": "MALE",
"date_of_birth": null,
"profile_image_url": "https://example.com/profiles/ravi.jpg",
"is_profile_complete": false,
"status": "PENDING_ONBOARDING",
"duty_status": "OFFLINE",
"rejection_reason": null,
"rating": "5.00",
"total_trips": 0,
"wallet_balance": "0.00",
"service_category": "CAB",
"city": "Bengaluru",
"state": "Karnataka",
"language": "en",
"own_referral_code": "CAP_8X9K2",
"referred_by_code": "CAP_XYZ12",
"vehicle_name": null,
"vehicle_model": null,
"vehicle_color": null,
"number_plate": null,
"vehicle": null,
"is_active": true,
"is_blocked": false,
"last_login_at": "2026-09-21T04:45:00.000Z",
"created_at": "2026-09-21T04:45:00.000Z",
"updated_at": "2026-09-21T04:45:00.000Z"
},
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkcnZfOGE3YjZjNWQ0ZSIsInNlc3Npb25fdmVyc2lvbiI6MSwiaWF0IjoxNzU4NDI5OTAwLCJleHAiOjE3NTg0MzM1MDB9.SIGNATURE",
"refreshToken": "drtok_7f8e9d0c1b2a345678901234567890ab"
}
```
#### 2\. `200 OK` — Successful Sign-in (Existing Approved Driver with Vehicle)
``` json
{
"message": "Signed in successfully",
"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-21T04:45:00.000Z"
},
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkcnZfOGE3YjZjNWQ0ZSIsInNlc3Npb25fdmVyc2lvbiI6MiwiaWF0IjoxNzU4NDI5OTAwLCJleHAiOjE3NTg0MzM1MDB9.SIGNATURE",
"refreshToken": "drtok_99aa88bb77cc66dd55ee44ff33aa22bb"
}
```
#### 3\. `400 Bad Request` — Validation Error
Returned when input validation fails (e.g. missing `phone` or invalid enum/format):
``` json
{
"success": false,
"message": "Validation failed: phone: Phone number is required",
"errors": [
{
"field": "phone",
"message": "Phone number is required"
}
]
}
```
#### 4\. `400 Bad Request` — Invalid Referral Code
Returned when a new driver registers with a referral code that does not exist:
``` json
{
"error": "Invalid referral code"
}
```
#### 5\. `403 Forbidden` — Account Blocked / Deactivated
Returned when the driver account is deactivated or blocked (`is_blocked = true` or account deleted):
``` json
{
"error": "Driver account is blocked or deactivated"
}
```
#### 6\. `500 Internal Server Error` — Server / Database Failure
``` json
{
"error": "Failed to process driver signin"
}
```
Or:
``` json
{
"error": "Internal server error during driver signin"
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Successfully registered or logged in; profile and auth tokens returned. |
| **`400 Bad Request`** | Validation failure on request body, or invalid referral code. |
| **`403 Forbidden`** | Driver account is blocked or soft-deleted. |
| **`500 Internal Server Error`** | Uncaught database or server processing error. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
This endpoint expects an object.
phone