Reporting Period Service - API Contract

GET /api/v1/reporting-periods/api/v1/reporting-periods

List all reporting periods for an organization

Public

Response Example

{
  "data": [
    {
      "id": "rp-2024-q4",
      "org_id": "org-bufdir-42",
      "label": "Q4 2024",
      "period_start": "2024-10-01",
      "period_end": "2024-12-31",
      "status": "closed",
      "is_current": false,
      "submission_deadline": "2025-01-31"
    },
    {
      "id": "rp-2025-q1",
      "org_id": "org-bufdir-42",
      "label": "Q1 2025",
      "period_start": "2025-01-01",
      "period_end": "2025-03-31",
      "status": "open",
      "is_current": true,
      "submission_deadline": "2025-04-30"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 6
  }
}

GET /api/v1/reporting-periods/api/v1/reporting-periods/current

Get the current active reporting period for an organization

Public

Response Example

{
  "id": "rp-2025-q1",
  "org_id": "org-bufdir-42",
  "label": "Q1 2025",
  "period_start": "2025-01-01",
  "period_end": "2025-03-31",
  "status": "open",
  "is_current": true,
  "submission_deadline": "2025-04-30"
}

GET /api/v1/reporting-periods/api/v1/reporting-periods/:id

Get a specific reporting period by ID

Public

Response Example

{
  "id": "rp-2024-q4",
  "org_id": "org-bufdir-42",
  "label": "Q4 2024",
  "period_start": "2024-10-01",
  "period_end": "2024-12-31",
  "status": "closed",
  "is_current": false,
  "submission_deadline": "2025-01-31",
  "submitted_at": "2025-01-28T14:00:00Z"
}

POST /api/v1/reporting-periods/api/v1/reporting-periods

Create a new reporting period for an organization

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "label": "Q2 2025",
  "period_start": "2025-04-01",
  "period_end": "2025-06-30",
  "submission_deadline": "2025-07-31"
}

Response Example

{
  "id": "rp-2025-q2",
  "org_id": "org-bufdir-42",
  "label": "Q2 2025",
  "period_start": "2025-04-01",
  "period_end": "2025-06-30",
  "status": "upcoming",
  "is_current": false,
  "submission_deadline": "2025-07-31",
  "created_at": "2025-03-26T09:00:00Z"
}

PUT /api/v1/reporting-periods/api/v1/reporting-periods/:id

Update a reporting period (e.g., extend deadline, change status)

Public

Request Example

{
  "submission_deadline": "2025-08-15",
  "status": "open"
}

Response Example

{
  "id": "rp-2025-q2",
  "org_id": "org-bufdir-42",
  "label": "Q2 2025",
  "period_start": "2025-04-01",
  "period_end": "2025-06-30",
  "status": "open",
  "submission_deadline": "2025-08-15",
  "updated_at": "2025-03-26T10:00:00Z"
}

DELETE /api/v1/reporting-periods/api/v1/reporting-periods/:id

Delete a reporting period (only allowed if status is 'upcoming')

Public

Response Example

{
  "deleted": true,
  "id": "rp-2025-q2"
}

GET /api/v1/reporting-periods/api/v1/reporting-periods/:id/check-date

Check if a given date falls within a reporting period

Public

Response Example

{
  "period_id": "rp-2025-q1",
  "date": "2025-02-14",
  "within_period": true
}

Additional Metadata

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