---
feature: Driver onboarding and account review status
slug: onboarding
surface: delivery
consumer: flutter
version: 1.0.1
status: ready
brd_version: "1.3"
brd_ids: [DRIV-002, DRIV-003]
business_rules: [BR-01, BR-03, BR-04]
decisions: [DEC-15, DEC-18, DEC-25, TD-01, TD-09, TD-14, TD-19, TD-25, TD-35, TD-43, TD-44, TD-48, TD-50, TD-51, TD-52, TD-56, TD-57, TD-59, TD-63, TD-64, TD-65, TD-66, TD-67]
schema_tables: [drivers, vehicles, driver_districts, user_documents, account_review_events, platform_settings, users, media, payout_accounts]
screens: ["driver--registration--0[2-3]-*"]
related_docs: [auth.md, ../provider/onboarding.md, ../admin/drivers.md]
last_updated: 2026-10-26
---

# Driver onboarding — Flutter Integration Guide (delivery)

> **Base URL:** `{HOST}/api/v1/delivery` · Shared headers, envelope, errors and Dio setup: [API_CONVENTIONS.md](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.1 | 2026-10-26 | PATCH | Documentation only: validation 422 examples and rows now show `data.errors` (`{field: [messages]}`, TD-02, API_CONVENTIONS 2.7.0) instead of `data: null`; examples are the captured Postman responses. | None. |
| 1.0.0 | 2026-10-22 | Initial | SCR-19 drafts, active vehicle, document replacement, submission/resubmission and review status. | Integrate all three routes after driver OTP; use backend flags and separate submission/activation missing lists. |

## Changelog

### 1.0.1 — 2026-10-26

- **Added:** N/A.
- **Changed:** Validation 422 examples and error-table rows show `data.errors`, not `data: null` (TD-02).
- **Fixed:** Documentation only; the server already returned `data.errors`.
- **Removed / Deprecated:** N/A.
- **Breaking:** No.
- **Endpoints affected:** None (documentation).
- **App action required:** None; map `data.errors` onto form fields, fall back to `message`.
- **BRD / decisions:** TD-02.

### 1.0.0 — 2026-10-22

- **Added:** GET/PUT onboarding and POST submit, role-scoped uploads, masked identifiers, public plate, status timeline and completion flags.
- **Changed:** provider and delivery now share Domain onboarding rules/actions and review-document policy; provider API contract is unchanged.
- **Fixed:** N/A.
- **Removed / Deprecated:** N/A.
- **Breaking:** No; initial release.
- **Endpoints affected:** `GET /api/v1/delivery/onboarding`, `PUT /api/v1/delivery/onboarding`, `POST /api/v1/delivery/onboarding/submit`.
- **App action required:** upload documents first, save a draft, submit separately, then refresh status; send only edited values, never masked IDs back as original numbers.
- **BRD / decisions:** DRIV-002/003, SCR-19; TD-65–67, existing review/masking decisions.

## 1. Business summary

After driver OTP registration, complete the SCR-19 full name, national ID, vehicle and three document uploads, then submit for admin review. City, districts, photo, birth date, nationality and payout account are completed before going online and do not block registration submission. During review, onboarding is read-only; rejected accounts can edit and resubmit according to the driver setting. Approval permits operational access, while availability and dispatch still enforce their own completion/coverage rules.

The base stores the name in `users.full_name`, shared across this person's app profiles. This feature does not add `users.name` or a second driver-name column.

## 2. User flow and screens

Only these three requested screens were opened.

| Step | Screen / widget | Endpoint | Notes (states, empty, loading, errors) |
|------|-----------------|----------|---------------------------------------|
| 1 | `driver--registration--02-data-docs-p1.png` | GET/PUT `/onboarding` | Full name, national ID and structured vehicle fields. Load saved values; omit unchanged masked fields. |
| 2 | `driver--registration--02-data-docs-p2.png` | Shared `POST /api/v1/media`, PUT `/onboarding`, POST `/onboarding/submit` | ID, driving license and vehicle registration; show upload progress/retry and submit from `can_submit`. |
| 3 | `driver--registration--03-under-review.png` | GET `/onboarding` | Received → verifying documents → activated. Show reason and edit/resubmit only from backend flags. Prototype simulation controls have no API. |

1. Complete [driver auth](auth.md), including BR-01 declaration, terms and privacy acceptance.
2. GET saved onboarding. A new account has `vehicle: null`, `documents: []`, nullable `national_id`, missing lists and `can_edit: true`.
3. Upload each file through shared multipart `POST /api/v1/media` with `collection=file`; keep returned `data.hash` for the draft.
4. PUT changed fields and fresh upload hashes. Saving never submits, even when complete.
5. POST submit with no body. Refresh GET after submission or admin review; use existing `/auth/me` for app routing too.
6. Present `missing_for_activation` as later profile-completion guidance. This endpoint never turns the driver online.

## 3. Endpoints

All routes require `Authorization: Bearer {delivery_token}` with JWT `app=driver`, `auth:api`, `app:driver`, and `active`. They sit outside `approved`, so status remains readable before approval and after rejection/suspension. No admin RBAC permission, `Idempotency-Key`, extra query/header or endpoint-specific throttle applies. Use `Accept-Language: ar` or `en`; responses use `Cache-Control: no-store, private`.

### 3.1 Read saved onboarding and review status

`GET /api/v1/delivery/onboarding` — `delivery.onboarding.show`.

**Path / query parameters:** N/A. **Request body:** N/A. The authenticated driver is always the owner; no target profile ID is accepted.

**Success — 200, real MySQL HTTP test:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-9e5f-720b-a63c-009d986b6314",
    "account_status": {
      "value": "pending_review",
      "label": "Pending review"
    },
    "status_reason": null,
    "submitted_at": "2026-10-22T08:41:20+00:00",
    "timeline": [
      {
        "key": "received",
        "label": "Application received",
        "state": "completed"
      },
      {
        "key": "verifying_documents",
        "label": "Verifying documents",
        "state": "current"
      },
      {
        "key": "activated",
        "label": "Account activated",
        "state": "waiting"
      }
    ],
    "full_name": "Maha Al Zahrani",
    "national_id": "****1234",
    "vehicle": {
      "id": "01a162c5-9eb6-722e-aced-5a99dbe089ca",
      "vehicle_type": {
        "value": "car",
        "label": "Car"
      },
      "make_model": "Toyota Yaris",
      "plate_number": "أ ب ج 1234",
      "model_year": 2024,
      "color": "White",
      "is_active": true
    },
    "documents": [
      {
        "id": "01a162c5-9eb9-72d5-b501-f0f6bc3fb0d9",
        "doc_type": {
          "value": "national_id",
          "label": "National ID / iqama"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/d7dce128-f8ee-47b6-b376-9048ae2bb58f.pdf"
      },
      {
        "id": "01a162c5-9ec1-7243-9b66-2848d06a02f2",
        "doc_type": {
          "value": "driving_license",
          "label": "Driving license"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/9d1e9e13-cb5d-40e1-b408-607c47c8c5f9.pdf"
      },
      {
        "id": "01a162c5-9ec7-71c1-82c5-2c64cf18e43d",
        "doc_type": {
          "value": "vehicle_registration",
          "label": "Vehicle registration"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/1990ec27-38b3-44d0-bd28-5f8f75560bbe.pdf"
      }
    ],
    "missing_for_submission": [],
    "missing_for_activation": [
      "city",
      "districts",
      "photo",
      "birth_date",
      "nationality",
      "payout_account",
      "account_status"
    ],
    "can_edit": false,
    "can_submit": false
  }
}
```

**Response fields** (same projection for all three routes):

| Field | Type / nullable | Meaning |
|-------|-----------------|---------|
| `id` | UUID string | Driver profile public UUID. |
| `account_status` | `{value,label}` | Exact schema account status, localized label. |
| `status_reason` | string / null | Current admin review reason; cleared by successful submit. |
| `submitted_at` | ISO 8601 / null | Most recent successful submission. |
| `timeline` | three `{key,label,state}` rows | `received`, `verifying_documents`, `activated`; each state completed/current/waiting. See §4. |
| `full_name` | string | Actual base `users.full_name`, also used by the person's other apps. |
| `national_id` | string / null | `****` plus last four; values of four characters or fewer reveal no suffix. |
| `vehicle` | object / null | Owned active vehicle only. Historical inactive vehicles remain stored. |
| `vehicle.id` | UUID string | Preserved across editable vehicle updates. |
| `vehicle.vehicle_type` | `{value,label}` | `car` or `motorbike`. |
| `vehicle.make_model`, `vehicle.plate_number` | strings | Single make/model field and public, unmasked plate (TD-51). |
| `vehicle.model_year`, `vehicle.color` | integer / null, string / null | Optional saved information. |
| `vehicle.is_active` | bool | True for the returned active vehicle. |
| `documents` | array | Driver-role documents only, oldest first, including historical replaced rows. |
| `documents[].id` | UUID string | Document public UUID. |
| `documents[].doc_type`, `documents[].status` | `{value,label}` | Schema type/status. |
| `documents[].doc_number` | string / null | Masked using the same policy as national ID. |
| `documents[].expires_at` | YYYY-MM-DD / null | Date-only expiry. |
| `documents[].file_url` | string / null | Existing Media module file projection; no raw internal media ID. |
| `missing_for_submission` | string[] | Stable `full_name`, `national_id`, `vehicle`, `documents.national_id`, `documents.driving_license`, `documents.vehicle_registration` keys. |
| `missing_for_activation` | string[] | Stable `city`, `districts`, `photo`, `birth_date`, `nationality`, `payout_account`, `account_status` completion keys. |
| `can_edit`, `can_submit` | bool | Enforced by backend; submit additionally needs no missing submission requirements. |

`missing_for_activation` checks actual saved records: city present, at least one driver district, a `users.image` media row, birth date/nationality present, a primary non-inactive driver payout account and approved status. It is completion guidance, not online or dispatch authorization. The list does not disclose bank values and does not affect `can_submit`.

**Errors:** 401 `UNAUTHENTICATED`; 403 `PERMISSION_DENIED` for another app/missing driver profile; 403 `ACCOUNT_INACTIVE` for disabled/banned users. See §3.4. Any review status can read this route.

### 3.2 Save a registration draft

`PUT /api/v1/delivery/onboarding` — `delivery.onboarding.update`.

**Path / query parameters:** N/A. **Request body:** `application/json`, all top-level keys optional.

| Field | Type | Required | Validation / description |
|-------|------|----------|--------------------------|
| `full_name` | string | If supplied | Nonempty, max255; updates base `users.full_name`. Omit to preserve. |
| `national_id` | string / null | No | Max20; required on submit. Omit to preserve; null clears. |
| `vehicle` | object | No | Allowed keys below only; cannot be null. Omit to preserve. |
| `vehicle.vehicle_type` | string | With vehicle | `car` or `motorbike`. |
| `vehicle.make_model` | string | With vehicle | Nonempty, max100; one combined field. |
| `vehicle.plate_number` | string | With vehicle | Nonempty, max20; returned publicly. |
| `vehicle.model_year` | integer / null | No | -32768…32767, schema SMALLINT capacity; no invented age/model-year rule. |
| `vehicle.color` | string / null | No | Max40. |
| `documents` | list of objects | No | Omitted/empty preserves existing documents. Each entry has only the four keys below. |
| `documents[].doc_type` | string | Per entry | One of `national_id`, `driving_license`, `vehicle_registration`; distinct per request. |
| `documents[].file` | string hash | Per entry | Fresh, unattached own media upload, distinct per request, image or PDF up to 5 MiB, physical file present. |
| `documents[].doc_number` | string / null | No | Max50, returned masked. |
| `documents[].expires_at` | date / null | No | YYYY-MM-DD; past dates save but block submit. |

**Real captured request** (the hashes illustrate previously uploaded test files; obtain fresh hashes in the app):

```json
{
  "full_name": "Maha Al Zahrani",
  "national_id": "1000001234",
  "vehicle": {
    "vehicle_type": "car",
    "make_model": "Toyota Yaris",
    "plate_number": "أ ب ج 1234",
    "model_year": 2024,
    "color": "White"
  },
  "documents": [
    {
      "doc_type": "national_id",
      "file": "d7dce128-f8ee-47b6-b376-9048ae2bb58f",
      "doc_number": "1000001234"
    },
    {
      "doc_type": "driving_license",
      "file": "9d1e9e13-cb5d-40e1-b408-607c47c8c5f9",
      "doc_number": "1000001234"
    },
    {
      "doc_type": "vehicle_registration",
      "file": "1990ec27-38b3-44d0-bd28-5f8f75560bbe",
      "doc_number": "1000001234"
    }
  ]
}
```

Unknown top-level keys do not change status, approver, online state or ownership. Unknown nested vehicle/document keys produce 422 validation.

A supplied vehicle updates the existing owned active row in place, preserving its UUID. If there is no active row, one is created; inactive history is retained. Optional year/color preserve omitted values and clear on explicit null. There is no vehicle ID, driver ID or active-status input, and no second active row is created.

Each document replacement marks previous same-driver-role/type rows `replaced`, creates a fresh `pending` row, and attaches the hash. Old review metadata and files remain on historical rows. Provider-role rows for the same person are untouched. The complete draft transaction rolls back if any write fails.

**Success — 200, real saved draft:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-9e5f-720b-a63c-009d986b6314",
    "account_status": {
      "value": "incomplete",
      "label": "Incomplete"
    },
    "status_reason": null,
    "submitted_at": null,
    "timeline": [
      {
        "key": "received",
        "label": "Application received",
        "state": "waiting"
      },
      {
        "key": "verifying_documents",
        "label": "Verifying documents",
        "state": "waiting"
      },
      {
        "key": "activated",
        "label": "Account activated",
        "state": "waiting"
      }
    ],
    "full_name": "Maha Al Zahrani",
    "national_id": "****1234",
    "vehicle": {
      "id": "01a162c5-9eb6-722e-aced-5a99dbe089ca",
      "vehicle_type": {
        "value": "car",
        "label": "Car"
      },
      "make_model": "Toyota Yaris",
      "plate_number": "أ ب ج 1234",
      "model_year": 2024,
      "color": "White",
      "is_active": true
    },
    "documents": [
      {
        "id": "01a162c5-9eb9-72d5-b501-f0f6bc3fb0d9",
        "doc_type": {
          "value": "national_id",
          "label": "National ID / iqama"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/d7dce128-f8ee-47b6-b376-9048ae2bb58f.pdf"
      },
      {
        "id": "01a162c5-9ec1-7243-9b66-2848d06a02f2",
        "doc_type": {
          "value": "driving_license",
          "label": "Driving license"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/9d1e9e13-cb5d-40e1-b408-607c47c8c5f9.pdf"
      },
      {
        "id": "01a162c5-9ec7-71c1-82c5-2c64cf18e43d",
        "doc_type": {
          "value": "vehicle_registration",
          "label": "Vehicle registration"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/1990ec27-38b3-44d0-bd28-5f8f75560bbe.pdf"
      }
    ],
    "missing_for_submission": [],
    "missing_for_activation": [
      "city",
      "districts",
      "photo",
      "birth_date",
      "nationality",
      "payout_account",
      "account_status"
    ],
    "can_edit": true,
    "can_submit": true
  }
}
```

**Errors:** shared auth/access errors; 422 validation for malformed name/vehicle/documents, wrong type, duplicate type/hash, unknown/attached/missing-storage file; 422 `BUSINESS_RULE_VIOLATED` for a foreign uploader, non-temporary file, unsupported MIME or oversized file; 409 `INVALID_STATE_TRANSITION` for locked states/disabled rejection resubmission; 500 `INTERNAL_ERROR` for unexpected persistence failure with rollback. See §3.4 and the captured examples.

### 3.3 Submit for admin review

`POST /api/v1/delivery/onboarding/submit` — `delivery.onboarding.submit`.

**Path / query parameters:** N/A. **Request body:** N/A. Save the draft first.

The shared `RuleChain` checks editable state, full name, national ID, an active vehicle with model/plate, and exactly the required document types from the shared initial-approval policy (TD-50/52/59). Qualifying driver-role files are pending or verified, attached, and unexpired: null expiry and expiry today in UTC qualify; rejected/expired/replaced/wrong-role/missing-file rows do not. Optional model year/color and activation completion never block submission.

Within one transaction, the service locks the profile, checks prerequisites, changes `account_status` to `pending_review`, refreshes `submitted_at`, clears `status_reason` and inserts one `submitted` review event with explicit from/to statuses and driver actor. The existing `admin_id` users FK carries the submitting driver actor, as for provider submission (TD-43/66). It does not approve or verify documents. A repeated submit returns 409 and creates no second event.

**Success — 200, real submitted registration:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-9e5f-720b-a63c-009d986b6314",
    "account_status": {
      "value": "pending_review",
      "label": "Pending review"
    },
    "status_reason": null,
    "submitted_at": "2026-10-22T08:41:20+00:00",
    "timeline": [
      {
        "key": "received",
        "label": "Application received",
        "state": "completed"
      },
      {
        "key": "verifying_documents",
        "label": "Verifying documents",
        "state": "current"
      },
      {
        "key": "activated",
        "label": "Account activated",
        "state": "waiting"
      }
    ],
    "full_name": "Maha Al Zahrani",
    "national_id": "****1234",
    "vehicle": {
      "id": "01a162c5-9eb6-722e-aced-5a99dbe089ca",
      "vehicle_type": {
        "value": "car",
        "label": "Car"
      },
      "make_model": "Toyota Yaris",
      "plate_number": "أ ب ج 1234",
      "model_year": 2024,
      "color": "White",
      "is_active": true
    },
    "documents": [
      {
        "id": "01a162c5-9eb9-72d5-b501-f0f6bc3fb0d9",
        "doc_type": {
          "value": "national_id",
          "label": "National ID / iqama"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/d7dce128-f8ee-47b6-b376-9048ae2bb58f.pdf"
      },
      {
        "id": "01a162c5-9ec1-7243-9b66-2848d06a02f2",
        "doc_type": {
          "value": "driving_license",
          "label": "Driving license"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/9d1e9e13-cb5d-40e1-b408-607c47c8c5f9.pdf"
      },
      {
        "id": "01a162c5-9ec7-71c1-82c5-2c64cf18e43d",
        "doc_type": {
          "value": "vehicle_registration",
          "label": "Vehicle registration"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/1990ec27-38b3-44d0-bd28-5f8f75560bbe.pdf"
      }
    ],
    "missing_for_submission": [],
    "missing_for_activation": [
      "city",
      "districts",
      "photo",
      "birth_date",
      "nationality",
      "payout_account",
      "account_status"
    ],
    "can_edit": false,
    "can_submit": false
  }
}
```

**Errors:** shared auth/access errors; 422 `BUSINESS_RULE_VIOLATED` naming missing requirements; 409 `INVALID_STATE_TRANSITION` for locked states or rejection setting false; 500 `INTERNAL_ERROR` with transaction rollback on persistence failure.

### 3.4 Errors and app behavior

| HTTP | `data.error_code` | When | App action |
|------|-------------------|------|------------|
| 401 | `UNAUTHENTICATED` | Missing/expired driver JWT | Use delivery auth/refresh. |
| 403 | `PERMISSION_DENIED` | Provider/customer/admin token or no matching driver profile | Authenticate through driver app. |
| 403 | `ACCOUNT_INACTIVE` | Banned/disabled user; unapproved operational request | Show account outcome. Approval middleware also returns account status; onboarding reads remain available to active users. |
| 422 | absent (`data.errors`) | Invalid draft shape/reference | Mark fields from `data.errors`; fall back to the localized `message` (TD-02). |
| 422 | `BUSINESS_RULE_VIOLATED` | Missing submission requirement or invalid fresh upload ownership/type/size | Display message; refetch GET and highlight stable missing keys. |
| 409 | `INVALID_STATE_TRANSITION` | Pending/approved/suspended, or rejected with setting false | Refresh status and backend flags; do not automatically retry the mutation. |
| 500 | `INTERNAL_ERROR` | Unexpected persistence error, transaction rolled back | Keep local input, refetch state before retry; retain correlation ID for support. |

**Missing active vehicle, real response:**

```json
{
  "status": "fail",
  "message": "Submission requires: Active vehicle with type, model and plate (vehicle).",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "context": {
      "violations": [
        "Submission requires: Active vehicle with type, model and plate (vehicle)."
      ]
    },
    "correlation_id": "edee4553-cc5d-41ae-9dba-22a3580a5ea5"
  }
}
```

**Already submitted, real response:**

```json
{
  "status": "fail",
  "message": "Onboarding cannot be edited or submitted while the account is Pending review.",
  "data": {
    "error_code": "INVALID_STATE_TRANSITION",
    "correlation_id": "38c17fa3-40a7-4bfc-8286-c1713a4071ec"
  }
}
```

**Invalid document type, real validation response:**

```json
{
  "status": "fail",
  "message": "The selected documents.0.doc_type is invalid.",
  "data": {
    "errors": {
      "documents.0.doc_type": [
        "The selected documents.0.doc_type is invalid."
      ]
    }
  }
}
```

Other real success/error variants are in [GET examples](../postman-collection.json) (Postman: `delivery.onboarding.show`, every saved response), [PUT examples](../postman-collection.json) (Postman: `delivery.onboarding.update`, every saved response) and [submit examples](../postman-collection.json) (Postman: `delivery.onboarding.submit`, every saved response). The 500 examples use deliberate test persistence failures; their text is not a stable app contract. TD-56 reuses captured surface-wide authentication/access examples in the [generated collection](../postman-collection.json).

## 4. Statuses and enums

| Account status | Meaning | `can_edit` / `can_submit` |
|----------------|---------|--------------------------|
| `incomplete` | Saved draft | Edit true; submit when requirements complete. |
| `pending_review` | Submitted, awaiting review | Both false. |
| `needs_changes` | Admin requested corrections | Edit true; submit when complete, regardless of rejection setting. |
| `approved` | Admin approved | Both false; later changes use reviewed profile-change workflow. |
| `rejected` | Admin rejected | Both depend on driver rejection setting and completeness. |
| `suspended` | Admin suspended | Both false; reactivation belongs to admin. |

`driver_resubmission_after_rejection` is read from `platform_settings`: absent defaults true; only JSON true enables rejection edits/resubmission. Provider's setting is independent. Every submit refreshes the received timestamp and clears the reason.

Vehicle types: `car`, `motorbike`. Saved document statuses: `pending`, `verified`, `rejected`, `expired`, `replaced`. Driver submission accepts national_id/driving_license/vehicle_registration; reads retain other historical driver-role schema document types if present. All enum values use `{value,label}`.

Timeline is always the same three steps. Received completes once submitted_at exists; verifying is current while pending_review, completes when all required files qualify as verified; activated completes only for approved. It does not invent dates or successful activation for rejected/needs_changes/suspended.

## Data model

| Table (`db-schema.sql`) | Read / write | Notes |
|-------------------------|--------------|-------|
| `drivers` | read + write | National ID, review state/reason/submission; never online or approval metadata through PUT. |
| `vehicles` | read + write | Owned active registration vehicle, updated in place; generated active_key/ux_vehicle_active retained. |
| `driver_districts` | read | Activation guidance only; pure link, no public UUID. |
| `user_documents` | read + write | Driver role, new pending replacement rows and preserved history. |
| `account_review_events` | write | Submitted action and owner actor, from/to state, inside transaction. |
| `platform_settings` | read | Driver rejection policy; no seeded value required for default true. |
| `users` | read + write | Existing full_name; image media for completion; auth/consents remain auth-owned. |
| `media` | read + attach | Fresh upload hash, exact uploader match; existing file collections, no URL columns. |
| `payout_accounts` | read | Primary/non-inactive driver payout completion; no bank values exposed. |

No migration, column, status, table or dependency was added. `Driver.vehicles` and district ownership use `drivers.user_id` internally; API profile/vehicle/document IDs use UUIDs.

## 5. Dart models

Use shared `EnumValue` and ISO parsing from API_CONVENTIONS. Keep nullable keys even when empty; parse vehicle as null until saved.

```dart
class DriverOnboarding {
  final String id;
  final EnumValue accountStatus;
  final String? statusReason;
  final DateTime? submittedAt;
  final String fullName;
  final String? nationalId; // masked: never echo this into an update
  final Map<String, dynamic>? vehicle;
  final List<Map<String, dynamic>> documents;
  final List<Map<String, dynamic>> timeline;
  final List<String> missingForSubmission;
  final List<String> missingForActivation;
  final bool canEdit;
  final bool canSubmit;

  DriverOnboarding.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        accountStatus = EnumValue.fromJson(j['account_status']),
        statusReason = j['status_reason'] as String?,
        submittedAt = j['submitted_at'] == null
            ? null : DateTime.parse(j['submitted_at'] as String),
        fullName = j['full_name'] as String,
        nationalId = j['national_id'] as String?,
        vehicle = j['vehicle'] == null
            ? null : Map<String, dynamic>.from(j['vehicle']),
        documents = (j['documents'] as List)
            .map((v) => Map<String, dynamic>.from(v)).toList(),
        timeline = (j['timeline'] as List)
            .map((v) => Map<String, dynamic>.from(v)).toList(),
        missingForSubmission = List<String>.from(j['missing_for_submission']),
        missingForActivation = List<String>.from(j['missing_for_activation']),
        canEdit = j['can_edit'] as bool,
        canSubmit = j['can_submit'] as bool;
}
```

Vehicle `id` is a string UUID, `vehicle_type` is EnumValue, `model_year` is nullable int and `color` nullable string. Document `expires_at` is date-only, not a timestamp; other document enum and masking rules are in §3.1.

## 6. Business rules enforced by the backend

| Rule | Backend behavior | What the user sees |
|------|------------------|--------------------|
| BR-01 / DEC-18 | Existing OTP registration requires all three consents, records profile acceptance; declaration-only eligibility | Complete consent during auth; no extra invented eligibility gate here. |
| BR-03 | Driver JWT/profile isolation; unapproved accounts cannot pass operational middleware | Read review status while waiting; no transportation access. |
| BR-04 / TD-44 | Approved/suspended draft mutations denied | Use future reviewed change-request process for approved changes. |
| SCR-19 / TD-65 | Registration fields/docs/active vehicle separate from activation checklist | Submit without city/district/photo/birth date/nationality/payout. |
| TD-35/43/66 | Explicit states, submission event and refresh of timestamp/reason atomically | Double submit and locked-state edit return 409; rejected policy uses flags. |
| TD-50/52/59 | Submission and initial approval share required document policy; active vehicle required | Correct missing/expired documents or vehicle before submit. |
| TD-51/63/67 | Masked identity, public plate; own fresh upload hashes; replacement history | Preserve masked values by omission; upload a fresh replacement file. |

Shared code lives in `app/Domain/Onboarding` and `app/Domain/AccountReview`; surface services do not call each other.

## 7. Notifications and real-time events

Submitting saves an account review event; it does not send external push or simulate admin approval. Existing admin review emits a transactional in-app inbox notification; external delivery is the owning ADMIN-020 feature.

| Inbox event key | When | Payload `data` keys | App action |
|-----------------|------|---------------------|------------|
| `account_review_status_changed` | Admin approve/reject/request-changes/suspend/reactivate | `profile_id`, `account_status`, `action`, `reason` | Refetch onboarding and auth/me. |

See [admin driver review](../admin/drivers.md) and [shared inbox](../API_CONVENTIONS.md#7-shared-in-app-notifications-all-apps). No new realtime subscription, polling interval or review duration is defined.

## 8. Localization and UI notes

- Request `ar` or `en`; machine keys remain stable while enum/timeline/error labels localize.
- Map missing keys to app-owned Arabic/English field labels; keep plate letters/numbers in a readable mixed-direction container.
- Display only the masked saved ID; leave its edit control untouched until the driver explicitly replaces the value.
- On loading disable actions; on failure keep unsaved edits and offer retry. Null vehicle and empty document list are normal draft states.
- Show status reason for correction/rejection; use backend flags even when the prototype has an edit button.
- Show date-only document expiry without timezone shifts; submitted_at is ISO 8601 with offset.

## 9. Integration checklist

- [ ] Parse real responses with stable nullable keys, UUID strings, enum objects and separate missing lists.
- [ ] Use driver auth token and the shared upload → fresh hash → PUT flow.
- [ ] Send all three required vehicle fields when vehicle is supplied; omit untouched year/color and identity fields.
- [ ] Make POST submit a separate action and refresh after any 409 or review notification.
- [ ] Respect can_edit/can_submit and handle every error in §3.4.
- [ ] Implement loading/empty/upload-failure/error/correction/rejected/approved/suspended states in Arabic and English.
- [ ] Complete activation information in its owning profile/availability flow before offering online status.

## 10. Acceptance scenarios

Tests: [Delivery OnboardingTest](../../tests/Feature/Api/V1/Delivery/OnboardingTest.php), AC-named, run on MySQL `joshen_testing`.

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-DRIV-002 | Complete car/motorbike registration | Save then submit with three attached files; activation fields remain separate. |
| AC-DRIV-002 | Missing name/national ID/vehicle; inactive vehicle | 422 BUSINESS_RULE_VIOLATED, missing keys, no submission writes. |
| AC-DRIV-002 | Missing each document; past expiry, invalid status, missing file or provider role | Shared policy refuses submission. Expiry today and verified documents qualify. |
| AC-DRIV-002 | Edit active vehicle repeatedly | Same UUID, one active vehicle; inactive history and omitted values preserved. |
| AC-DRIV-002 | Replace document or invalid upload | Old row/file preserved; correct role only; foreign/attached/oversized/unsupported uploads denied. |
| AC-DRIV-002/003 | Persistence failure | Name/profile/vehicle/doc/media or status/event writes roll back atomically. |
| AC-DRIV-003 | Double submit; edit while pending/approved/suspended | 409, one submission event, no locked-state mutations. |
| AC-DRIV-003 | Needs changes or rejected | Settings govern rejected edits/resubmit; needs_changes always allowed; new timestamp and cleared reason. |
| AC-DRIV-003 | Provider/customer token, missing driver profile, guest | 403 or 401 on every onboarding route. |
| AC-DRIV-003 | Unapproved account attempts operations | Existing approval middleware denies all unapproved states; status read allowed. |
| AC-DRIV-003 | OTP registration → shared upload → submit → admin approve | Documents verified, timeline activated, auth/me approved; online remains false. |

## 11. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| TD-65/66 | Owner-supplied working assumptions | SCR-19-only submit and absent-default-true rejection policy implemented as logged. |
| DEC-15 | SMS gateway selection | Existing auth delivery limitation remains; no gateway added here. |
| DEC-18 | Female-user eligibility | Declaration-only, no additional verification. |
| DEC-25 / TD-44 | Post-approval profile/document/bank changes | Reviewed change-request contract remains deferred; onboarding refuses approved/suspended edits. |
| DRIV-006/007 | Profile completion, online availability and dispatch eligibility | This feature reports completion guidance. It neither implements missing profile endpoints nor certifies dispatch eligibility. |
| BR-03 | Operational route acceptance boundary | Driver operational routes remain placeholders. Tests exercise a test-only route using the real approved middleware; this is not live trip/dispatch acceptance. |
| TD-50/59 | Document qualification | Uses existing attached Media row/status/expiry policy; physical storage existence is additionally checked when saving fresh hashes. |
| Local acceptance | Deployment | MySQL HTTP/OTP/admin cycle and generated Postman coverage are local evidence; no deployed/mobile/stakeholder acceptance claimed. |
