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

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

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

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

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

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

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

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

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

Create Contractor

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

{
  "detail": "Client with name 'Airtel Kenya' already exists"
}

403 Forbidden

{
  "detail": "Only platform administrators can create clients"
}

404 Not Found

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