> ## Documentation Index
> Fetch the complete documentation index at: https://docs.n-3.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Interim Report

> Create a new interim report with comprehensive drawdown tracking, risk assessments, and site visit documentation

Create a detailed interim report for tracking project progress during active project phases. This endpoint combines financial drawdown data, risk status assessments, and site visit documentation into a single comprehensive report.

## Request Body

<ParamField body="project_id" type="bigint" required>
  The unique identifier of the project for which the interim report is being created
</ParamField>

<ParamField body="month" type="number" required>
  The month of the reporting period (1-12)
</ParamField>

<ParamField body="year" type="number" required>
  The year of the reporting period
</ParamField>

<ParamField body="edition" type="number">
  The edition number of the report (defaults to 1 for new reports)
</ParamField>

<ParamField body="comments" type="string">
  General comments or notes about the project status for this reporting period
</ParamField>

<ParamField body="aggregate" type="object" required>
  Aggregate financial information for the reporting period

  <Expandable title="aggregate">
    <ParamField body="amount" type="number" required>
      Total amount drawn down across all facilities
    </ParamField>

    <ParamField body="surplus_shortfall" type="number">
      Overall surplus (positive) or shortfall (negative) amount
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="facility" type="array" required>
  Array of facility-specific drawdown information

  <Expandable title="facility items">
    <ParamField body="facility_id" type="bigint" required>
      Identifier of the project facility
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount drawn down for this facility
    </ParamField>

    <ParamField body="surplus_shortfall" type="number">
      Facility-specific surplus or shortfall amount
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="riskStatus" type="array" required>
  Array of risk assessment entries for the reporting period

  <Expandable title="riskStatus items">
    <ParamField body="input_setting_id" type="bigint" required>
      ID of the risk input setting being assessed
    </ParamField>

    <ParamField body="risk_status_legend_id" type="bigint" required>
      ID of the risk status legend entry that applies
    </ParamField>

    <ParamField body="notes" type="string">
      Notes explaining the risk assessment or changes from previous period
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="visit" type="object">
  Site visit information (optional, only include if a site visit occurred)

  <Expandable title="visit">
    <ParamField body="date" type="string">
      Date of the site visit in YYYY-MM-DD format
    </ParamField>

    <ParamField body="notes" type="string">
      Detailed notes from the site visit
    </ParamField>

    <ParamField body="files" type="array">
      Array of files (photos, documents) from the site visit

      <Expandable title="files items">
        <ParamField body="filename" type="string" required>
          Original filename of the uploaded file
        </ParamField>

        <ParamField body="s3_location" type="string" required>
          S3 location path where the file is stored
        </ParamField>

        <ParamField body="file_size" type="number">
          Size of the file in bytes
        </ParamField>

        <ParamField body="mime_type" type="string">
          MIME type of the file (e.g., image/jpeg, application/pdf)
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

```json theme={null}
{
  "project_id": "123456789",
  "month": 6,
  "year": 2024,
  "edition": 1,
  "comments": "Q2 progress showing strong advancement on main structure",
  "aggregate": {
    "amount": 150000,
    "surplus_shortfall": 5000
  },
  "facility": [
    {
      "facility_id": "987654321",
      "amount": 75000,
      "surplus_shortfall": 2500
    },
    {
      "facility_id": "987654322",
      "amount": 75000,
      "surplus_shortfall": 2500
    }
  ],
  "riskStatus": [
    {
      "input_setting_id": "111",
      "risk_status_legend_id": "222",
      "notes": "Risk level maintained at low due to good weather conditions"
    },
    {
      "input_setting_id": "333",
      "risk_status_legend_id": "444",
      "notes": "Material delivery risk increased due to supply chain delays"
    }
  ],
  "visit": {
    "date": "2024-06-15",
    "notes": "Foundation work completed ahead of schedule. Steel frame installation proceeding well. No safety issues observed.",
    "files": [
      {
        "filename": "foundation_complete.jpg",
        "s3_location": "projects/123456789/site-visits/2024-06/foundation_complete.jpg",
        "file_size": 2048576,
        "mime_type": "image/jpeg"
      },
      {
        "filename": "steel_frame_progress.jpg",
        "s3_location": "projects/123456789/site-visits/2024-06/steel_frame_progress.jpg",
        "file_size": 1536789,
        "mime_type": "image/jpeg"
      }
    ]
  }
}
```

## Response

Returns the created report with its unique identifier:

<ResponseField name="id" type="bigint">
  Unique identifier of the created interim report
</ResponseField>

<ResponseField name="created_date" type="string">
  ISO timestamp when the report was created
</ResponseField>

<ResponseField name="project_id" type="bigint">
  ID of the associated project
</ResponseField>

<ResponseField name="month" type="number">
  Month of the reporting period
</ResponseField>

<ResponseField name="year" type="number">
  Year of the reporting period
</ResponseField>

<ResponseField name="edition" type="number">
  Edition number of the report
</ResponseField>

<ResponseField name="template_id" type="bigint">
  ID of the template used for report generation
</ResponseField>

<ResponseField name="type" type="string">
  Report type (will be "INTERIM\_REPORT")
</ResponseField>

## Example Response

```json theme={null}
{
  "id": "789012345",
  "created_date": "2024-06-20T10:30:00.000Z",
  "project_id": "123456789",
  "month": 6,
  "year": 2024,
  "edition": 1,
  "template_id": "555666777",
  "type": "INTERIM_REPORT"
}
```

## Automatic Actions

When an interim report is successfully created, the system automatically:

1. **Creates Project Event**: Logs a `REPORT_UPLOADED` event for audit tracking
2. **Updates Project Comments**: Saves the comments field to the project record
3. **Applies Template**: Uses the first available interim report template for the environment
4. **Validates Data**: Ensures all required data relationships exist and are valid

## Error Responses

<ResponseField name="400" type="error">
  **Bad Request** - Missing required fields or invalid data format

  ```json theme={null}
  {
    "statusCode": 400,
    "message": "Project ID is required",
    "error": "Bad Request"
  }
  ```
</ResponseField>

<ResponseField name="403" type="error">
  **Forbidden** - User does not have access to the specified project

  ```json theme={null}
  {
    "statusCode": 403,
    "message": "User does not have access to this project",
    "error": "Forbidden"
  }
  ```
</ResponseField>

<ResponseField name="404" type="error">
  **Not Found** - Project or referenced entities not found

  ```json theme={null}
  {
    "statusCode": 404,
    "message": "Project not found",
    "error": "Not Found"
  }
  ```
</ResponseField>

## Notes

* All monetary amounts should be provided as numbers (not strings)
* Site visit information is optional - omit the entire `visit` object if no visit occurred
* Risk status assessments are required for all interim reports
* The system automatically determines the appropriate template based on the project's environment
* File uploads must be completed separately before creating the report - provide S3 locations in the request