Activity Attribution Service - API Contract

GET /api/v1/activity-attributions/api/v1/activity-attributions

List attributed activities, filterable by mentor (attributed-to) or coordinator (registrant)

Public

Response Example

{
  "data": [
    {
      "attribution_id": "attr-20260325-001",
      "activity_id": "pact-20260325-001",
      "attributed_to_mentor_id": "mentor-042",
      "attributed_to_mentor_name": "Sam Rivera",
      "registered_by_coordinator_id": "coord-007",
      "registered_by_coordinator_name": "Jordan Lee",
      "activity_type_id": "one-on-one",
      "activity_date": "2026-03-24T14:00:00Z",
      "proxy": true,
      "created_at": "2026-03-24T15:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 28
  }
}

GET /api/v1/activity-attributions/api/v1/activity-attributions/:id

Get a single attribution record by ID

Public

Response Example

{
  "attribution_id": "attr-20260325-001",
  "activity_id": "pact-20260325-001",
  "attributed_to_mentor_id": "mentor-042",
  "attributed_to_mentor_name": "Sam Rivera",
  "registered_by_coordinator_id": "coord-007",
  "registered_by_coordinator_name": "Jordan Lee",
  "activity_type_id": "one-on-one",
  "activity_date": "2026-03-24T14:00:00Z",
  "duration_minutes": 60,
  "proxy": true,
  "audit_trail": [
    {
      "event": "created",
      "actor": "coord-007",
      "at": "2026-03-24T15:30:00Z"
    }
  ],
  "created_at": "2026-03-24T15:30:00Z"
}

POST /api/v1/activity-attributions/api/v1/activity-attributions

Build and create an attributed activity record linking a draft to a coordinator and mentor

Public

Request Example

{
  "activity_type_id": "workshop",
  "activity_date": "2026-03-26T09:00:00Z",
  "duration_minutes": 120,
  "location": "Innovation Lab",
  "notes": "Ran resume workshop for junior cohort",
  "coordinator_id": "coord-007",
  "mentor_id": "mentor-033"
}

Response Example

{
  "attribution_id": "attr-20260326-002",
  "activity_id": "pact-20260326-015",
  "attributed_to_mentor_id": "mentor-033",
  "registered_by_coordinator_id": "coord-007",
  "activity_type_id": "workshop",
  "activity_date": "2026-03-26T09:00:00Z",
  "proxy": true,
  "created_at": "2026-03-26T08:55:00Z"
}

PUT /api/v1/activity-attributions/api/v1/activity-attributions/:id

Update an attribution record (e.g. correct mentor or activity details)

Public

Request Example

{
  "activity_date": "2026-03-26T10:00:00Z",
  "duration_minutes": 90,
  "notes": "Updated: session ran longer than expected"
}

Response Example

{
  "attribution_id": "attr-20260326-002",
  "activity_date": "2026-03-26T10:00:00Z",
  "duration_minutes": 90,
  "notes": "Updated: session ran longer than expected",
  "updated_at": "2026-03-26T11:00:00Z"
}

DELETE /api/v1/activity-attributions/api/v1/activity-attributions/:id

Remove an attribution record (coordinator or admin only)

Public

Response Example

{
  "message": "Attribution attr-20260325-001 deleted",
  "deleted_at": "2026-03-26T09:00:00Z"
}

GET /api/v1/activity-attributions/api/v1/activity-attributions/audit-log

Get the full proxy registration audit log for an organization within a date range

Public

Response Example

{
  "data": [
    {
      "event": "proxy_activity_created",
      "attribution_id": "attr-20260325-001",
      "activity_id": "pact-20260325-001",
      "actor_id": "coord-007",
      "actor_name": "Jordan Lee",
      "mentor_id": "mentor-042",
      "mentor_name": "Sam Rivera",
      "activity_type_id": "one-on-one",
      "activity_date": "2026-03-24T14:00:00Z",
      "occurred_at": "2026-03-24T15:30:00Z"
    },
    {
      "event": "bulk_batch_confirmed",
      "batch_id": "batch-20260325-007",
      "actor_id": "coord-007",
      "actor_name": "Jordan Lee",
      "mentor_count": 10,
      "skipped_count": 2,
      "occurred_at": "2026-03-25T09:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 62
  }
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}