---
feature: Registration request review (accounts and extra-category requests)
slug: registration-review
surface: admin
consumer: react
version: 1.0.0
status: ready
brd_version: "1.3"
brd_ids: [ADMIN-007, PROV-009]
business_rules: [BR-01, BR-03, BR-04, BR-29]
decisions: [D4, TD-02, TD-19, TD-35, TD-50, TD-51, TD-60, TD-70, TD-85, TD-86]
schema_tables: [providers, drivers, users, user_documents, payout_accounts, vehicles, account_review_events, provider_categories]
related_docs: [providers.md, drivers.md, ../provider/services-pricing.md, ../provider/onboarding.md, ../delivery/onboarding.md, ../API_CONVENTIONS.md]
last_updated: 2026-10-25
---

# Registration request review — React Dashboard Integration Guide

> **Base URL:** `{HOST}/api/v1/admin` · Shared rules (headers, envelope, errors,
> pagination, axios setup, TS types): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Version history

Newest first. Never edit an old row.

| Version | Date | Type | Summary | Dashboard action required |
|---------|------|------|---------|---------------------------|
| 1.0.0 | 2026-10-25 | Initial | One review queue for submitted provider and driver registrations, with the review payload and the approve / reject / request-changes decisions, plus the review of providers' requests to add a main category (AC-PROV-009), all under the `registration_review` permission section. | Add the Registration requests page; the provider and driver pages keep working unchanged. |

## Changelog

### 1.0.0 — 2026-10-25
- **Added:** `GET /category-requests`, `POST /category-requests/{id}/approve|reject` — admin approval for a provider's request to add a main category (PROV-009; the provider app already creates the requests). `GET /registration-requests`, `GET /registration-requests/{type}/{id}`, `POST /registration-requests/{type}/{id}/approve|reject|request-changes` (`type` = `provider` or `driver`). Section `registration_review` in the permission matrix.
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** —
- **Breaking:** No.
- **Endpoints affected:** the eight above (new). `/providers/*` and `/drivers/*` are unchanged.
- **Dashboard action required:** add the page; use `account_type` + `id` of a row to open and decide it.
- **BRD / decisions:** ADMIN-007, BR-01, BR-03, BR-04, TD-35, TD-85.

---

## 1. Business summary

Providers and drivers register in their apps, submit their data and documents,
and wait for Joshen's decision (BR-03: no operations before approval). This page
is the one queue the review team works from: every submitted account of both
types, newest submission first. Opening a request shows what the applicant sent —
information, documents, the services she picked (provider) or her vehicle
(driver), payout details, the terms / privacy acceptance and the female
declaration (BR-01) — and the admin approves, rejects, or sends it back for
corrections with a reason. The decision uses exactly the same transactional
review as the provider and driver pages (TD-85): documents are verified, the
account status, review event and audit entry are written together, and the
applicant gets an in-app notice. Suspending and reactivating approved accounts is
not part of this queue; that stays on the provider and driver pages.

## 2. Pages and permissions

| Page / component | Purpose | Endpoint(s) | RBAC permission (route name) |
|------------------|---------|-------------|------------------------------|
| RegistrationRequestsPage | Queue table with filters | `GET /registration-requests` | `admin.registration-requests.index` |
| RegistrationRequestDetailsPage | Review payload of one request | `GET /registration-requests/{type}/{id}` | `admin.registration-requests.show` |
| ApproveDialog | Approve | `POST /registration-requests/{type}/{id}/approve` | `admin.registration-requests.approve` |
| RejectDialog | Reject with a reason | `POST /registration-requests/{type}/{id}/reject` | `admin.registration-requests.reject` |
| RequestChangesDialog | Ask for corrections | `POST /registration-requests/{type}/{id}/request-changes` | `admin.registration-requests.request-changes` |
| CategoryRequestsPage | Providers' requests to add a main category | `GET /category-requests` | `admin.category-requests.index` |
| ApproveCategoryDialog / RejectCategoryDialog | Decide one category request | `POST /category-requests/{id}/approve`, `POST /category-requests/{id}/reject` | `admin.category-requests.approve`, `admin.category-requests.reject` |

Section `registration_review` (TD-27): `index`/`show` → view; `approve`, `reject`
and `request-changes` → approve (the same for `category-requests`). The section is separate from `providers` and
`drivers`: a supervisor with only `registration_review` can work the queue but
cannot open the provider or driver pages, and the other way round. Hide the
sidebar entry **Registration requests** without the index permission, and each
button without its route permission.

## 3. List / table

`GET /api/v1/admin/registration-requests` — list key in `data`: `registration_requests`

| Column | Field | Sortable (`sort[...]`) | Filter (`filters[...]`) | Notes |
|--------|-------|------------------------|-------------------------|-------|
| Type | `account_type.label` | no | `filters[account_type]=provider\|driver` | Badge by `account_type.value` |
| Name | `name` | no | — | Provider trading name or driver full name |
| Mobile | `phone_code` + `phone` | no | — | |
| City | `city.name` (nullable until she picks one) | no | `filters[city_id]=<city uuid>` | Localized |
| Submitted | `submitted_at` | `sort[submitted_at]` | `filters[submitted_from]`, `filters[submitted_to]` (`YYYY-MM-DD`) | ISO 8601 with offset; default order newest first |
| Status | `account_status.label` | no | `filters[account_status]` ∈ `pending_review`, `needs_changes`, `approved`, `rejected`, `suspended` | Send `pending_review` for the queue awaiting a decision |
| Created | `created_at` | `sort[created_at]` | — | |

`search` matches the name and the phone. Identity numbers are never searchable
(TD-54). `paginate=false` returns a plain array capped at 500 rows. Accounts that
never submitted (`incomplete`), administrators and deleted users are not listed.

Postman: `admin.registration-requests.index` › "200 Registration Requests Queue".

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "registration_requests": [
      {
        "id": "01a171e8-5034-71da-9641-3a215e0dc5e3",
        "account_type": { "value": "driver", "label": "Driver" },
        "name": "Edwina Gutkowski",
        "phone_code": "966",
        "phone": "517677356",
        "city": null,
        "account_status": { "value": "needs_changes", "label": "Changes required" },
        "submitted_at": "2026-10-25T07:13:32+00:00",
        "created_at": "2026-10-25T07:13:32+00:00"
      },
      {
        "id": "01a171e8-5023-7311-992f-268dc7f09b5d",
        "account_type": { "value": "provider", "label": "Service provider" },
        "name": "Noor Beauty",
        "phone_code": "966",
        "phone": "506161166",
        "city": { "id": "01a171e8-501a-73f0-865d-5be8ecedc2d5", "name": "Sample-wvld95997161" },
        "account_status": { "value": "pending_review", "label": "Pending review" },
        "submitted_at": "2026-10-24T07:13:32+00:00",
        "created_at": "2026-10-25T07:13:32+00:00"
      }
    ],
    "links": { "first": "…?page=1", "last": "…?page=1", "prev": null, "next": null },
    "meta": { "current_page": 1, "per_page": 15, "total": 2 }
  }
}
```

(`links` and `meta` trimmed to their first keys; the recorded example has the full standard pagination object.)

### 3.2 Category requests — `GET /api/v1/admin/category-requests` — list key `category_requests`

After approval a provider cannot add a main category on her own (AC-PROV-009): she sends a request from the provider app (`POST /provider/categories`, [services-pricing.md](../provider/services-pricing.md)) and it waits here. Registration categories are approved together with the account (TD-60) and are **not** listed; an account that is not approved has no requests here.

| Column | Field | Sortable | Filter | Notes |
|--------|-------|----------|--------|-------|
| Provider | `provider.display_name`, `provider.phone_code` + `provider.phone` | no | `filters[provider_id]=<provider uuid>` | |
| Category | `category.name` | no | `filters[category_id]=<category uuid>` | Localized |
| Status | `status.label` | no | `filters[status]` ∈ `requested`, `approved`, `rejected` | Send `requested` for the queue |
| Requested | `created_at` | `sort[created_at]` (default `asc`: oldest first) | — | ISO 8601 |
| Decided | `reviewed_at`, `reviewed_by.name` | `sort[reviewed_at]` | — | `null` until decided |

`search` matches the provider name and phone. `paginate=false` returns a plain array (cap 500).
Postman: `admin.category-requests.index` › "200 Category Requests Queue".

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "category_requests": [
      {
        "id": "01a171ec-b409-7260-bcd5-faba32a01534",
        "provider": { "id": "01a171ec-b3f8-7005-86f5-e1be4e682f1b", "display_name": "Noor Beauty", "phone_code": "966", "phone": "590978764" },
        "category": { "id": "01a171ec-b409-7260-bcd5-faba32fea7d7", "name": "Sample-wful39005919" },
        "status": { "value": "requested", "label": "Requested" },
        "is_enabled": true,
        "reviewed_by": null,
        "reviewed_at": null,
        "created_at": "2026-10-24T07:18:20+00:00"
      }
    ],
    "links": { "first": "…", "last": "…", "prev": null, "next": null },
    "meta": { "current_page": 1, "per_page": 15, "total": 2 }
  }
}
```

(One of the two recorded rows shown; `links`/`meta` shortened.)

## 4. Details view

`GET /api/v1/admin/registration-requests/{type}/{id}` — `type` is `provider` or
`driver`, `id` is the row's uuid. A uuid of the other type, an integer id or an
unknown `type` is 404.

The payload is **the same as the provider or driver details** — see
[providers.md §4](providers.md#4-details-view) and [drivers.md §4](drivers.md#4-details-view)
for every field. The parts a reviewer needs:

| Block | Provider keys | Driver keys |
|-------|---------------|-------------|
| Entered information | `display_name`, `provider_type`, `bio`, `years_experience`, `specialists_count`, `authorized_person`, `city`, `coverage`, `national_id` / `commercial_register_no` / `vat_number` (masked) | `full_name`, `nationality`, `birth_date`, `city`, `districts`, `national_id` (masked) |
| Uploaded documents | `documents[]` (type, status, expiry, masked number) | `documents[]` |
| What was selected | `main_services`, `priced_services`, `packages`, `portfolio` | `vehicle` (active), `vehicles[]` |
| Payout details | `payout_account` (IBAN masked) | `payout_account` |
| Acceptance | `consents.terms_accepted_at`, `privacy_accepted_at`, `female_declared_at` | same |
| Pending corrections | `change_requests` | `change_requests` |
| History | `review_history[]` | `review_history[]` |

Full identity and document numbers are not part of this payload; the audited
read stays on `GET /providers/{id}/identity` and `GET /drivers/{id}/identity`
(permission `approve` of that section).

Postman: `admin.registration-requests.show` › "200 Registration Request Provider Details" · "200 Registration Request Driver Details".

## 5. Forms (create / edit)

N/A — requests are created by applicants in their apps. The admin only decides.

## 6. Actions (non-CRUD)

All three: `POST /api/v1/admin/registration-requests/{type}/{id}/<action>`.

| Action | Route / permission | Body | Result status |
|--------|--------------------|------|---------------|
| Approve | `admin.registration-requests.approve` | none (`reason` is refused) | `approved` |
| Reject | `admin.registration-requests.reject` | `reason` required, string, max 500 | `rejected` |
| Request changes | `admin.registration-requests.request-changes` | `reason` required, string, max 500 | `needs_changes` |

Approval needs a submitted account with the required, non-expired documents
(provider: individual ID + professional + health certificates, establishment:
commercial register + licence + staff health certificates; driver: ID, driving
licence, vehicle registration, and an active vehicle) — TD-35/TD-50. Reject and
request-changes need a reason that the applicant sees as `status_reason`. A
reviewed provider's requested registration categories are promoted by the
approval (TD-60). Approval activates the account (BR-03).

Postman: `admin.registration-requests.approve` › "200 Registration Request Approved" ·
`…reject` › "200 Registration Request Rejected" · `…request-changes` › "200 Registration Request Changes Requested".

```json
{
  "status": "success",
  "message": "Data updated successfully",
  "data": {
    "id": "01a171e8-5517-7036-afbc-7e5f2015b90f",
    "account_status": { "value": "approved", "label": "Approved" },
    "status_reason": null,
    "approved_at": "2026-10-25T07:13:34+00:00"
  }
}
```

| HTTP | `error_code` | When | Dashboard behavior |
|------|--------------|------|--------------------|
| 401 | `UNAUTHENTICATED` | Missing or expired token | Refresh, then retry |
| 403 | `PERMISSION_DENIED` | Missing route permission | Hide/disable the action |
| 404 | — | Unknown, integer or wrong-type id; administrator or deleted account | Toast, reload the queue |
| 409 | `INVALID_STATE_TRANSITION` | The request is not in a reviewable status (e.g. rejecting an approved account) | Refetch and update the buttons |
| 422 | `BUSINESS_RULE_VIOLATED` | Approval prerequisites missing (documents, submission, vehicle) | Toast `message`; the rule list is in `data.context.violations` |
| 422 | — | Validation: `reason` missing or too long → `data.errors.reason` | Mark the field |

```json
{
  "status": "fail",
  "message": "Approval requires: National ID / iqama, Professional certificate, Health certificate.",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "context": { "violations": ["Approval requires: National ID / iqama, Professional certificate, Health certificate."] },
    "correlation_id": "c254651c-6dc1-43ac-9d71-43fe82f87946"
  }
}
```

```json
{
  "status": "fail",
  "message": "The reason field is required.",
  "data": { "errors": { "reason": ["The reason field is required."] } }
}
```

Postman: `admin.registration-requests.approve` › "422 Registration Request Approval Missing Documents" ·
`admin.registration-requests.reject` › "422 Registration Request Rejection Without Reason".

### 6.2 Decide a category request

`POST /api/v1/admin/category-requests/{id}/approve` · `POST /api/v1/admin/category-requests/{id}/reject` — `id` is the request's uuid (the `id` of the list row).

| Field | Type | Required | Validation | Description |
|-------|------|----------|-----------|-------------|
| `reason` | string | no (reject only) | max 500; **prohibited on approve** | Shown to the provider in her in-app notice; kept in the audit trail, not stored on the row (the schema has no reason column) |

Approval sets the request `approved` with reviewer and time; the provider can then select and price its services, and turn it on or off herself. Rejection is final — she cannot request the same category again (TD-70). Both write one in-app notice in the provider's language (event `provider_category_reviewed`, payload `category_request_id`, `category_id`, `status`, `reason`) in the same transaction.

Postman: `admin.category-requests.approve` › "200 Category Request Approved" · "409 Category Request Already Reviewed" · "422 Category Request Approve With A Reason"; `admin.category-requests.reject` › "200 Category Request Rejected" · "422 Category Request Reason Too Long".

```json
{
  "status": "success",
  "message": "Data updated successfully",
  "data": {
    "id": "01a171ec-b565-723e-bd83-60bbaf92c3dd",
    "provider": { "id": "01a171ec-b560-72b0-8399-2e52328c40d0", "display_name": "Georgianna Strosin", "phone_code": "966", "phone": "554294823" },
    "category": { "id": "01a171ec-b565-723e-bd83-60bbb02aa6de", "name": "Sample-rnfi93790547" },
    "status": { "value": "approved", "label": "Approved" },
    "is_enabled": true,
    "reviewed_by": { "id": "01a171ec-b55d-7140-a31d-9f3abbe07dfb", "name": "Alta Batz Jr." },
    "reviewed_at": "2026-10-25T07:18:20+00:00",
    "created_at": "2026-10-25T07:18:20+00:00"
  }
}
```

| HTTP | `error_code` | When | Dashboard behavior |
|------|--------------|------|--------------------|
| 403 | `PERMISSION_DENIED` | Missing route permission | Hide/disable the action |
| 404 | — | Unknown or integer id | Toast, reload the queue |
| 409 | `INVALID_STATE_TRANSITION` | Already decided, or the provider account is not approved | Refetch the queue |
| 422 | — | `reason` sent on approve, or longer than 500 → `data.errors.reason` | Mark the field |

```json
{
  "status": "fail",
  "message": "This category request was already reviewed, or the provider account is not approved.",
  "data": { "error_code": "INVALID_STATE_TRANSITION", "correlation_id": "85f3c8d2-0ff6-4065-8bfc-2f7cbb803dbf" }
}
```

## 7. Statuses and enums

| Enum | `value` | Label (en) | Badge color | Actions allowed here |
|------|---------|------------|-------------|----------------------|
| `account_type` | `provider`, `driver` | Service provider, Driver | blue, teal | — |
| `account_status` | `pending_review` | Pending review | amber | approve, reject, request changes |
| | `needs_changes` | Changes required | orange | none (waits for resubmission → `pending_review`) |
| | `rejected` | Rejected | red | none (applicant may resubmit) |
| | `approved` | Approved | green | none here; suspend on the provider/driver page |
| | `suspended` | Suspended | grey | none here; reactivate on the provider/driver page |
| `category_request.status` | `requested` | Requested | amber | approve, reject |
| | `approved` | Approved | green | none |
| | `rejected` | Rejected | red | none (final) |

`incomplete` accounts are not requests and never appear. Always branch on
`value`; `label` is localized.

## Data model

| Table (`db-schema.sql`) | Read / write | Notes |
|-------------------------|--------------|-------|
| `providers`, `drivers` | read; write `account_status`, `status_reason`, `approved_at`, `approved_by` | Through the shared review transaction |
| `users` | read | Name, phone; administrators and deleted users excluded |
| `user_documents` | read; write `status` on approval | Verified when approval passes |
| `payout_accounts`, `vehicles` | read | Masked IBAN, public plates |
| `account_review_events` | write | One row per decision, with the admin (`review_history`) |
| `notifications` | write | One in-app notice per decision |
| `provider_categories` | read; write `status`, `reviewed_by`, `reviewed_at` | Extra-category requests of approved providers |

## 8. TypeScript types

```ts
export type RegistrationAccountType = EnumValue<'provider' | 'driver'>;
export type RegistrationStatus = EnumValue<'pending_review' | 'needs_changes' | 'approved' | 'rejected' | 'suspended'>;

export interface RegistrationRequest {
  id: string; // profile uuid (TD-19); open with account_type
  account_type: RegistrationAccountType;
  name: string | null;
  phone_code: string; phone: string;
  city: { id: string; name: string | null } | null;
  account_status: RegistrationStatus;
  submitted_at: string | null; created_at: string; // ISO 8601 with offset
}

export type RegistrationRequestList = Paginated<'registration_requests', RegistrationRequest>;

export interface ReviewResult {
  id: string;
  account_status: RegistrationStatus;
  status_reason: string | null;
  approved_at: string | null;
}
// Details: ProviderDetails | DriverDetails (providers.md §8, drivers.md §8)

export interface CategoryRequest {
  id: string; // provider_categories uuid
  provider: { id: string; display_name: string | null; phone_code: string; phone: string };
  category: { id: string; name: string | null };
  status: EnumValue<'requested' | 'approved' | 'rejected'>;
  is_enabled: boolean; // the provider's own toggle
  reviewed_by?: { id: string; name: string | null } | null; // present on list/review responses
  reviewed_at: string | null; created_at: string; // ISO 8601 with offset
}
export type CategoryRequestList = Paginated<'category_requests', CategoryRequest>;
```

## 9. Business rules enforced by the backend

| Rule | What the backend does | What the admin sees |
|------|-----------------------|---------------------|
| BR-29 | `rbac.auto` on every route, section `registration_review` | 403 `PERMISSION_DENIED` |
| BR-03 | Only approval activates an account; other statuses see their review status only | Status badge |
| BR-01 | Consent timestamps (terms, privacy, female declaration) are part of the review payload | `consents` block |
| BR-04 | Post-approval edits are change requests, never `approved → needs_changes` | 409 `INVALID_STATE_TRANSITION` |
| TD-35 | Approval needs submission time and required non-expired documents | 422 `BUSINESS_RULE_VIOLATED` |
| TD-19 | Only uuids; integer ids and the wrong `type` are 404 | 404 |
| AC-PROV-009 | A new main category needs admin approval; only a pending request of an approved provider can be decided, once | 409 `INVALID_STATE_TRANSITION` |

## 10. Notifications triggered

| Event | Who is notified | Channel |
|-------|-----------------|---------|
| `account_review_status_changed` (approve, reject, request changes) | The applicant (provider or driver app inbox) | Shared in-app inbox, written in the review transaction; push/SMS pending ADMIN-020 |
| `provider_category_reviewed` (approve, reject a category request) | The provider (provider app inbox) | Same inbox and transaction; title/body in her language |

## 11. Integration checklist

- [ ] Queue defaults to `filters[account_status]=pending_review`; the status filter has the five values of §7
- [ ] Row click opens `GET /registration-requests/{account_type.value}/{id}`
- [ ] Decisions send `reason` for reject and request-changes only
- [ ] Buttons gated by their route permission; hide the page without `admin.registration-requests.index`
- [ ] Every error code of §6 handled, `data.errors.reason` marks the field
- [ ] Category requests page: default `filters[status]=requested`, oldest first; reason input only on reject
- [ ] Types match the real responses above
- [ ] RTL (`ar`) and `en` verified

## 12. Acceptance scenarios

| AC ID | Scenario | Expected / test |
|-------|----------|-----------------|
| AC-ADMIN-007 | Provider and driver requests appear together, newest first; drafts and admins are not listed | `test_ac_admin_007_queue_lists_submitted_providers_and_drivers_together` |
| AC-ADMIN-007 | Filter by type, city, status, dates; search; sort | `test_ac_admin_007_queue_filters_searches_and_sorts` |
| AC-ADMIN-007 | Review documents, consents and vehicle before deciding | `test_ac_admin_007_request_opens_with_documents_consents_and_vehicle` |
| AC-ADMIN-007 | Approve, reject or require correction; activate only on approval; notify the applicant | `test_ac_admin_007_admin_approves_rejects_or_asks_for_corrections` |
| AC-ADMIN-007 | Approval refused without documents; reason required; wrong status | `test_ac_admin_007_invalid_decisions_are_refused` |
| AC-PROV-009 | Admin approval adds a main category; rejection is final and carries an optional reason; registration categories and unapproved accounts are not in the queue | `CategoryRequestTest` (six tests) |
| AC-ADMIN-007 | Type must match the profile; permissions follow the section | `test_ac_admin_007_type_must_match_the_profile`, `test_ac_admin_007_uses_the_registration_review_permissions` |

## 13. Open decisions and known limitations

| ID | Impact on this feature | Current behavior |
|----|------------------------|------------------|
| TD-85 | ADMIN-007 is a queue and decision surface over the existing review | Accepted: no second review implementation; details and decisions delegate to the provider and driver services |
| DEC-25 | How documents are updated after approval | Not part of this queue; reviewed change requests stay deferred (TD-44) |
| TD-86 | Category-request decision has no stored reason | Accepted: the optional reason travels in the notice and audit trail; a reason column would need a schema change |
| ADMIN-020 | Push/SMS/email to the applicant | In-app notice only |
