Skip to content

API and Integration View

This document describes the API surface and external integration points for the Employment Services SaaS domain. It is written for architects and engineers designing APIs and integrations.

The Employment Services SaaS exposes REST APIs for external clients and integrates with ConnectSoft platforms and external systems. This document defines the API structure and integration patterns.

Note

All APIs follow RESTful principles and support multi-tenancy. Authentication is handled via Identity Platform, and all operations are scoped to tenants.

External APIs and Clients

Web Portal

Client Type: Single-page application (SPA)

APIs Used: - All REST APIs for CRUD operations - Real-time updates via SignalR/WebSockets (optional) - File upload/download for documents

Authentication: - OAuth2/OIDC via Identity Platform - User tokens for API calls - Tenant context from token claims

Customer Backoffice

Client Type: Internal admin portal

APIs Used: - Admin APIs for tenant management - Reporting APIs for analytics - Configuration APIs for settings

Authentication: - OAuth2/OIDC via Identity Platform - Admin role required - Cross-tenant access (with proper authorization)

Integrations

Client Types: - CRM systems (Salesforce, HubSpot) - ATS systems (for hiring) - Payment processors (Stripe, PayPal) - Accounting systems (QuickBooks, Xero)

APIs Used: - Webhook endpoints for external events - REST APIs for data synchronization - Event bus for real-time updates

See: External SaaS Integration Patterns for integration patterns.

Internal Service APIs

Tenant Management API

Base Path: /api/v1/tenants

Resources: - GET /tenants - List tenants (admin only) - GET /tenants/{id} - Get tenant details - POST /tenants - Create tenant - PUT /tenants/{id} - Update tenant - GET /tenants/{id}/subscription - Get subscription - PUT /tenants/{id}/subscription - Update subscription - GET /tenants/{id}/settings - Get tenant settings - PUT /tenants/{id}/settings - Update tenant settings

Customer Accounts API

Base Path: /api/v1/customers

Resources: - GET /customers - List customers (tenant-scoped) - GET /customers/{id} - Get customer details - POST /customers - Create customer - PUT /customers/{id} - Update customer - GET /customers/{id}/contacts - List contacts - POST /customers/{id}/contacts - Add contact

Project & Engagement API

Base Path: /api/v1/engagements

Resources: - GET /engagements - List engagements (tenant-scoped) - GET /engagements/{id} - Get engagement details - POST /engagements - Create engagement - PUT /engagements/{id} - Update engagement - POST /engagements/{id}/activate - Activate engagement - POST /engagements/{id}/complete - Complete engagement - GET /engagements/{id}/milestones - List milestones - POST /engagements/{id}/milestones - Create milestone

Squad & Staffing API

Base Path: /api/v1/squads

Resources: - GET /squads - List available squads - GET /squads/{id} - Get squad details - GET /squads/{id}/capacity - Get squad capacity - POST /squads/{id}/assign - Assign squad to engagement - GET /assignments - List assignments - GET /assignments/{id} - Get assignment details

Work Management API

Base Path: /api/v1/work

Resources: - GET /epics - List epics (engagement-scoped) - POST /epics - Create epic - GET /epics/{id}/stories - List user stories - POST /epics/{id}/stories - Create user story - GET /stories/{id}/tasks - List tasks - POST /stories/{id}/tasks - Create task - GET /sprints - List sprints - POST /sprints - Create sprint

Billing & Invoicing API

Base Path: /api/v1/billing

Resources: - GET /invoices - List invoices (tenant-scoped) - GET /invoices/{id} - Get invoice details - POST /invoices - Create invoice - GET /invoices/{id}/download - Download invoice PDF - POST /invoices/{id}/issue - Issue invoice - GET /payments - List payments - POST /payments - Record payment

Authentication and Authorization

Authentication

Identity Platform Integration: - All APIs require OAuth2/OIDC authentication - Tokens issued by Identity Platform - Token validation via Identity Platform introspection

See: Identity Platform API Overview for authentication details.

Authorization

Multi-Tenant + Roles: - Tenant Isolation - All operations scoped to tenant from token - Role-Based Access - Roles: Customer Admin, Project Manager, Squad Lead, Member, Finance - Resource-Level Authorization - Additional checks for resource ownership

Role Permissions:

Role Permissions
Customer Admin Full access to customer resources, billing, settings
Project Manager Create/manage projects, engagements, work items
Squad Lead View assigned engagements, update work progress
Member View assigned work, update tasks
Finance View invoices, process payments, billing reports

See: Security & Compliance for security requirements.

Integration with ConnectSoft Platforms

Identity Platform

Integration: - User authentication and authorization - Tenant context from token claims - Role-based access control - External IdP federation (if needed)

API Usage: - Token validation and introspection - User info retrieval - Role and permission checks

See: Identity Platform API Overview for API details.

Audit Platform

Integration: - Audit event emission for all critical actions - Event types: EngagementCreated, InvoiceIssued, PaymentReceived, etc. - Query audit events for reporting and compliance

API Usage: - Write audit events via API - Query audit events for dashboards - Webhook notifications for critical events

See: Audit Platform API Overview for API details.

Config Platform

Integration: - Tenant-level configuration and settings - Feature flags for gradual rollouts - Pricing plan configuration - Edition-based feature management

API Usage: - Retrieve tenant configuration - Update feature flags - Webhook notifications for config changes

See: Config Platform API Overview for API details.

Bot Platform (Optional)

Integration: - Customer support bot - Squad assistance bot - Project management bot

API Usage: - Bot API for conversational interfaces - Webhook endpoints for bot events - Integration with microservices via APIs

See: Bot Platform API Overview for API details.

Example API Scenarios

Scenario 1: Create Engagement via API

Request: 

POST /api/v1/engagements
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerId": "customer-123",
  "projectId": "project-456",
  "squadId": "squad-789",
  "contractTerms": {
    "scope": "Build MVP for customer portal",
    "pricing": {
      "model": "fixed-price",
      "amount": 50000.00,
      "currency": "USD"
    },
    "timeline": {
      "startDate": "2025-02-01",
      "endDate": "2025-04-30"
    }
  }
}

Response: 

{
  "engagementId": "engagement-abc",
  "status": "Draft",
  "createdAt": "2026-01-01T10:30:00Z"
}

Events Emitted: - EngagementCreated - Consumed by Squad & Staffing, Billing, Work Management

Scenario 2: Fetch List of Invoices per Tenant

Request: 

GET /api/v1/billing/invoices?tenantId={tenantId}&status=Issued
Authorization: Bearer {token}

Response: 

{
  "invoices": [
    {
      "invoiceId": "invoice-001",
      "customerId": "customer-123",
      "engagementId": "engagement-abc",
      "totalAmount": {
        "amount": 50000.00,
        "currency": "USD"
      },
      "status": "Issued",
      "issueDate": "2026-01-01",
      "dueDate": "2025-02-15"
    }
  ],
  "totalCount": 1
}

Scenario 3: Update Work Progress

Request: 

PUT /api/v1/work/tasks/{taskId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "Completed",
  "completedAt": "2026-01-01T14:30:00Z"
}

Events Emitted: - TaskCompleted - Consumed by Work Management, Billing - MilestoneCompleted (if all tasks done) - Consumed by Billing, Reporting