API Reference

Creating and Managing Inspections

This guide explains how to programmatically request and manage property inspections using the Modern Insurer API. You'll learn how to create the required resources, submit inspection requests, and receive real-time updates as inspections progress.

Overview

Modern Insurer supports claim and underwriting inspections. To share assignment data with the assigned contractor, the API supports additional information, like policyNumber and claimNumber in addition to information about the requestor in case the contractor has questions.

Prerequisites

Before creating an inspection, you'll need:

  • A Modern Insurer API key with appropriate permissions
  • A webhook endpoint configured to receive inspection status updates (optional, but recommended)

Step-by-Step Implementation Guide

1. Create a Property

👍

Best Practice

Store and reuse the property's unique id to maintain data consistency.

Create a property record. Pass contact information and, optionally, information about the policy:

POST /properties
{
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
  },
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "14155551234"
  },
  "policyNumber": "POL-2024-001",
  "policyType": "home"
}

Response:

{
  "propertyId": "507f1f77bcf86cd799439011",
  "address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "latitude": "string",
    "longitude": "string"
  },
  "normalizedAddress": {
    "street": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94105",
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "14155551234"
  },
  "policyNumber": "POL-2024-001",
  "policyType": "home"
}

2. Request an Inspection

With a property created, you can now request an inspection:

POST /inspections
{
  "propertyId": "507f1f77bcf86cd799439011",
  "type": "claim",
  "protocol": "wildfire_prepared_home",
  "requestor": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "14155551234"
  },
  "claimNumber": "CLM-2024-001",
  "dateOfLoss": "2024-03-15",
  "peril": "wildfire",
  "note": "Please check the roof condition carefully"
}

Response:

{
  "inspectionId": "507f1f77bcf86cd799439011",
  "status": "requested",
  "type": "claim",
  "propertyId": "507f1f77bcf86cd799439011",
  "protocol": "wildfire_prepared_home",
  "requestor": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "14155551234"
  },
  "dateOfLoss": "2024-03-15",
  "peril": "wildfire",
  "claimNumber": "CLM-2024-001"
}

3. Listen for Webhooks

Modern Insurer uses webhooks to notify your system about inspection status changes. Here are the key events you'll receive:

Inspection Assigned

Sent when the assigned contractor accepts the assignment.

{
  "eventType": "inspection.assigned",
  "inspectionId": "676ee72e11ea12e6eb282c22"
}

Inspection Scheduled

Sent when the contractor schedules the inspection with the contact. Includes the scheduledDate which can be displayed in your insured or agent portal.

{
  "eventType": "inspection.scheduled",
  "inspectionId": "676ee72e11ea12e6eb282c22",
  "scheduledDate": "2024-12-31T00:00:00.000Z"
}

Inspection Completed

Sent when the contractor completes the assignment. Includes the report object, that includes a link to the inspection report provided by the contractor.

{
  "eventType": "inspection.completed",
  "inspectionId": "676ee72e11ea12e6eb282c22",
  "report": {
    "filename": "123_main_st_inspection_report.pdf",
    "uploadDate": "2024-12-27T17:44:30.572Z",
    "url": "https://mxoiflstnghwqac9.public.blob.vercel-storage.com/inspection_report.pdf"
  }
}

For additional information about the inspection lifecycle, see the Inspection Webhooks guide.

4. Support Inspection Cancellations

You can cancel an inspection that hasn't been completed:

POST /inspections/{inspectionId}/cancel

The system will confirm that the cancellation was successful with a webhook event:

{
  "eventType":"inspection.cancelled",
  "inspectionId":"676f879211ea12e6eb282cb7"
}