Resourcing API

The Resourcing API provides endpoints for managing team capacity, allocations, and scheduling. All endpoints require the resourcing tool permission.

Base path

/api/resourcing

---

GET /api/resourcing/schedule

Returns combined timeline data for a date range, used to render the resourcing schedule view.

Permission: resourcing → can_view

Query parameters

Parameter	Type	Required	Description
from	YYYY-MM-DD	Yes	Start of the date range
to	YYYY-MM-DD	Yes	End of the date range
squad_id	string	No	Filter to a specific squad
user_id	string	No	Filter to a specific user
template_id	string	No	Filter to users on a specific template profile

Response

{
  "people": [
    {
      "id": "person-id",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "avatar_url": "https://...",
      "squad": "Engineering",
      "squad_id": "squad-id",
      "user_id": "user-id",
      "access_level": "employee",
      "job_title": "Software Engineer",
      "template_id": "template-id",
      "template_name": "Engineering",
      "weekly_capacity_hours": 40,
      "billable_target_percent": 80
    }
  ],
  "allocations": [
    {
      "id": "alloc-id",
      "user_id": "user-id",
      "booking_type": "project",
      "reference_id": "project-id",
      "from_date": "2026-03-01",
      "to_date": "2026-03-31",
      "hours_per_day": 6,
      "notes": null,
      "created_by": "user-id",
      "created_at": "2026-02-01T00:00:00.000Z",
      "updated_at": "2026-02-01T00:00:00.000Z",
      "deleted_at": null
    }
  ],
  "leave": [
    {
      "id": "leave-id",
      "person_id": "person-id",
      "user_id": "user-id",
      "first_name": "Jane",
      "last_name": "Smith",
      "leave_type_name": "Annual Leave",
      "start_date": "2026-03-10",
      "end_date": "2026-03-14",
      "total_hours": 40,
      "status": "approved"
    }
  ],
  "public_holidays": [
    {
      "id": "holiday-id",
      "date": "2026-03-09",
      "local_name": "Labour Day",
      "name": "Labour Day",
      "country_code": "AU",
      "year": 2026
    }
  ],
  "events": [
    {
      "id": "event-id",
      "title": "Team Offsite",
      "confirmed_date": "2026-03-20",
      "status": "confirmed"
    }
  ],
  "projects": [
    { "id": "proj-id", "name": "Acme Redesign", "status": "active" }
  ],
  "deals": [
    { "id": "deal-id", "title": "New Deal", "status": "open" }
  ],
  "jobs": [
    { "id": "job-id", "title": "Senior Engineer", "status": "published" }
  ]
}

---

POST /api/resourcing/allocations

Create a new allocation for a user.

Permission: resourcing → can_update

Request body

{
  "user_id": "user-id",
  "booking_type": "project",
  "reference_id": "project-id",
  "from_date": "2026-03-01",
  "to_date": "2026-03-31",
  "hours_per_day": 6,
  "notes": "Optional notes"
}

Field	Type	Required	Description
user_id	string	Yes	The user being allocated
booking_type	string	Yes	One of: project, deal, recruitment
reference_id	string	Yes	ID of the referenced project, deal, or job
from_date	YYYY-MM-DD	Yes	Start date of the allocation
to_date	YYYY-MM-DD	Yes	End date of the allocation
hours_per_day	number	Yes	Hours per working day (0–24)
notes	string	No	Optional notes

Response 201

{
  "allocation": {
    "id": "alloc-id",
    "user_id": "user-id",
    "booking_type": "project",
    "reference_id": "project-id",
    "from_date": "2026-03-01",
    "to_date": "2026-03-31",
    "hours_per_day": 6,
    "notes": null,
    "created_by": "user-id",
    "created_at": "2026-03-15T00:00:00.000Z",
    "updated_at": "2026-03-15T00:00:00.000Z",
    "deleted_at": null
  }
}

---

PATCH /api/resourcing/allocations/:id

Partially update an existing allocation. Only provided fields are updated.

Permission: resourcing → can_update

Request body (all fields optional)

{
  "from_date": "2026-03-05",
  "to_date": "2026-03-28",
  "hours_per_day": 8,
  "notes": "Updated notes",
  "booking_type": "deal",
  "reference_id": "deal-id"
}

Response 200

{
  "allocation": { "...updated allocation object..." }
}

Errors

Status	Description
404	Allocation not found or already deleted
400	Invalid booking_type or hours_per_day

---

DELETE /api/resourcing/allocations/:id

Soft-delete an allocation (sets deleted_at). The record is retained but excluded from all active queries.

Permission: resourcing → can_manage

Response 200

{ "ok": true }

Errors

Status	Description
404	Allocation not found or already deleted

---

GET /api/resourcing/capacity

Returns per-person capacity utilisation for a date range. Working days are calculated as Monday–Friday, minus public holidays, minus approved leave.

Permission: resourcing → can_view

Query parameters

Parameter	Type	Required	Description
from	YYYY-MM-DD	Yes	Start of the date range
to	YYYY-MM-DD	Yes	End of the date range
squad_id	string	No	Filter to a specific squad
user_id	string	No	Filter to a specific user

Response

{
  "capacity": [
    {
      "user_id": "user-id",
      "person_id": "person-id",
      "first_name": "Jane",
      "last_name": "Smith",
      "target_hours": 152,
      "allocated_hours": 120,
      "remaining_hours": 32,
      "utilisation_pct": 79,
      "over_allocated": false
    }
  ]
}

Field	Description
target_hours	Available working hours after subtracting leave and public holidays
allocated_hours	Total hours from active allocations in the range
remaining_hours	target_hours − allocated_hours (negative if over-allocated)
utilisation_pct	allocated / target × 100, rounded to nearest integer
over_allocated	true if allocated_hours > target_hours

Capacity calculation

1. Count working days (Mon–Fri) in the from–to range
2. Subtract public holidays that fall on working days
3. Subtract approved leave days per person (clamped to the query range)
4. Multiply remaining days by weekly_capacity_hours / 5 (daily rate from template profile, default 40h/week)
5. Sum all active allocation hours_per_day × working_days_in_allocation_range per user