Report Period Validator - API Contract

GET /api/v1/report-period-validations/api/v1/report-period-validations

List historical validation results for an organization

Public

Response Example

{
  "data": [
    {
      "id": "val-001",
      "org_id": "org-bufdir-42",
      "period_start": "2026-01-01",
      "period_end": "2026-03-31",
      "is_valid": true,
      "errors": [],
      "validated_at": "2026-03-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/report-period-validations/api/v1/report-period-validations/:id

Get a specific validation result by ID

Public

Response Example

{
  "id": "val-001",
  "org_id": "org-bufdir-42",
  "period_start": "2026-01-01",
  "period_end": "2026-03-31",
  "is_valid": true,
  "errors": [],
  "validated_at": "2026-03-10T09:00:00Z"
}

POST /api/v1/report-period-validations/api/v1/report-period-validations

Validate a ReportPeriod for an organization (validate)

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "period": {
    "name": "Q1 2026",
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "preset_type": "quarterly"
  }
}

Response Example

{
  "id": "val-002",
  "org_id": "org-bufdir-42",
  "period_start": "2026-01-01",
  "period_end": "2026-03-31",
  "is_valid": false,
  "errors": [
    {
      "code": "OVERLAP_WITH_SUBMITTED",
      "message": "This period overlaps with an already submitted period (2025-10-01 – 2026-02-28).",
      "field": "period"
    }
  ],
  "validated_at": "2026-03-26T10:55:00Z"
}

PUT /api/v1/report-period-validations/api/v1/report-period-validations/:id

Re-run validation for a previously saved validation result

Public

Request Example

{
  "period": {
    "start_date": "2026-01-01",
    "end_date": "2026-03-31"
  }
}

Response Example

{
  "id": "val-001",
  "org_id": "org-bufdir-42",
  "period_start": "2026-01-01",
  "period_end": "2026-03-31",
  "is_valid": true,
  "errors": [],
  "validated_at": "2026-03-26T11:05:00Z"
}

DELETE /api/v1/report-period-validations/api/v1/report-period-validations/:id

Delete a saved validation result

Public

Response Example

{
  "deleted": true,
  "id": "val-001"
}

POST /api/v1/report-period-validations/api/v1/report-period-validations/range-check

Check whether a DateTimeRange has valid start/end boundaries

Public

Request Example

{
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  }
}

Response Example

{
  "is_valid": true,
  "errors": []
}

POST /api/v1/report-period-validations/api/v1/report-period-validations/overlap-check

Check whether a DateTimeRange overlaps with any already-submitted periods for an org

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "range": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  }
}

Response Example

{
  "has_overlap": true,
  "overlapping_periods": [
    {
      "submitted_period_id": "sub-period-009",
      "start_date": "2025-10-01",
      "end_date": "2026-02-28",
      "submitted_at": "2026-02-28T16:00:00Z"
    }
  ]
}

Additional Metadata

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