Skip to main content
POST
/
reports
/
drawdown
Create Interim Report
curl --request POST \
  --url https://api.n-3.co.uk/reports/drawdown \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": {},
  "month": 123,
  "year": 123,
  "edition": 123,
  "comments": "<string>",
  "aggregate": {
    "amount": 123,
    "surplus_shortfall": 123
  },
  "facility": [
    {
      "facility_id": {},
      "amount": 123,
      "surplus_shortfall": 123
    }
  ],
  "riskStatus": [
    {
      "input_setting_id": {},
      "risk_status_legend_id": {},
      "notes": "<string>"
    }
  ],
  "visit": {
    "date": "<string>",
    "notes": "<string>",
    "files": [
      {
        "filename": "<string>",
        "s3_location": "<string>",
        "file_size": 123,
        "mime_type": "<string>"
      }
    ]
  }
}
'
{
  "400": {},
  "403": {},
  "404": {},
  "id": {},
  "created_date": "<string>",
  "project_id": {},
  "month": 123,
  "year": 123,
  "edition": 123,
  "template_id": {},
  "type": "<string>"
}
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

​
project_id
bigint
required
The unique identifier of the project for which the interim report is being created
​
month
number
required
The month of the reporting period (1-12)
​
year
number
required
The year of the reporting period
​
edition
number
The edition number of the report (defaults to 1 for new reports)
​
comments
string
General comments or notes about the project status for this reporting period
​
aggregate
object
required
Aggregate financial information for the reporting period
​
facility
array
required
Array of facility-specific drawdown information
​
riskStatus
array
required
Array of risk assessment entries for the reporting period
​
visit
object
Site visit information (optional, only include if a site visit occurred)

​
Example Request

{
  "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:
​
id
bigint
Unique identifier of the created interim report
​
created_date
string
ISO timestamp when the report was created
​
project_id
bigint
ID of the associated project
​
month
number
Month of the reporting period
​
year
number
Year of the reporting period
​
edition
number
Edition number of the report
​
template_id
bigint
ID of the template used for report generation
​
type
string
Report type (will be “INTERIM_REPORT”)

​
Example Response

{
  "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

​
400
error
Bad Request - Missing required fields or invalid data format
{
  "statusCode": 400,
  "message": "Project ID is required",
  "error": "Bad Request"
}
​
403
error
Forbidden - User does not have access to the specified project
{
  "statusCode": 403,
  "message": "User does not have access to this project",
  "error": "Forbidden"
}
​
404
error
Not Found - Project or referenced entities not found
{
  "statusCode": 404,
  "message": "Project not found",
  "error": "Not Found"
}

​
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