# Entity: Org registration

Captures self-serve signup and assisted “request to register” flows before Admin activates commercial terms.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Sub-entities

| Entity | Purpose |
|--------|---------|
| `OrgRegistration` | Full self-register submission + first SUPER_USER |
| `OrgRegistrationRequest` | Lightweight lead capture (email or phone) |

## OrgRegistration

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | `string` | ✓ | `oreg_*` |
| `org_id` | `string` | ✓ | Created org in `pending_activation` |
| `submitted_at` | `Timestamp` | ✓ | |
| `company` | `RegistrationCompany` | ✓ | Mirrors org fields at submit |
| `super_user` | `RegistrationUser` | ✓ | First admin account |
| `status` | `RegistrationStatus` | ✓ | |
| `admin_notes` | `string` | | Admin-only (not in B2B API) |

### RegistrationCompany

| Field | Type |
|-------|------|
| `legal_name` | `string` |
| `tin` | `string` |
| `billing_contact` | `Contact` |
| `approx_headcount` | `integer` |

### RegistrationUser

| Field | Type |
|-------|------|
| `full_name` | `string` |
| `email` | `string` |
| `phone` | `Phone` |
| `password_hash` | `string` | Server-side only; never returned |

### RegistrationStatus

```
submitted | under_review | activated | rejected
```

## OrgRegistrationRequest

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | `string` | ✓ | `orreq_*` |
| `contact_name` | `string` | ✓ | |
| `company_name` | `string` | | Optional |
| `channel` | `RequestChannel` | ✓ | Preferred contact method |
| `email` | `string` | conditional | Required if `channel=email` |
| `phone` | `Phone` | conditional | Required if `channel=phone` |
| `message` | `string` | | Free text |
| `status` | `RequestStatus` | ✓ | |
| `created_at` | `Timestamp` | ✓ | |

### RequestChannel

```
email | phone
```

### RequestStatus

```
new | contacted | converted | closed
```

## Validation rules

| Rule | Error code |
|------|------------|
| Unique `tin` on self-register | `DUPLICATE_ORG` |
| Password min 8 chars, 1 upper, 1 digit | `WEAK_PASSWORD` |
| Email unique for super_user | `DUPLICATE_USER` |
| Request must have email OR phone per channel | `VALIDATION_FAILED` |

## Clinical withhold

No clinical data in registration entities.

## Sample: self-register submit

**Request:**

```json
{
  "company": {
    "legal_name": "Gamma Industries PLC",
    "tin": "0011223344",
    "billing_contact": {
      "name": "Hanna T.",
      "email": "hanna@gamma.et",
      "phone": "+251922334455"
    },
    "approx_headcount": 200
  },
  "super_user": {
    "full_name": "Hanna Tadesse",
    "email": "hanna@gamma.et",
    "phone": "+251922334455",
    "password": "SecurePass1"
  }
}
```

**Response (201):**

```json
{
  "registration_id": "oreg_01HABC",
  "org_id": "org_01HNEW",
  "status": "submitted",
  "org_status": "pending_activation",
  "session": {
    "user_id": "usr_01HNEW",
    "roles": ["SUPER_USER"],
    "org_id": "org_01HNEW"
  }
}
```

## Sample: request to register

```json
{
  "contact_name": "Daniel Kebede",
  "company_name": "Delta Embassy",
  "channel": "phone",
  "phone": "+251911998877",
  "message": "We need coverage for ~40 staff"
}
```

**Response (201):**

```json
{
  "request_id": "orreq_01HXYZ",
  "status": "new",
  "message": "A Gishen representative will contact you."
}
```

## Events

| Event | When |
|-------|------|
| `org.registration_submitted` | Self-register completes |
| `org.registration_requested` | Request form submitted |
| `org.activated` | Admin activates org (see Organisation) |

## Related endpoints

- [`../endpoints/org.md`](../endpoints/org.md) — registration routes