Gishen-B2B/docs/backend/endpoints/org.md

Endpoints: Organisation

Org profile, registration, departments, and verification settings.

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

Entities: organisation, org-registration, department

---

POST /v1/org/register

Self-register organisation + first SUPER_USER.

Auth	Public
Roles	—

Request

See sample in org-registration.md.

Response 201

{
  "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.

Event

org.registration_requested

---

GET /v1/org

Current organisation profile.

Auth	Required
Roles	SUPER_USER, HR_ADMIN, FINANCE

Response 200

Full Organisation. 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)

{
  "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

{
  "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

{
  "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 list.

---

POST /v1/org/departments

Create department.

Auth	Required
Roles	SUPER_USER, HR_ADMIN

Request

{
  "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.