# Endpoints: Organisation

Org profile, registration, departments, and verification settings.

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

**Entities:** [`organisation`](../entities/organisation.md), [`org-registration`](../entities/org-registration.md), [`department`](../entities/department.md)

---

## POST /v1/org/register

Self-register organisation + first SUPER_USER.

| | |
|---|---|
| **Auth** | Public |
| **Roles** | — |

### Request

See sample in [`org-registration.md`](../entities/org-registration.md).

### Response 201

```json
{
  "data": {
    "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" }
  }
}
```

### Validation / errors

| Code | HTTP | When |
|------|------|------|
| `DUPLICATE_ORG` | 409 | TIN exists |
| `DUPLICATE_USER` | 409 | Email taken |
| `WEAK_PASSWORD` | 400 | Password policy |
| `VALIDATION_FAILED` | 400 | Field errors |

### Event

`org.registration_submitted`

### Clinical withhold

N/A.

---

## POST /v1/org/register/request

Request-to-register (email or phone lead).

| | |
|---|---|
| **Auth** | Public |

### Request / Response

See [`org-registration.md`](../entities/org-registration.md).

### Event

`org.registration_requested`

---

## GET /v1/org

Current organisation profile.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE |

### Response 200

Full [`Organisation`](../entities/organisation.md). `commercial` null if pending.

### Errors

| Code | HTTP | When |
|------|------|------|
| `FORBIDDEN` | 403 | MEMBER role |
| `UNAUTHENTICATED` | 401 | |

### Clinical withhold

No clinical fields.

---

## PATCH /v1/org

Update HR-managed org fields (not commercial).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Request (partial)

```json
{
  "display_name": "Acme Bank",
  "dependant_limit": 4,
  "join_rules": {
    "join_code": "ACME-2026",
    "allowed_email_domains": ["acme.et"]
  }
}
```

### Response 200

Updated organisation.

### Errors

| Code | HTTP | When |
|------|------|------|
| `ORG_PENDING` | 422 | Some actions blocked — read still allowed |
| `FORBIDDEN` | 403 | Attempt to mutate `commercial` |

---

## GET /v1/org/registration-status

Pending org activation status for SUPER_USER.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER |

### Response 200

```json
{
  "data": {
    "org_status": "pending_activation",
    "submitted_at": "2026-03-01T09:00:00Z",
    "message": "Gishen is reviewing your application. You will be notified when activated."
  }
}
```

---

## PATCH /v1/org/verification

Verification method settings.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Request

```json
{
  "method": "employee_id",
  "require_at_checkout": true
}
```

### Response 200

Updated `verification` object.

### Errors

| Code | HTTP | When |
|------|------|------|
| `ORG_PENDING` | 422 | Org not active |

---

## GET /v1/org/departments

List departments.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE (read) |

### Query

`?page=1&page_size=25&q=addis&parent_id=dept_root`

### Response 200

Paginated [`Department`](../entities/department.md) list.

---

## POST /v1/org/departments

Create department.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Request

```json
{
  "name": "Hawassa Branch",
  "code": "HAW",
  "parent_id": null,
  "sub_limit": { "amount": "100000.00", "currency": "ETB" }
}
```

### Response 201

Created department.

### Errors

| Code | HTTP |
|------|------|
| `DUPLICATE_DEPARTMENT` | 409 |
| `ORG_PENDING` | 422 |
| `VALIDATION_FAILED` | 400 |

---

## GET /v1/org/departments/:id

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE |

---

## PATCH /v1/org/departments/:id

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

---

## DELETE /v1/org/departments/:id

Soft-deactivate (`is_active: false`).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Errors

| Code | HTTP |
|------|------|
| `DEPARTMENT_IN_USE` | 422 |

---

## UI routes

| Route | Endpoint(s) |
|-------|-------------|
| `/organisation` | GET/PATCH `/v1/org` + spend charts |
| `/departments` | Department list |
| `/departments/new` | POST `/v1/org/departments` |
| `/departments/[id]` | GET/PATCH department detail |
| `/settings/verification` | PATCH `/v1/org/verification` |
| `/register/organisation` | POST `/v1/org/register` |
| `/register/request` | POST `/v1/org/register/request` |

## Clinical withhold

Organisation and department endpoints expose no clinical data.