# Parental Consent Form — API Reference

**Feature:** PCF-001  
**Base URL:** `/registrations`  
**Auth:** Firebase bearer token required on all endpoints  
**Response envelope:** `{ success: boolean, message: string, data?: any }`

---

## 1. Seeker Upload

**`POST /registrations/:id/parental-consent/upload`**

Seeker confirms they have uploaded the signed form to S3 and submits the URL.

**Path param:** `id` — registration ID

**Body:**
```json
{
  "s3Url": "https://s3.amazonaws.com/bucket/signed-form.pdf"
}
```

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent form uploaded successfully. If you uploaded the wrong file, please contact your RM.",
  "data": {
    "message": "...",
    "uploadedAt": "2026-06-12T10:30:00.000Z",
    "uploadDeadline": "2026-06-30T18:29:59.000Z"
  }
}
```

**Errors:**
- `400` — consent not triggered yet (status is null / not applicable)
- `400` — form already verified (cannot re-upload)
- `400` — upload deadline has passed
- `400` — registration does not belong to authenticated user
- `404` — registration not found

---

## 2. Admin — Send Consent Email

**`POST /registrations/:id/parental-consent/send`**

Admin manually triggers the parental consent email to the seeker. Generates a new pre-filled PDF and sends it. Can be called any number of times — no restriction on resend.

**Roles:** `admin`, `relational_manager`, `rm`, `operational_manger`

**Path param:** `id` — registration ID

**Body:**

```json
{
  "reason": "Seeker's DOB was corrected"
}
```

> `reason` is optional — stored as admin notes on the registration.

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent email sent successfully"
}
```

**Errors:**
- `400` — parental consent not enabled or form content missing on programme
- `400` — seeker age not in consent range
- `400` — payment not completed
- `404` — registration not found

---

## 3. Admin — Upload on Behalf of Seeker

**`POST /registrations/:id/parental-consent/admin-upload`**

Admin uploads a signed form on the seeker's behalf. Sets status directly to `VERIFIED`.

**Roles:** `admin`, `relational_manager`, `rm`, `operational_manger`

**Path param:** `id` — registration ID

**Body:**
```json
{
  "s3Url": "https://s3.amazonaws.com/bucket/signed-form.pdf",
  "sourceNote": "Received via email"
}
```
> `sourceNote` is optional.

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent form uploaded and verified successfully"
}
```

**Errors:**
- `404` — registration not found

---

## 4. Admin — Verify Seeker Upload

**`PATCH /registrations/:id/parental-consent/verify`**

Admin approves a form that the seeker uploaded. Only works when status is `SUBMITTED`.

**Roles:** `admin`, `relational_manager`, `rm`, `operational_manger`

**Path param:** `id` — registration ID

**Body:** none

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent form verified successfully"
}
```

**Errors:**
- `400` — form status is not `SUBMITTED`
- `404` — registration not found

---

## 5. Admin — Delete Consent Record

**`DELETE /registrations/:id/parental-consent`**

Clears the uploaded form and resets status to `PENDING_UPLOAD`. No S3 deletion — only DB fields are cleared.

**Roles:** `admin`, `relational_manager`, `operational_manger`

**Path param:** `id` — registration ID

**Body:** none

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent record deleted successfully"
}
```

**Errors:**
- `404` — registration not found

---

## 6. Admin — List Consent Records

**`GET /registrations/parental-consent`**

Paginated list of all registrations that have a parental consent status. For `relational_manager` / `rm` roles, automatically scoped to their assigned registrations only.

**Roles:** `admin`, `relational_manager`, `rm`, `finance_manager`, `operational_manger`, `viewer`

**Query params:**

| Param | Type | Required | Description |
|---|---|---|---|
| `status` | string | no | Filter by status: `pending_upload`, `submitted`, `verified`, `not_applicable` |
| `dateFrom` | string (ISO) | no | Filter by trigger date from |
| `dateTo` | string (ISO) | no | Filter by trigger date to |
| `minAge` | number | no | Minimum seeker age |
| `maxAge` | number | no | Maximum seeker age |
| `limit` | number | no | Records per page (default: 20) |
| `offset` | number | no | Records to skip (default: 0) |
| `rmId` | number | no | Filter by RM — ignored for `relational_manager`/`rm` roles (auto-scoped to self) |

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent list fetched successfully",
  "data": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "data": [
      {
        "registrationId": 1234,
        "seekerName": "Arjun Sharma",
        "age": 17,
        "consentStatus": "submitted",
        "dateTriggered": "2026-06-10T08:00:00.000Z",
        "dateLastUploaded": "2026-06-11T14:22:00.000Z",
        "uploadedBy": 56,
        "programName": "TAT June 2026"
      }
    ]
  }
}
```

> `uploadedBy` is the user ID of the uploader — `null` if not yet uploaded, seeker's user ID if seeker uploaded, admin's user ID if admin uploaded.

---

## 7. Admin — Consent Record Detail

**`GET /registrations/parental-consent/:registrationId`**

Full detail for a single consent record including the direct S3 URL of the uploaded form.

**Roles:** `admin`, `relational_manager`, `rm`, `finance_manager`, `operational_manger`, `viewer`

**Path param:** `registrationId` — registration ID

**Success `200`:**
```json
{
  "success": true,
  "message": "Parental consent detail fetched successfully",
  "data": {
    "registrationId": 1234,
    "seekerName": "Arjun Sharma",
    "age": 17,
    "consentStatus": "submitted",
    "dateTriggered": "2026-06-10T08:00:00.000Z",
    "dateLastUploaded": "2026-06-11T14:22:00.000Z",
    "uploadedBy": 56,
    "uploadDeadline": "2026-06-30T18:29:59.000Z",
    "formUrl": "https://s3.amazonaws.com/bucket/signed-form.pdf",
    "programName": "TAT June 2026"
  }
}
```

> `formUrl` — direct S3 URL of the uploaded form. `null` if no form uploaded yet.  
> `uploadDeadline` — `null` if no deadline configured on the programme.  
> `uploadedBy` — `null` if not uploaded, seeker user ID or admin user ID.

**Errors:**
- `404` — registration not found

---

## Status Enum Reference

| Value | Meaning |
|---|---|
| `pending_upload` | Email sent, waiting for seeker to upload the signed form |
| `submitted` | Seeker has uploaded the signed form, pending admin verification |
| `verified` | Admin has verified and approved the form |
| `not_applicable` | Seeker's age is outside the consent range |