---
feature: Review of provider and driver change requests
slug: profile-change-requests
surface: admin
consumer: react
version: 1.0.0
status: ready
brd_version: "1.3"
brd_ids: [ADMIN-004, ADMIN-006]
business_rules: [BR-04, BR-29]
decisions: [DEC-25, TD-44, TD-184]
schema_tables: [profile_change_requests, payout_accounts, user_documents, vehicles, providers, drivers]
screens: "No admin prototype"
related_docs: [providers.md, drivers.md, ../provider/profile-change-requests.md, ../delivery/profile-change-requests.md]
last_updated: 2026-11-10
---

# Review of provider and driver change requests — React integration guide (admin)

> **Base URL:** `{HOST}/api/v1/admin` · [Shared API conventions](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.0 | 2026-11-10 | Initial | List an account's change requests, approve one exactly as submitted, reject one with a reason (R01–R03, TD-184). Replaces the read-only metadata of TD-44. | Add a "change requests" tab to the provider and driver details with approve and reject. |

## 1. Business summary

A provider or driver asks to change approved data (work area, bank account, identity, documents, and for a driver the vehicle). The old data stays effective until an admin approves (BR-04). The admin **approves or rejects the request exactly as submitted**: there is no editing. Approval may carry a note; rejection needs a reason. Approval applies the new values in one transaction. If a saved value changed after the request was made, the approval is refused as stale and nothing is written: reject it with a note so she can send a new one.

## 2. Pages and permissions

| Route name | Section / action | What it does |
|------------|------------------|--------------|
| `admin.providers.change-requests.index` | `providers` / view | A provider's requests, newest first |
| `admin.providers.change-requests.approve` | `providers` / approve | Apply a pending request |
| `admin.providers.change-requests.reject` | `providers` / approve | Reject a pending request |
| `admin.drivers.change-requests.index` | `drivers` / view | A driver's requests |
| `admin.drivers.change-requests.approve` | `drivers` / approve | Apply a pending request |
| `admin.drivers.change-requests.reject` | `drivers` / approve | Reject a pending request |

A new request raises an alert (`admin_provider_change_requested`, `admin_driver_change_requested`) in the inbox of every active admin who holds the `approve` action of that section (BR-29). The alert's `data` carries `id` (the account uuid), `request_id` and `change_type`, and opens `providers/show` or `drivers/show`.

## 3. Endpoints

`{id}` is the provider's or driver's uuid; `{changeRequest}` is the request uuid. A request of another account is 404.

### `GET /providers/{id}/change-requests` · `GET /drivers/{id}/change-requests`

Query: `page`, `per_page` (1–100, default 15), `filters[status]` (`pending`, `approved`, `rejected`, `cancelled`), `filters[change_type]`. `data` is a Laravel page of the resource below.

### `POST /providers/{id}/change-requests/{changeRequest}/approve` · `POST /drivers/{id}/change-requests/{changeRequest}/approve`

Body: `note` (optional, max 500). Returns the approved request. A repeated approval returns it unchanged (200).

### `POST /providers/{id}/change-requests/{changeRequest}/reject` · `POST /drivers/{id}/change-requests/{changeRequest}/reject`

Body: `reason` (required, 3–500). Returns the rejected request. A repeated rejection returns it unchanged.

## 4. Request resource

Same resource the apps get ([provider guide §4](../provider/profile-change-requests.md)): `id`, `change_type {value,label}`, `status {value,label}`, `changes[] {field, label, current, proposed}`, `file` (document requests: `{url, mime_type}`), `decision_note`, `can_cancel`, `submitted_at`, `reviewed_at`. IBANs, document numbers, commercial register numbers and phones are **masked** here too; the full values are never returned.

## 5. Errors

| HTTP | `error_code` | When |
|------|--------------|------|
| 403 | — | The admin lacks the section's `approve` action |
| 404 | `ENTITY_NOT_FOUND` | Unknown account or request, or the request belongs to another account |
| 409 | `INVALID_STATE_TRANSITION` | Approve or reject a request that is already decided differently (approved vs rejected vs cancelled) |
| 409 | `CHANGE_REQUEST_STALE` | A saved value changed since the request; nothing was applied. Reject it with a note |
| 409 | `ACTIVE_TRIP_BLOCKS_VEHICLE_CHANGE` | A vehicle request while the driver has an accepted or live trip; approve after the trip ends |
| 422 | `VALIDATION_FAILED` | `reason` missing or short, `note` too long, bad filter |

## 6. Business rules

BR-04; approval applies exactly the submitted fields (no editing); the request row is locked before the account and its targets, so two admins deciding at once serialise and the second gets 409 (or the unchanged request for a repeat); the audit entry stores field names only, never an IBAN or a document number; the requester is notified (`profile_change_approved` / `profile_change_rejected`).

## 7. Integration checklist

- [ ] Show the pending count on the provider and driver details; list with `filters[status]=pending`.
- [ ] Show `current` beside `proposed`; for a document, the file link.
- [ ] Approve with an optional note; reject with a required reason.
- [ ] On 409 `CHANGE_REQUEST_STALE`, offer "Reject with a note".
- [ ] Hide the buttons from admins without the `approve` action.

## 8. Acceptance and open decisions

AC-ADMIN-004 / AC-ADMIN-006 (BR-04 change review). Tests: `tests/Feature/Api/V1/Shared/ProfileChangeRequestTest.php`. Postman: `admin.providers.change-requests.*`, `admin.drivers.change-requests.*`. Open: a review time target (none stated).
