docs/dev/orgs/ORGANIZATIONS_API_GUIDE.md

# Organizations API Guide

Foundation layer for managing Clients and Contractors.

## Overview

- **Clients**: Companies that hire contractors (e.g., Airtel Kenya, Safaricom)
- **Contractors**: Companies that execute field work (e.g., TechInstall Ltd)

## Authentication

All endpoints require authentication. Include the JWT token in the header:
```
Authorization: Bearer <your_token>
```

## Clients API

### 1. Create Client

**POST** `/api/v1/clients`

**Requires:** `platform_admin`, `client_admin`, or `contractor_admin` role

**Business Logic:** Self-service organization onboarding
- Platform admins can create any client
- Client admins can create clients (their own organization or partners)
- Contractor admins can create clients they work with

```json
{
  "name": "Airtel Kenya",
  "description": "Leading telecommunications provider",
  "industry": "Telecommunications",
  "main_email": "contact@airtel.co.ke",
  "main_phone": "+254700000000",
  "website": "https://airtel.co.ke",
  "default_sla_days": 3
}
```

**Response:**
```json
{
  "id": "uuid",
  "name": "Airtel Kenya",
  "description": "Leading telecommunications provider",
  "industry": "Telecommunications",
  "main_email": "contact@airtel.co.ke",
  "main_phone": "+254700000000",
  "website": "https://airtel.co.ke",
  "is_active": true,
  "default_sla_days": 3,
  "additional_metadata": {},
  "created_at": "2025-11-15T22:00:00Z",
  "updated_at": "2025-11-15T22:00:00Z"
}
```

### 2. List Clients

**GET** `/api/v1/clients?skip=0&limit=100&is_active=true`

**Query Parameters:**
- `skip`: Number of records to skip (default: 0)
- `limit`: Max records to return (default: 100, max: 100)
- `is_active`: Filter by active status (optional)

**Response:** Array of client objects

### 3. Get Client

**GET** `/api/v1/clients/{client_id}`

**Response:** Single client object

### 4. Update Client

**PUT** `/api/v1/clients/{client_id}`

**Requires:** `platform_admin` or `client_admin` (own organization only)

```json
{
  "description": "Updated description",
  "is_active": true,
  "default_sla_days": 5
}
```

### 5. Delete Client

**DELETE** `/api/v1/clients/{client_id}`

**Requires:** `platform_admin` role

Performs soft delete (sets `deleted_at` timestamp).

---

## Contractors API

### 1. Create Contractor

**POST** `/api/v1/contractors`

**Requires:** `platform_admin`, `client_admin`, or `contractor_admin` role

**Business Logic:** Self-service organization onboarding
- Platform admins can create any contractor
- Client admins can create contractors they want to hire
- Contractor admins can create contractors (their own organization or partners)

```json
{
  "name": "TechInstall Ltd",
  "description": "Professional field service provider",
  "website": "https://techinstall.co.ke",
  "main_email": "info@techinstall.co.ke",
  "main_phone": "+254711111111",
  "competencies": ["FTTH", "Fixed Wireless", "Fiber Splicing"]
}
```

**Response:**
```json
{
  "id": "uuid",
  "name": "TechInstall Ltd",
  "description": "Professional field service provider",
  "website": "https://techinstall.co.ke",
  "main_email": "info@techinstall.co.ke",
  "main_phone": "+254711111111",
  "is_active": true,
  "competencies": ["FTTH", "Fixed Wireless", "Fiber Splicing"],
  "onboarding_status": "started",
  "onboarding_completed_at": null,
  "additional_metadata": {},
  "created_at": "2025-11-15T22:00:00Z",
  "updated_at": "2025-11-15T22:00:00Z"
}
```

### 2. List Contractors

**GET** `/api/v1/contractors?skip=0&limit=100&is_active=true`

**Query Parameters:**
- `skip`: Number of records to skip (default: 0)
- `limit`: Max records to return (default: 100, max: 100)
- `is_active`: Filter by active status (optional)

**Response:** Array of contractor objects

### 3. Get Contractor

**GET** `/api/v1/contractors/{contractor_id}`

**Response:** Single contractor object

### 4. Update Contractor

**PUT** `/api/v1/contractors/{contractor_id}`

**Requires:** `platform_admin` or `contractor_admin` (own organization only)

```json
{
  "description": "Updated description",
  "is_active": true,
  "competencies": ["FTTH", "Fixed Wireless", "Fiber Splicing", "FTTB"],
  "onboarding_status": "completed"
}
```

**Note:** Setting `onboarding_status` to `"completed"` automatically sets `onboarding_completed_at` timestamp.

### 5. Delete Contractor

**DELETE** `/api/v1/contractors/{contractor_id}`

**Requires:** `platform_admin` role

Performs soft delete (sets `deleted_at` timestamp).

---

## Testing with cURL

### Create Client
```bash
curl -X POST https://your-space.hf.space/api/v1/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airtel Kenya",
    "industry": "Telecommunications",
    "main_email": "contact@airtel.co.ke",
    "default_sla_days": 3
  }'
```

### List Clients
```bash
curl -X GET "https://your-space.hf.space/api/v1/clients?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Create Contractor
```bash
curl -X POST https://your-space.hf.space/api/v1/contractors \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TechInstall Ltd",
    "main_email": "info@techinstall.co.ke",
    "competencies": ["FTTH", "Fixed Wireless"]
  }'
```

---

## Error Responses

### 400 Bad Request
```json
{
  "detail": "Client with name 'Airtel Kenya' already exists"
}
```

### 403 Forbidden
```json
{
  "detail": "Only platform administrators can create clients"
}
```

### 404 Not Found
```json
{
  "detail": "Client not found"
}
```

---

## Authorization Matrix

| Endpoint | platform_admin | client_admin | contractor_admin | Others |
|----------|---------------|--------------|------------------|--------|
| Create Client | ✅ | ❌ | ❌ | ❌ |
| List Clients | ✅ | ✅ | ✅ | ✅ |
| Get Client | ✅ | ✅ | ✅ | ✅ |
| Update Client | ✅ | ✅ (own) | ❌ | ❌ |
| Delete Client | ✅ | ❌ | ❌ | ❌ |
| Create Contractor | ✅ | ❌ | ❌ | ❌ |
| List Contractors | ✅ | ✅ | ✅ | ✅ |
| Get Contractor | ✅ | ✅ | ✅ | ✅ |
| Update Contractor | ✅ | ❌ | ✅ (own) | ❌ |
| Delete Contractor | ✅ | ❌ | ❌ | ❌ |

---

## Next Steps

1. Deploy updated code
2. Test client creation
3. Test contractor creation
4. Assign users to organizations
5. Build projects layer (clients + contractors → projects)