Project Management REST API & Git CI/CD Automation Guide

1. Executive Overview & Architecture

Quantivo ProspectIQ CRM provides a comprehensive RESTful API framework designed to manage the full lifecycle of software engineering and operational projects. Through the API, external developer platforms, CI/CD pipelines (GitHub Actions, GitLab CI, Bitbucket Pipelines), and microservices can programmatically interact with projects, tasks, milestones, timesheets, and checklists.

Key Integration Capabilities

• Projects Lifecycle: Provisioning, status management, client allocation, budget tracking, and member assignment.
• Task Management: Hierarchical work breakdown structure (WBS), priorities, milestones, deadlines, and dynamic task status updates.
• Task Checklists: Granular acceptance criteria verification and definition-of-done (DoD) tracking.
• Timesheets & Resource Tracking: Granular labor logging, start/stop timer integrations, and developer effort auditing.
• Git CI/CD Automation: Automated commit-to-task correlation, PR status synchronization, and build/deploy event logging.

2. Authentication & Authorization

All API endpoints require authentication using the API key header:

authtoken: YOUR_API_TOKEN_HERE
Content-Type: application/json

• Base URL: https://crm.quantivolabs.co.ke/api/
• Token Generation: Navigate to Setup > Integrations > API / Users in the ProspectIQ CRM console to generate API keys with appropriate project and task privileges.
• Access Control: API tokens enforce staff role permissions. Ensure the service token possesses VIEW, CREATE, EDIT, and LOG_TIME permissions for Projects and Tasks.

3. Core Project Management API Specifications

3.1 Projects API

List Projects

Endpoint: GET /api/projects

Query Parameters:

• status: Filter by project status ID (e.g. 1=Not Started, 2=In Progress, 3=On Hold, 4=Finished, 5=Cancelled)
• clientid: Filter by client ID
• limit: Number of records (default 50)

curl -X GET "https://crm.quantivolabs.co.ke/api/projects?status=2" \
  -H "authtoken: {{authtoken}}"

Get Project Details

Endpoint: GET /api/projects/:id

Create Project

Endpoint: POST /api/projects

Payload:

{
  "name": "SuperApp Settlement Microservice Migration",
  "clientid": "1",
  "billing_type": "1",
  "start_date": "2026-09-15",
  "deadline": "2026-11-30",
  "description": "Migration of settlement reconciliation engine to distributed event architecture.",
  "progress_from_tasks": "1",
  "project_members": [1, 7, 8]
}

3.2 Tasks API

List Tasks

Endpoint: GET /api/tasks

Query Parameters: rel_type=project, rel_id=PROJECT_ID, status=STATUS_ID

Create Task

Endpoint: POST /api/tasks

Payload:

{
  "name": "Implement Idempotency Keys in Settlement Gateway",
  "priority": "3",
  "startdate": "2026-09-12",
  "duedate": "2026-09-18",
  "rel_type": "project",
  "rel_id": "1",
  "milestone": "2",
  "description": "Ensure payment webhooks cannot trigger duplicate ledger postings.",
  "assignees": [1, 8],
  "billable": "1"
}

Update Task Status

Endpoint: POST /api/tasks/status/:id or PUT /api/tasks/:id

Status Mapping: 1 = Not Started | 4 = In Progress | 3 = Testing / QA | 2 = Awaiting Feedback | 5 = Complete

{
  "status": "5"
}

3.3 Task Checklists & Milestones API

Add Checklist Item to Task

Endpoint: POST /api/tasks/:id/checklist_items

{
  "description": "Unit tests pass with >90% coverage",
  "finished": 0
}

Complete Checklist Item

Endpoint: PUT /api/tasks/checklist_items/:item_id

{
  "finished": 1
}

Create Milestone

Endpoint: POST /api/projects/:id/milestones

{
  "name": "Sprint 1: Settlement Engine Kernel",
  "due_date": "2026-09-30",
  "description": "Core messaging and event distribution verification."
}

3.4 Timesheets & Work Logging API

Log Time Entry

Endpoint: POST /api/timesheets

{
  "task_id": "45",
  "staff_id": "1",
  "start_time": "2026-09-11 14:00:00",
  "end_time": "2026-09-11 16:30:00",
  "note": "Refactored payment event listener and added retry handling in settlement service."
}

Fetch Project Timesheets

Endpoint: GET /api/timesheets?project_id=1

4. Git CI/CD Automated Activity & Task Tracking

Automate project tracking across GitHub, GitLab, and Bitbucket using standardized commit formatting and CI pipelines.

4.1 Commit Message Grammar

feat(settlement): add idempotent transaction lock [TASK-45] #time 1h 30m

- Resolves race condition during concurrent settlement calls
- Closes checklist: 'Concurrency stress testing'
Refs: #45

• Task Key: [TASK-<id>], TASK-<id>, or #<id>
• Status Triggers: Fixes #<id>, Closes #<id>, Resolves [TASK-<id>] triggers status transition to Testing (3) or Complete (5).
• Time Logging: #time 1h 30m automatically parses effort and submits timesheets against the task.

4.2 GitHub Actions Workflow Sample

Add .github/workflows/prospectiq-task-sync.yml to your application repositories:

name: ProspectIQ Task & Activity Sync

on:
  push:
    branches: [ "main", "develop" ]
  pull_request:
    types: [ opened, closed, synchronize ]

jobs:
  sync-task:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 5

      - name: Sync Git Activity to ProspectIQ CRM
        env:
          PROSPECTIQ_API_URL: "https://crm.quantivolabs.co.ke/api"
          PROSPECTIQ_API_TOKEN: ${{ secrets.PROSPECTIQ_API_TOKEN }}
          COMMIT_MSG: ${{ github.event.head_commit.message }}
          AUTHOR_EMAIL: ${{ github.event.head_commit.author.email }}
        run: |
          TASK_ID=$(echo "$COMMIT_MSG" | grep -oE '(TASK-[0-9]+|#[0-9]+)' | head -n1 | tr -dc '0-9')
          if [ -z "$TASK_ID" ]; then
            echo "No CRM task ID found in commit."
            exit 0
          fi

          echo "Found ProspectIQ Task ID: $TASK_ID"

          # 1. Post Git activity comment to task
          COMMENT_BODY="Git Push on ${GITHUB_REPOSITORY} (${GITHUB_REF_NAME}):\nCommit: ${GITHUB_SHA::7} by ${AUTHOR_EMAIL}\nMessage: ${COMMIT_MSG}"
          curl -s -X POST "${PROSPECTIQ_API_URL}/tasks/${TASK_ID}/comments" \
            -H "authtoken: ${PROSPECTIQ_API_TOKEN}" \
            -H "Content-Type: application/json" \
            -d "{\"content\": \"$COMMENT_BODY\"}"

          # 2. Check if closing keywords are present
          if echo "$COMMIT_MSG" | grep -iqE '(closes|fixes|resolves)'; then
            echo "Transitioning task to Testing/QA (Status 3)..."
            curl -s -X POST "${PROSPECTIQ_API_URL}/tasks/status/${TASK_ID}" \
              -H "authtoken: ${PROSPECTIQ_API_TOKEN}" \
              -H "Content-Type: application/json" \
              -d '{"status": "3"}'
          fi

          # 3. Check for time log
          TIME_LOG=$(echo "$COMMIT_MSG" | grep -oE '#time\s+[0-9]+(h|m)' | awk '{print $2}')
          if [ -n "$TIME_LOG" ]; then
            END_TIME=$(date -u +"%Y-%m-%d %H:%M:%S")
            START_TIME=$(date -u -d "1 hour ago" +"%Y-%m-%d %H:%M:%S")
            curl -s -X POST "${PROSPECTIQ_API_URL}/timesheets" \
              -H "authtoken: ${PROSPECTIQ_API_TOKEN}" \
              -H "Content-Type: application/json" \
              -d "{\"task_id\": \"$TASK_ID\", \"start_time\": \"$START_TIME\", \"end_time\": \"$END_TIME\", \"note\": \"Automated CI time log: $COMMIT_MSG\"}"
          fi

5. Postman Collection Integration

A ready-to-import Postman collection has been pre-configured with all endpoints, schema validation scripts, and automated environment variable capture.

• File Name: crm_project_management_postman_collection.json
• Server Path: /www/wwwroot/crm.quantivolabs.co.ke/prospectiq/crm_project_management_postman_collection.json
• Local Project Path: public_html/crm_project_management_postman_collection.json