Submit Driver KYC Document
# Submit Driver KYC Document
Submits or re-submits a verification document (Driving Licence, Aadhaar, PAN, Vehicle RC, Insurance, etc.) for the authenticated driver.
> **💡 Upsert & Workflow Behavior:** Re-submitting an existing document type updates the record, clears previous rejection reasons, and resets verification_status back to "PENDING".
On the driver's first document submission, the driver account status automatically transitions from PENDING_ONBOARDING to PENDING_APPROVAL.
---
### Endpoint Overview
- **Method:** `POST`
- **Route:** `/api/v1/driver/documents`
- **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 | Nullable | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- | --- |
| `document_type` | `enum` | **Yes** | No | `"DRIVING_LICENCE""AADHAAR""PAN""VEHICLE_RC""VEHICLE_MODEL_NUMBER""PERMIT""INSURANCE""FITNESS_CERTIFICATE"` | Category of document submitted |
| `front_image_url` | `string` | Conditional | Yes | Valid URL | Hosted URL of the front side of document |
| `back_image_url` | `string` | Conditional | Yes | Valid URL | Hosted URL of the back side of document |
| `document_number` | `string` | Conditional | Yes | Any string | Identifier number (e.g. DL, Aadhaar, PAN, RC number) |
| `name_on_doc` | `string` | Conditional | Yes | Any string | Name as printed on document (required for `PAN`) |
| `date_of_birth` | `string` | Conditional | Yes | ISO 8601 Date string | Date of birth (required for `DRIVING_LICENCE`) |
| `fuel_type` | `enum` | Conditional | Yes | `"PETROL"`, `"DIESEL"`, `"CNG"`, `"ELECTRIC"` | Vehicle fuel type (required for `VEHICLE_RC`) |
| `vehicle_model_number` | `string` | Conditional | Yes | Any string | Required for `VEHICLE_MODEL_NUMBER` |
---
### Per-Document Required Fields Matrix
| Document Type | Required Fields |
| --- | --- |
| `DRIVING_LICENCE` | `front_image_url`, `back_image_url`, `document_number`, `date_of_birth` |
| `AADHAAR` | `front_image_url`, `document_number` |
| `PAN` | `front_image_url`, `document_number`, `name_on_doc` |
| `VEHICLE_RC` | `front_image_url`, `back_image_url`, `document_number`, `fuel_type` |
| `VEHICLE_MODEL_NUMBER` | `vehicle_model_number` |
| `PERMIT` | `front_image_url` |
| `INSURANCE` | `front_image_url` |
| `FITNESS_CERTIFICATE` | `front_image_url` |
---
### Request Body Examples
#### Example 1: Driving Licence
``` json
{
"document_type": "DRIVING_LICENCE",
"front_image_url": "https://storage.example.com/docs/dl_front.jpg",
"back_image_url": "https://storage.example.com/docs/dl_back.jpg",
"document_number": "KA0120200012345",
"date_of_birth": "1992-05-15"
}
```
#### Example 2: Vehicle RC
``` json
{
"document_type": "VEHICLE_RC",
"front_image_url": "https://storage.example.com/docs/rc_front.jpg",
"back_image_url": "https://storage.example.com/docs/rc_back.jpg",
"document_number": "KA-01-AB-1234",
"fuel_type": "PETROL"
}
```
#### Example 3: PAN Card
``` json
{
"document_type": "PAN",
"front_image_url": "https://storage.example.com/docs/pan_front.jpg",
"document_number": "ABCDE1234F",
"name_on_doc": "Ravi Kumar"
}
```
---
### Response Body Schema (`200 OK`)
| Top-Level Key | Data Type | Description |
| --- | --- | --- |
| `message` | `string` | Confirmation message (`"Document submitted successfully"`) |
| `document` | `object` | The inserted or updated document record |
#### `document` Object Fields
| Field | Data Type | Nullable | Allowed Values / Constraints | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` | No | Prefixed with `ddoc_` | Unique document record ID |
| `driverId` | `string` | No | Prefixed with `drv_` | ID of driver submitting document |
| `document_type` | `enum` | No | Same as request enum | Submitted document category |
| `front_image_url` | `string` | Yes | URL | URL of front side image |
| `back_image_url` | `string` | Yes | URL | URL of back side image |
| `document_number` | `string` | Yes | String | Document identifier number |
| `name_on_doc` | `string` | Yes | String | Name on document |
| `date_of_birth` | `string` | Yes | ISO 8601 Timestamp | Date of birth |
| `fuel_type` | `enum` | Yes | `"PETROL"`, `"DIESEL"`, `"CNG"`, `"ELECTRIC"` | Fuel type (for RC) |
| `vehicle_model_number` | `string` | Yes | String | Model number |
| `verification_status` | `enum` | No | `"PENDING""APPROVED""REJECTED"` | Admin verification status (defaults to `"PENDING"`) |
| `rejection_reason` | `string` | Yes | String | Feedback if rejected by admin |
| `verified_at` | `string` | Yes | ISO 8601 Timestamp | Timestamp when admin approved/rejected |
| `verified_by` | `string` | Yes | Admin ID | ID of admin who reviewed |
| `created_at` | `string` | No | ISO 8601 Timestamp | Initial submission timestamp |
| `updated_at` | `string` | No | ISO 8601 Timestamp | Last update timestamp |
---
### Response Examples
#### 1\. `200 OK` — Document Submitted Successfully
``` json
{
"message": "Document submitted successfully",
"document": {
"id": "ddoc_9a8b7c6d5e",
"driverId": "drv_8a7b6c5d4e",
"document_type": "DRIVING_LICENCE",
"front_image_url": "https://storage.example.com/docs/dl_front.jpg",
"back_image_url": "https://storage.example.com/docs/dl_back.jpg",
"document_number": "KA0120200012345",
"name_on_doc": null,
"date_of_birth": "1992-05-15T00:00:00.000Z",
"fuel_type": null,
"vehicle_model_number": null,
"verification_status": "PENDING",
"rejection_reason": null,
"verified_at": null,
"verified_by": null,
"created_at": "2026-09-21T05:30:00.000Z",
"updated_at": "2026-09-21T05:30:00.000Z"
}
}
```
#### 2\. `400 Bad Request` — Missing Required Per-Document Field
``` json
{
"error": "Licence number is required for Driving Licence"
}
```
Or for Vehicle RC:
``` json
{
"error": "Fuel type is required for Vehicle RC"
}
```
#### 3\. `400 Bad Request` — Schema / Type Validation Error
``` json
{
"success": false,
"message": "Validation failed: document_type: Invalid enum value",
"errors": [
{
"field": "document_type",
"message": "Invalid enum value"
}
]
}
```
#### 4\. `401 Unauthorized` — Missing / Expired Token / Revoked Session
``` json
{
"error": "Unauthorized",
"message": "Invalid or expired driver access token."
}
```
#### 5\. `403 Forbidden` — Account Blocked / Deactivated
``` json
{
"error": "Forbidden",
"message": "Driver account is blocked or deactivated."
}
```
#### 6\. `500 Internal Server Error`
``` json
{
"error": "Failed to submit document"
}
```
---
### Status Codes Reference
| HTTP Status Code | Condition |
| --- | --- |
| **`200 OK`** | Document successfully stored or updated with status reset to `PENDING`. |
| **`400 Bad Request`** | Missing required document fields (e.g. missing licence number or invalid fuel type). |
| **`401 Unauthorized`** | Missing, invalid, expired token or session revoked. |
| **`403 Forbidden`** | Driver account is deactivated or blocked. |
| **`500 Internal Server Error`** | Server or database query error. |
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.