---
feature: Provider onboarding and account review status
slug: onboarding
surface: provider
consumer: flutter
version: 1.0.4
status: ready
brd_version: "1.3"
brd_ids: [PROV-002, PROV-003, PROV-004]
business_rules: [BR-01, BR-03, BR-04, BR-05, BR-06, BR-08]
decisions: [D4, DEC-18, DEC-25, TD-01, TD-09, TD-14, TD-19, TD-35, TD-43, TD-44, TD-45, TD-46, TD-50, TD-51, TD-56, TD-57, TD-58, TD-59, TD-60, TD-61, TD-62, TD-63, TD-64, TD-67, TD-71]
schema_tables: [providers, provider_categories, user_documents, account_review_events, platform_settings, media, users, categories, category_translations, provider_districts, provider_working_hours, payout_accounts, provider_services, services]
screens: ["provider--registration--0[3-5]-*"]
related_docs: [services-pricing.md, profile.md, auth.md, ../admin/providers.md, ../admin/services.md, ../delivery/onboarding.md]
last_updated: 2026-11-08
---

# Provider onboarding — Flutter Integration Guide (provider)

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

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.0.4 | 2026-11-08 | PATCH | BR-03 boundary row reworded: operational routes now exist behind the `approved` group. | None. |
| 1.0.3 | 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.2 | 2026-10-22 | PATCH | BR-06 checklist uses shared complete active base/choice pricing rule (TD-71); extra requested categories remain visible. | None; an active base alone no longer clears services when choices lack prices. |
| 1.0.1 | 2026-10-22 | PATCH | Shared provider/driver Domain onboarding extraction (TD-67); existing provider contract preserved. | None. |
| 1.0.0 | 2026-10-22 | Initial | SCR-18 step-2 drafts, category chips, submission, status, resubmission and atomic registration-category approval. | Integrate the four routes below after OTP registration; use returned flags and missing lists. |

## Changelog

### 1.0.4 — 2026-11-08

- **Changed:** BR-03 boundary row reworded: operational routes now exist behind the `approved` group.
- **Breaking:** No. **App action required:** None.

### 1.0.3 — 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.2 — 2026-10-22

- **Fixed:** missing_for_bookability.services uses the same Domain predicate as provider pricing enable/toggle: active base and active provider prices for every active choice in active groups, including free zero; account/category gates remain separate (BR-06/TD-42/71).
- **Added:** links to the scoped profile/portfolio and services-pricing contracts. Extra post-approval category requests show their requested status in existing categories output.
- **Changed / Removed / Deprecated:** N/A.
- **Breaking:** No; stable keys and enums preserved.
- **Endpoints affected:** GET/PUT onboarding, POST onboarding/submit derived checklist only.
- **App action required:** None; retain services completion guidance until prices are complete.
- **BRD / decisions:** PROV-009/010, TD-64/70/71.

### 1.0.1 — 2026-10-22

- **Added:** shared Domain onboarding edit/completeness/upload rules, submit/document replacement actions and timeline, reused by delivery.
- **Changed:** provider service delegates to shared actions (TD-67), preserving its API, required fields, settings, errors and review behavior.
- **Fixed:** N/A.
- **Removed / Deprecated:** N/A.
- **Breaking:** No.
- **Endpoints affected:** existing provider onboarding routes; no contract change.
- **App action required:** None.
- **BRD / decisions:** PROV-002/003/004, TD-67; [driver guide](../delivery/onboarding.md).

### 1.0.0 — 2026-10-22

- **Added:** four authenticated provider routes; partial drafts, masked saved fields, document replacement history, submission/bookability checklists, three-step review timeline and edit/submit flags.
- **Changed:** initial admin approval also approves requested registration categories in its existing transaction (TD-60; [admin contract](../admin/providers.md)).
- **Fixed:** submission and admin approval now use one required-document and qualification policy (TD-59).
- **Removed / Deprecated:** N/A.
- **Breaking:** N/A; first onboarding release.
- **Endpoints affected:** `GET /categories`, `GET /onboarding`, `PUT /onboarding`, `POST /onboarding/submit`.
- **App action required:** load the saved draft after OTP, save changed fields, upload documents, submit separately, and refresh status. Never send masked values back as real numbers.
- **BRD / decisions:** PROV-002/003/004, SCR-18, D4; TD-58–64. DEC-18 remains declaration-only; DEC-25/BR-04 govern later approved-profile changes.

## 1. Business summary

After OTP registration the provider is `incomplete`. She completes the individual or establishment step-2 form, chooses at least one active main category and attaches the SCR-18 documents, then submits for review. Submission changes the account to `pending_review`; account approval and category review happen through the admin workflow. City, coverage, photo, portfolio, working hours and payout details are completion guidance in `missing_for_bookability`, rather than blockers for sending registration to review.

D4 keeps an establishment as one provider account; `specialists_count` does not create staff accounts. This API cannot edit an approved or suspended provider.

## 2. User flow and screens

Only these five prototype screens were opened for this feature.

| Step | Screen | Endpoint | States and actions |
|------|--------|----------|--------------------|
| 1 | `provider--registration--03-individual-id-crafts-p1.png` | `GET /onboarding`, `GET /categories`, `PUT /onboarding` | Individual ID, years, employer/experience note and category chips. Preserve omitted fields while paging. |
| 2 | `provider--registration--03-individual-docs-p2.png` | Shared `POST /api/v1/media`, `PUT /onboarding`, `POST /onboarding/submit` | Upload ID, professional certificate/licence and health certificate; submit only when `can_submit`. |
| 3 | `provider--registration--04-establishment-cr-vat-p1.png` | `GET /onboarding`, `GET /categories`, `PUT /onboarding` | CR, optional VAT, authorized person name/phone, years active and specialist count. |
| 4 | `provider--registration--04-establishment-docs-p2.png` | Shared upload, `PUT /onboarding`, `POST /onboarding/submit` | CR file, business licence, staff health certificates. |
| 5 | `provider--registration--05-under-review.png` | `GET /onboarding`, existing `GET /auth/me` | Received → verifying documents → activated. Use backend flags for edit/resubmit. The prototype's simulation button has no production endpoint. |

1. OTP registration/verification uses [auth.md](auth.md); it already persists provider type, display name and consents.
2. Fetch onboarding and category chips. Show the appropriate step-2 form from `provider_type.value`.
3. Upload each file through shared media with multipart `file` and `collection=file`; use the returned `data.hash` in `documents[].file`.
4. Save changed fields with PUT, then POST submit with no body. Saving a complete draft alone never submits it.
5. Refresh GET onboarding after submission and admin review. `auth/me.profile.account_status` remains available for app routing. There is no polling interval or simulated review duration in this contract.

## 3. Endpoints

All four routes require `Authorization: Bearer {provider_token}`, `auth:api`, `app:provider`, and `active`. They are in the authenticated account group outside `approved`. No admin RBAC grant or `Idempotency-Key` is required. Use `Accept-Language: ar` or `en`; no endpoint-specific throttle is added.

GET onboarding and the two mutation responses use `Cache-Control: no-store, private`.

### 3.1 Active category chips

`GET /api/v1/provider/categories` — route `provider.categories.index`.

No path/query/body parameters. Returns an unpaginated array of active categories ordered by catalog `sort_order`, then internal tie-breaker; IDs are public UUIDs. Names use the requested locale with Arabic fallback. Images use the existing Media URL/placeholder behavior. Empty catalog returns `data: []`.

**Success — 200 (captured from MySQL HTTP test):**

```json
{
  "status": "success",
  "message": "",
  "data": [
    {
      "id": "01a162c5-c165-71b2-b3fe-c3f16b7f9cab",
      "name": "مكياج",
      "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200"
    }
  ]
}
```

Errors: 401 `UNAUTHENTICATED`; 403 `PERMISSION_DENIED` for another app claim or missing provider profile; 403 `ACCOUNT_INACTIVE` for a banned/disabled account. Handle these as in §3.5.

### 3.2 Saved onboarding and review status

`GET /api/v1/provider/onboarding` — route `provider.onboarding.show`.

No path/query/body parameters. Always returns the same documented keys, including nullable fields for the other provider type. The result belongs to the authenticated provider; no target user/profile UUID is accepted.

**Success — 200, individual under review:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-bbe1-7334-a29d-2c724b0a0215",
    "account_status": {
      "value": "pending_review",
      "label": "Pending review"
    },
    "status_reason": null,
    "submitted_at": "2026-10-22T08:41:28+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"
      }
    ],
    "provider_type": {
      "value": "individual",
      "label": "Individual"
    },
    "display_name": "Ms. Maximillia Ebert Sr.",
    "national_id": "****1234",
    "commercial_register_no": null,
    "vat_number": null,
    "authorized_person_name": null,
    "authorized_person_phone": null,
    "years_experience": 4,
    "experience_note": "Four years at a beauty centre",
    "specialists_count": null,
    "categories": [
      {
        "id": "01a162c5-bbf0-70ba-b4f8-1d3cc344c725",
        "name": "Sample-wbrw85028032",
        "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
        "is_active": true,
        "status": {
          "value": "requested",
          "label": "Requested"
        }
      }
    ],
    "documents": [
      {
        "id": "01a162c5-bc52-73ff-99a3-d8204f5cf3fe",
        "doc_type": {
          "value": "national_id",
          "label": "National ID / iqama"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/9f062104-fc0d-4a74-a490-dbb051772a8d.pdf"
      },
      {
        "id": "01a162c5-bc79-70c1-bc2b-32018ce83189",
        "doc_type": {
          "value": "professional_certificate",
          "label": "Professional certificate"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/2d688bd9-3686-448c-84e4-2e2db65149eb.pdf"
      },
      {
        "id": "01a162c5-bc94-72b9-945b-de0989bc96c7",
        "doc_type": {
          "value": "health_certificate",
          "label": "Health certificate"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/b89996be-3a2a-411d-ad8c-1a5f2665771d.pdf"
      }
    ],
    "missing_for_submission": [],
    "missing_for_bookability": [
      "city",
      "coverage",
      "photo",
      "portfolio",
      "working_hours",
      "payout_account",
      "account_status",
      "categories",
      "services"
    ],
    "can_edit": false,
    "can_submit": false
  }
}
```

The establishment projection has the same keys: `provider_type.value=establishment`, masked `commercial_register_no`/`vat_number`, authorized person name/phone, years and specialist count. See the [captured establishment response](../postman-collection.json) (Postman: `provider.onboarding.show` › "200 Establishment under review").

| Response field | Type / nullable | Meaning |
|----------------|-----------------|---------|
| `id` | UUID string | Provider profile UUID, not user UUID. |
| `account_status`, `provider_type` | `{value,label}` | Schema machine value and localized label. |
| `status_reason` | string / null | Latest review outcome reason; cleared by submit. |
| `submitted_at` | ISO 8601 / null | Latest successful submission time. |
| `timeline` | exactly three `{key,label,state}` rows | See §4. No fabricated dates or percentage. |
| `display_name` | string | Step-1 name; read-only here. |
| `national_id`, `commercial_register_no`, `vat_number` | string / null | Fixed redaction `****` plus last four; shorter values return only `****`. |
| `authorized_person_name`, `authorized_person_phone`, `experience_note` | string / null | Saved step-2 values. |
| `years_experience`, `specialists_count` | integer / null | Saved years/count. Zero is a stored value, not missing. |
| `categories` | `{id,name,image,is_active,status}[]` | Category UUID (not selection-row UUID), name/image, activity, selection status `{value,label}`. Inactive saved selections remain visible. |
| `documents` | `{id,doc_type,doc_number,expires_at,status,file_url}[]` | Only provider-role documents; includes historical replaced rows, ordered oldest first. Public document UUIDs, masked numbers, expiry date-only/null, localized enums, file URL/null. |
| `missing_for_submission` | string[] | Stable missing-field keys, `categories`, or `documents.<doc_type>`. Invalid document status, absent file or past expiry all leave that type missing. |
| `missing_for_bookability` | string[] | Completion guidance from actual saved records, described below; separate from submission. |
| `can_edit`, `can_submit` | bool | Enforced backend actions; submit also requires all prerequisites. |

`missing_for_bookability` can contain `city`, `coverage`, `photo`, `portfolio`, `working_hours`, `payout_account`, `account_status`, `categories`, `services` (TD-64). A saved district or base coordinates plus positive radius satisfies coverage completion. Photo is the user's `image` media, portfolio belongs to the provider, hours require saved rows, payout requires a primary non-inactive provider account. The remaining keys require approval, an approved/enabled/active category and active type-1 pricing within an approved category. This is a completion checklist; final enabled-area, availability, option pricing and address-based eligibility remain with their owning features. An empty list is not a checkout authorization.

Errors: same authentication/access errors as §3.1. A review status never turns this read endpoint into a 409.

### 3.3 Save a partial draft

`PUT /api/v1/provider/onboarding` — route `provider.onboarding.update`.

JSON body; all top-level fields are optional. Omission preserves a value, explicit null clears a nullable scalar. `categories: []` clears selected categories; an omitted categories key preserves them. An empty/omitted documents list preserves documents. Unknown top-level keys are ignored and cannot change account status, approver or step-1 identity.

| Field | Type | Validation / meaning |
|-------|------|----------------------|
| `national_id` | string / null | Individual ID/iqama; max 20. Required on individual submit. |
| `commercial_register_no` | string / null | Max 20. Required on establishment submit; cannot clear to null once establishment status is no longer incomplete (schema constraint). |
| `vat_number` | string / null | Max 20, optional on submit. |
| `authorized_person_name` | string / null | Max 150; required on establishment submit. |
| `authorized_person_phone` | string / null | Max 20; required on establishment submit. |
| `years_experience` | integer / null | 0–32767 (schema SMALLINT capacity); required on submit for both types. |
| `experience_note` | string / null | Max 255; required on individual submit. |
| `specialists_count` | integer / null | 0–32767; required on establishment submit; informational, D4. |
| `categories` | list of distinct UUIDs | Must reference existing active `categories`; entire selection is replaced. Selected rows become requested, enabled, with prior reviewer metadata cleared. Empty is allowed in a draft. |
| `documents` | list of objects | One entry per doc type and file hash; only the four nested keys below are allowed. |
| `documents[].doc_type` | required string | One of the six provider document schema types; must belong to this provider type's shared required-document policy. |
| `documents[].file` | required string | Fresh unattached hash from shared upload; uploader ID/type must match this user. Image or PDF, up to 5 MiB, physical storage file present. No integer media IDs, raw URLs or paths. |
| `documents[].doc_number` | string / null | Optional, max 50; returned masked. |
| `documents[].expires_at` | date / null | Optional `YYYY-MM-DD`; null permitted. Past dates save as draft but block submission. |

**Individual submit requirements:** `national_id`, `years_experience`, `experience_note`, active category and files of types `national_id`, `professional_certificate`, `health_certificate`.

**Establishment submit requirements:** `commercial_register_no`, `authorized_person_name`, `authorized_person_phone`, `years_experience`, `specialists_count`, active category and files of types `commercial_register`, `business_license`, `staff_health_certificates`. VAT remains optional.

Each new upload replaces all current same-role/same-type rows by marking them `replaced`, then creating a fresh `pending` row and attaching the new media. Old numbers, review metadata and files remain on historical rows. Other document types/roles are untouched. Previously attached hashes cannot be reused as replacements; upload a fresh file. To preserve a saved sensitive number, omit it—never echo `****1234` back into the draft.

**Success — 200, partial draft (same complete response shape as GET):**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-c24e-7244-bb01-c454a1f404cf",
    "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"
      }
    ],
    "provider_type": {
      "value": "individual",
      "label": "Individual"
    },
    "display_name": "Cordia Hoppe",
    "national_id": "****1234",
    "commercial_register_no": null,
    "vat_number": null,
    "authorized_person_name": null,
    "authorized_person_phone": null,
    "years_experience": 0,
    "experience_note": "First employer",
    "specialists_count": null,
    "categories": [],
    "documents": [],
    "missing_for_submission": [
      "categories",
      "documents.national_id",
      "documents.professional_certificate",
      "documents.health_certificate"
    ],
    "missing_for_bookability": [
      "city",
      "coverage",
      "photo",
      "portfolio",
      "working_hours",
      "payout_account",
      "account_status",
      "categories",
      "services"
    ],
    "can_edit": true,
    "can_submit": false
  }
}
```

Errors: 422 shape validation (§3.5); 422 `BUSINESS_RULE_VIOLATED` for inactive categories, a wrong-type document, foreign/not-fresh/unsupported/oversized upload, or clearing a submitted establishment's CR; 409 `INVALID_STATE_TRANSITION` for a valid-shaped edit in a locked state; authentication/access errors as above. No draft writes survive a failed transaction.

### 3.4 Submit for admin review

`POST /api/v1/provider/onboarding/submit` — route `provider.onboarding.submit`.

No body/path/query parameters. First save the intended draft. The RuleChain checks editable state, every required scalar, at least one active enabled selected category, and the shared qualifying document policy. Files must be attached, pending or verified, with no expiry or expiry on/after today's UTC date. Rejected, expired, replaced, missing-file and wrong-role rows never qualify. Approval uses the same required types and qualification query (TD-46/50/59).

On success, one transaction sets `pending_review`, refreshes `submitted_at`, clears `status_reason` and inserts a submitted account review event with provider actor and explicit from/to statuses. It does not approve the account or verify documents. The existing `admin_id` users FK stores the provider actor on submitted events (TD-61); other actions keep their admin actor.

**Success — 200:**

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a162c5-bbe1-7334-a29d-2c724b0a0215",
    "account_status": {
      "value": "pending_review",
      "label": "Pending review"
    },
    "status_reason": null,
    "submitted_at": "2026-10-22T08:41:28+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"
      }
    ],
    "provider_type": {
      "value": "individual",
      "label": "Individual"
    },
    "display_name": "Ms. Maximillia Ebert Sr.",
    "national_id": "****1234",
    "commercial_register_no": null,
    "vat_number": null,
    "authorized_person_name": null,
    "authorized_person_phone": null,
    "years_experience": 4,
    "experience_note": "Four years at a beauty centre",
    "specialists_count": null,
    "categories": [
      {
        "id": "01a162c5-bbf0-70ba-b4f8-1d3cc344c725",
        "name": "Sample-wbrw85028032",
        "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
        "is_active": true,
        "status": {
          "value": "requested",
          "label": "Requested"
        }
      }
    ],
    "documents": [
      {
        "id": "01a162c5-bc52-73ff-99a3-d8204f5cf3fe",
        "doc_type": {
          "value": "national_id",
          "label": "National ID / iqama"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/9f062104-fc0d-4a74-a490-dbb051772a8d.pdf"
      },
      {
        "id": "01a162c5-bc79-70c1-bc2b-32018ce83189",
        "doc_type": {
          "value": "professional_certificate",
          "label": "Professional certificate"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/2d688bd9-3686-448c-84e4-2e2db65149eb.pdf"
      },
      {
        "id": "01a162c5-bc94-72b9-945b-de0989bc96c7",
        "doc_type": {
          "value": "health_certificate",
          "label": "Health certificate"
        },
        "doc_number": "****1234",
        "expires_at": null,
        "status": {
          "value": "pending",
          "label": "Pending"
        },
        "file_url": "/storage/onboarding/b89996be-3a2a-411d-ad8c-1a5f2665771d.pdf"
      }
    ],
    "missing_for_submission": [],
    "missing_for_bookability": [
      "city",
      "coverage",
      "photo",
      "portfolio",
      "working_hours",
      "payout_account",
      "account_status",
      "categories",
      "services"
    ],
    "can_edit": false,
    "can_submit": false
  }
}
```

Errors: 422 `BUSINESS_RULE_VIOLATED` names all missing items in the localized message, including stable keys even in production; 409 `INVALID_STATE_TRANSITION` for a second submit or other locked state; authentication/access errors. Failed submission writes no status, timestamp or review event. Retrying after a successful submit returns 409 rather than creating another event.

### 3.5 Errors and app behavior

| HTTP | `data.error_code` | When | App action |
|------|-------------------|------|------------|
| 401 | `UNAUTHENTICATED` | Missing/expired token | Use provider auth/refresh. |
| 403 | `PERMISSION_DENIED` | Customer/driver/admin token or missing matching profile | Authenticate in provider app. |
| 403 | `ACCOUNT_INACTIVE` | Disabled/banned user | Show access outcome/support flow. Non-approved operational routes also return this code and `data.account_status`. |
| 422 | absent (`data.errors`) | Invalid body shape, category UUID, duplicate type/hash or attached/missing media | Mark fields from `data.errors`; fall back to `message` (TD-02). |
| 422 | `BUSINESS_RULE_VIOLATED` | Submit requirements missing or draft domain references invalid | Show message; refresh GET to obtain actionable missing keys. |
| 409 | `INVALID_STATE_TRANSITION` | pending_review/approved/suspended; rejected with setting disabled | Refetch status and honor flags; do not retry the mutation automatically. |

A real missing-document response:

```json
{
  "status": "fail",
  "message": "Submission requires: Health certificate (documents.health_certificate).",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "context": {
      "violations": [
        "Submission requires: Health certificate (documents.health_certificate)."
      ]
    },
    "correlation_id": "5db398b0-88b3-430b-8118-951e1238fd2d"
  }
}
```

A real state-conflict 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": "8bf545fc-80c0-4ba8-9514-d6729dd3fb07"
  }
}
```

A real validation response:

```json
{
  "status": "fail",
  "message": "The years experience field must be between 0 and 32767. (and 2 more errors)",
  "data": {
    "errors": {
      "years_experience": [
        "The years experience field must be between 0 and 32767."
      ],
      "documents.0": [
        "The documents.0 field must be an array."
      ],
      "documents.0.file": [
        "The documents.0.file field is required."
      ]
    }
  }
}
```

The remaining captured success/error variants are generated into [the Postman collection](../postman-collection.json); surface-wide 401/403 examples are reused by TD-56. `postman:generate --check` covers all four routes without adding baseline gaps.

## 4. Statuses and enums

| `account_status.value` | Meaning | `can_edit` | `can_submit` |
|------------------------|---------|------------|--------------|
| `incomplete` | Draft not sent | true | true when complete |
| `pending_review` | Received and under review | false | false |
| `needs_changes` | Admin requested corrections | true | true when complete |
| `rejected` | Rejected, reason in `status_reason` | setting-dependent | setting-dependent and complete |
| `approved` | Account approved; other eligibility still applies | false | false |
| `suspended` | Operations suspended | false | false |

`provider_resubmission_after_rejection` is a JSON boolean in `platform_settings`. Missing key defaults to true. Explicit false disables rejected edits and submission; needs_changes remains editable regardless. There is no new settings-admin endpoint in this feature.

Provider type values: `individual`, `establishment`. Category status values: `requested`, `approved`, `rejected`. Document type values for this flow: `national_id`, `professional_certificate`, `health_certificate`, `commercial_register`, `business_license`, `staff_health_certificates`. Document status values: `pending`, `verified`, `rejected`, `expired`, `replaced`. Each is serialized as `{value,label}`.

Timeline keys are `received`, `verifying_documents`, `activated`; `state` is `completed`, `current`, or `waiting`. Received completes when a submission timestamp exists. Verification is current during pending_review and completes when all shared required document types have qualifying verified files. Activation completes only for approved; rejected/needs_changes/suspended do not claim activation. No duration/ETA is inferred.

## Data model

| Table | Read / write | Notes |
|-------|--------------|-------|
| `providers` | read + write | Step-2 fields and atomic submission; existing schema unchanged. |
| `provider_categories` | read + write | Uses providers.user_id FK; selection UUIDs stay internal to this response. Initial admin approve reviews requested rows. |
| `user_documents` | read + write | Own provider-role rows only; replacement is a new row, not an in-place file overwrite. |
| `account_review_events` | write | Submitted action, actor, from/to statuses; other review actions reuse existing service. |
| `platform_settings` | read | Resubmission JSON boolean; absent=true. |
| `media` | read + attach | HasMedia files with uploader metadata; no new URL columns. |
| `categories`, translations | read | Active chips and localized saved-category display. |
| `users`, `provider_districts`, `provider_working_hours`, `payout_accounts`, `provider_services`, `services` | read | Existing values feed completion guidance; this API cannot edit them. |

No migrations, columns, staff accounts or approval backfills are added.

## 5. Dart models

Use the shared `EnumValue` and ISO date helpers from API_CONVENTIONS. All lists are present even when empty; all nullable keys remain present.

```dart
class OnboardingStatus {
  final String id;
  final Map<String, dynamic> accountStatus;
  final Map<String, dynamic> providerType;
  final String? statusReason;
  final DateTime? submittedAt;
  final bool canEdit;
  final bool canSubmit;
  final List<String> missingForSubmission;
  final List<String> missingForBookability;
  final List<Map<String, dynamic>> timeline;
  final List<Map<String, dynamic>> categories;
  final List<Map<String, dynamic>> documents;
  final Map<String, dynamic> savedFields;

  OnboardingStatus.fromJson(Map<String, dynamic> j)
      : id = j['id'] as String,
        accountStatus = Map<String, dynamic>.from(j['account_status']),
        providerType = Map<String, dynamic>.from(j['provider_type']),
        statusReason = j['status_reason'] as String?,
        submittedAt = j['submitted_at'] == null ? null : DateTime.parse(j['submitted_at']),
        canEdit = j['can_edit'] as bool,
        canSubmit = j['can_submit'] as bool,
        missingForSubmission = List<String>.from(j['missing_for_submission']),
        missingForBookability = List<String>.from(j['missing_for_bookability']),
        timeline = List<Map<String, dynamic>>.from(j['timeline']),
        categories = List<Map<String, dynamic>>.from(j['categories']),
        documents = List<Map<String, dynamic>>.from(j['documents']),
        savedFields = Map<String, dynamic>.from(j);
}
```

Keep changed draft inputs separately from the masked saved projection. Display `documents` grouped by `doc_type.value`, with historical replaced rows distinguished from current pending/verified rows. Do not use the last document in the full list as the selected file for every type.

## 6. Business rules enforced by the backend

| Rule | Backend behavior | App behavior |
|------|------------------|--------------|
| BR-01 / DEC-18 | OTP registration already captures declaration/terms/privacy | Do not duplicate or bypass registration consent. |
| BR-03 | App JWT and profile isolation; operational middleware requires approved | Route non-approved accounts to onboarding/status; use `auth/me` status. |
| BR-04 / TD-62 | Approved/suspended onboarding mutation denied | Important approved-profile changes belong to reviewed change requests, outside this feature. |
| BR-05/06 / PROV-003 | Active categories selected at registration; admin approve promotes requested rows atomically | Use chips; refetch after review. Account approval alone does not price services. |
| BR-08 / SCR-18 / TD-58 | Remaining completion items do not block registration submission | Show separate bookability completion guidance. |
| TD-46/50/59 | One required-document list and qualifying query for submit/approval | Replace rejected/expired files with fresh uploads. |
| TD-61 | needs_changes always resubmits; rejected depends on setting | Follow `can_edit` and `can_submit`, show reason. |
| D4 | Specialist count only | Never offer staff-account creation here. |

## 7. Notifications and real-time events

Submission emits the persisted `submitted` review event; this feature adds no external message, push or admin broadcast. Existing admin review writes an in-app provider notice atomically with account/documents/categories/event/audit.

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

Read the shared inbox with the provider token. External delivery remains ADMIN-020. No realtime subscription is added.

## 8. Localization and UI notes

- `label` fields and errors are localized by `Accept-Language`; branch on machine `value`, timeline key/state and missing keys.
- The client localizes missing-key labels; the server supplies both localized missing-item text and stable keys in submit errors.
- Support Arabic RTL and English, including mixed-direction phone/ID fragments; masks are display-only.
- Dates with time are ISO 8601 with offset; document expiry stays calendar-only `YYYY-MM-DD`. Expiry today remains valid in UTC.
- Save success does not navigate to under-review automatically. Navigate after POST submit succeeds; on 409 reload current status.

## 9. Integration checklist

- [ ] Authenticate through provider OTP and preserve `account_status` routing from `auth/me`.
- [ ] Load saved onboarding plus active category chips; handle empty/loading/error states.
- [ ] Maintain changed-field inputs separately from returned masked identifiers.
- [ ] Upload fresh files to shared media; send hashes, not URLs or integer IDs.
- [ ] Save drafts before submit; require backend `can_submit` for the submit control.
- [ ] Handle 401/403/422/409 as in §3.5; refetch after mutation/review.
- [ ] Show rejection/change reason, timeline and both distinct missing lists.
- [ ] Disable edits for pending_review/approved/suspended and rejected when disabled by settings.
- [ ] Render historical replaced documents without confusing them with the current file.
- [ ] Route review inbox notices back to the status screen; verify Arabic and English.

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-PROV-002 | Individual and establishment submit complete SCR-18 drafts | pending_review, submitted timestamp, provider-actor event; bookability-only items remain separate. |
| AC-PROV-002 | Each required scalar missing; missing/expired/rejected/replaced/wrong-role/missing-file document | 422 BUSINESS_RULE_VIOLATED naming omissions, no submission writes. |
| AC-PROV-002 | Fresh same-type upload | Old row replaced, new pending row, old file/reviewer metadata preserved. |
| AC-PROV-002 | Foreign/attached/duplicate/wrong-type upload or invalid shape/UUID | 422; no file stealing or partial writes. |
| AC-PROV-003 | Zero or inactive category; category selection replacement | Submit denied until active selection; omitted selection preserved, empty clears draft. |
| AC-PROV-003 | Admin initial approve and late inbox failure | Requested categories approved with reviewer/time; failure rolls back category/document/profile/event/audit/inbox writes. Reactivate preserves metadata. |
| AC-PROV-004 | Double submit or edit pending/approved/suspended | 409, one submission event only. |
| AC-PROV-004 | needs_changes and rejected with setting absent/on/off | needs_changes always allowed; rejection defaults on, explicit off denies edit/submit. |
| AC-PROV-004 | Customer/driver token, including same-user profiles | 403 on all four routes; guests 401. |
| AC-PROV-004 | Before/after approval | Non-approved operational probe denied; after approval probe allowed and `auth/me` updated. |
| AC-PROV-002/004 | Late draft/history failure | Transaction rolls back all draft/submission writes. |

Evidence: `tests/Feature/Api/V1/Provider/OnboardingTest.php` and `tests/Feature/Api/V1/Admin/ProviderManagementTest.php`, running against MySQL `joshen_testing`; real captured responses in `docs/postman-collection.json` (saved responses of `provider.*`). The end-to-end test exercises OTP registration, shared file upload, draft, submission, admin approval, category approval and updated auth/status. Operational routes are not yet implemented, so that boundary uses the actual middleware chain on a test-only route. Local tests do not constitute deployed/mobile acceptance.

## 11. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| DEC-18 | Female-user eligibility verification | Declaration-only assumption inherited from OTP registration; no extra verification. |
| DEC-25 / TD-44 / BR-04 | Approved-profile/document/bank changes | Deferred reviewed change-request contract; onboarding refuses approved/suspended edits. |
| TD-58 / SCR-18 / BR-08 | Bookability completion is broader than registration submission | City/coverage/photo/portfolio/hours/payout are outside this edit API; completed checklist does not certify checkout eligibility. |
| TD-61 | Rejected resubmission policy | JSON boolean setting, absent defaults true; no new settings CRUD here. |
| TD-14 / TD-63 | File delivery and temporary upload ownership | Existing Media storage/URL behavior is reused; upload owner metadata is required. Private/signed delivery is not introduced by this flow. |
| BR-03 | Operational routes (orders, services-pricing, availability, packages, earnings) sit behind the `approved` group | Boundary verified with the real middleware; at the time of the first version those routes did not exist yet, they now do. See [orders](orders.md), [services-pricing](services-pricing.md) and [availability](availability.md). Non-approved accounts still reach only auth, profile, onboarding and review status. |
| ADMIN-020 | External review notifications | Existing transactional in-app notice only; push/SMS/email remain their owning feature. |

Pricing completion is owned by [services-pricing.md](services-pricing.md): an active base alone is insufficient when active choices in active groups have missing/inactive provider prices, including free choices. Portfolio completion uses live media from [profile.md](profile.md); post-approval requested categories remain visible here with status requested.
