API Reference

Receiving and Approving Invoices

This guide explains how to handle contractor invoices using webhooks and the Modern Insurer API. You'll learn how to receive invoice webhooks, fetch invoice details, and approve invoices for payment.

Prerequisites

Before working with invoices, you'll need:

  • A Modern Insurer API key with appropriate permissions
  • A webhook endpoint configured to receive invoice status updates
  • To be requesting contractor assignments with the Modern Insurer API

Core Concepts

Invoice States

An invoice can be in one of the following states:

  • created: Initial state when a contractor creates an invoice
  • submitted: Contractor has submitted the invoice for approval
  • approved: Invoice has been approved via API
  • paid: Contractor has marked the invoice as paid
  • cancelled: Invoice has been cancelled by the contractor

Invoice Lifecycle

The basic lifecycle of an invoice is:

  1. Contractor creates invoice (created state)
  2. Contractor submits invoice (submitted state)
  3. API call approves invoice (approved state)
  4. Contractor marks invoice as paid (paid state)

📘

Note

Contractors can cancel invoices in either created or submitted states, moving them to the cancelled state.

Step-by-Step Implementation Guide

1. Receive Invoice Webhook

When a contractor submits an invoice, you'll receive an invoice.submitted webhook event:

{
  "eventType":"invoice.submitted",
  "invoiceId":"676ee6f411ea12e6eb282c0b",
  "invoiceNumber":"123456-dlkj09"
}

2. Fetch Invoice Details

Use the invoiceId from the webhook to fetch complete invoice details:

GET /invoices/676ee6f411ea12e6eb282c0b

Response:

{
    "invoiceId": "676ee6f411ea12e6eb282c0b",
    "invoiceNumber": "123456-dlkj09",
    "amount": 480,
    "status": "submitted",
    "submittedDate": "2024-12-27T17:46:44.477Z",
    "approvedDate": null,
    "paidDate": null,
    "documentUrl": "https://mxoiflstnghwqac9.public.blob.vercel-storage.com/invoice-123456-dlkj09-W8E1FQ4nR7VKHpWqcDaMfCndYSXP7b.pdf",
    "contractor": {
        "name": "Porter's Risk Reduction",
        "location": {
            "street": "12023 St Bernard Dr",
            "city": "Truckee",
            "state": "ca",
            "zip": "96161"
        }
    }
}

3. Approve Invoice

After reviewing the invoice details, you can approve it:

POST /invoices/676ee6f411ea12e6eb282c0b/approve

Response:

{
    "invoiceId": "676ee6f411ea12e6eb282c0b",
    "status": "approved",
    "amount": 480,
    "invoiceNumber": "123456-dlkj09"
}

When you approve an invoice, Modern Insurer sends an invoice.approved webhook event to your system. You can use this event to trigger a payment to the contractor using your preferred payment provider.

{
  "eventType":"invoice.approved",
  "invoiceId":"676ee6f411ea12e6eb282c0b",
  "invoiceNumber":"123456-dlkj09"
}

Additional Considerations

Contractors can cancel invoices that have been submitted. When that occurs, Modern Insurer sends an invoice.cancelled webhook event.

{
  "eventType": "invoice.cancelled",
  "invoiceId": "676ee6f411ea12e6eb282c0b",
  "invoiceNumber": "123456-dlkj09",
  "cancellationReason": "Services no longer needed",
  "timestamp": "2024-03-15T10:00:00.000Z"
}