API Reference

Invoice Webhooks

Invoice Lifecycle

Invoices are created by Contractors in Modern Insurer. When a contractor creates an Invoice, the Invoice starts in a Created state. When the Contractor submits the Invoice, the Invoice moves to a Submitted state.

While in a Submitted state, the Invoice can be approved with the Approve invoice endpoint. When approved, the Invoice moves to an Approved state. Contractors can mark Approved Invoices as Paid, which will update the status of the Invoice to Paid.

While in either a Created or Submitted state, the Contractor can cancel the Invoice. This will move the Invoice to a Cancelled state.

Invoice Lifecycle Diagram

Invoice Lifecycle Diagram

Webhook Events

📘

Created & Paid Statuses

While Created and Paid are valid states in the Invoice lifecycle, state changes to these statuses do not trigger webhook events. This is by design. These changes in state do not require action by the Insurer for the Invoice to proceed with its lifecycle. That said, these statuses will be provided in the Get invoice by ID response.

EventTypeDescription
invoice.submittedThe invoice has been submitted by the contractor.
invoice.approvedThe invoice has been successfully approved via API.
invoice.cancelledThe invoice has been cancelled by the contractor.

Sample Payloads

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

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

{
  "eventType":"invoice.cancelled",
  "invoiceId":"676f8ab911ea12e6eb282cf4",
  "invoiceNumber":"abc-7093421"
}