Participant Deduplication Service - API Contract

GET /api/v1/participant-deduplication/api/v1/participant-deduplication

List deduplication results for an org/period

Public

Response Example

{
  "data": [
    {
      "id": "dedup-011",
      "org_id": "org-bufdir-42",
      "period_id": "rp-2024-q4",
      "activity_type": "group_session",
      "raw_record_count": 2100,
      "unique_participant_count": 1601,
      "duplicate_count": 499,
      "ambiguous_count": 14,
      "proxy_overlap_detected": true,
      "run_at": "2025-01-05T08:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

GET /api/v1/participant-deduplication/api/v1/participant-deduplication/:id

Get a specific deduplication result by ID

Public

Response Example

{
  "id": "dedup-011",
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "activity_type": "group_session",
  "raw_record_count": 2100,
  "unique_participant_count": 1601,
  "duplicate_count": 499,
  "ambiguous_count": 14,
  "proxy_overlap_detected": true,
  "flagged_conflicts": [
    {
      "conflict_id": "conf-88",
      "participant_hash": "a3f9e2c1",
      "conflict_type": "proxy_direct_overlap",
      "occurrences": 3
    }
  ],
  "run_at": "2025-01-05T08:05:00Z"
}

POST /api/v1/participant-deduplication/api/v1/participant-deduplication

Run deduplication on raw participant records for an org

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "raw_records": [
    {
      "participant_hash": "a3f9e2c1",
      "activity_type": "group_session",
      "registration_type": "direct",
      "event_date": "2025-01-15"
    },
    {
      "participant_hash": "a3f9e2c1",
      "activity_type": "group_session",
      "registration_type": "bulk",
      "event_date": "2025-01-15"
    }
  ]
}

Response Example

{
  "id": "dedup-022",
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "raw_record_count": 2,
  "unique_participant_count": 1,
  "duplicate_count": 1,
  "ambiguous_count": 0,
  "proxy_overlap_detected": true,
  "run_at": "2025-03-26T09:00:00Z"
}

PUT /api/v1/participant-deduplication/api/v1/participant-deduplication/:id

Reprocess or update an existing deduplication result

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "reprocess": true
}

Response Example

{
  "id": "dedup-011",
  "org_id": "org-bufdir-42",
  "unique_participant_count": 1603,
  "duplicate_count": 497,
  "run_at": "2025-03-26T09:20:00Z"
}

DELETE /api/v1/participant-deduplication/api/v1/participant-deduplication/:id

Delete a deduplication result record

Public

Response Example

{
  "deleted": true,
  "id": "dedup-011"
}

GET /api/v1/participant-deduplication/api/v1/participant-deduplication/unique-count

Get unique participant count for org, period, and activity type

Public

Response Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "activity_type": "group_session",
  "unique_participant_count": 1601
}

Additional Metadata

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