API Reference

The Malcolm API is a RESTful JSON API. All requests require authentication and must be made over HTTPS.

Base URL

https://api.trymalcolm.com/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer mk_live_...

Key prefix	Environment
`mk_live_`	Production
`mk_test_`	Sandbox

Endpoints

POST /quotes

Create a new quote request. Malcolm fans the request out to all eligible insurers and returns aggregated results.

Request body

Field	Type	Required	Description
`line_of_business`	string	Yes	Insurance line (general_liability, bop, workers_comp, cyber)
`risk`	object	Yes	Risk details - varies by line
`coverage`	object	Yes	Requested coverage parameters
`carrier_filter`	array	No	Limit to specific insurer IDs

Response

{
  "id": "qt_abc123",
  "status": "quoted",
  "created_at": "2025-01-15T10:30:00Z",
  "carriers": [
    {
      "carrier": "Acme Insurance",
      "carrier_id": "car_acme",
      "premium_annual": 2847,
      "premium_monthly": 245,
      "bindable": true,
      "quote_expires_at": "2025-02-15T00:00:00Z",
      "coverage_details": {}
    }
  ]
}

POST /quotes/:id/bind

Bind an accepted quote to create a policy.

Request body

Field	Type	Required	Description
`carrier`	string	Yes	Insurer name or ID
`effective_date`	string	Yes	ISO 8601 date

GET /quotes/:id

Retrieve a quote by ID. Useful for polling status on async quotes.

GET /carriers

List all available insurers and the lines of business they support.

Response

{
  "carriers": [
    {
      "id": "car_acme",
      "name": "Acme Insurance",
      "lines": ["general_liability", "bop"],
      "states": ["CA", "NY", "TX"]
    }
  ]
}

Rate limits

Plan	Requests/min
Sandbox	60
Production	600
Enterprise	Custom

Rate-limited responses return HTTP 429 with a Retry-After header.

Pagination

List endpoints support cursor-based pagination via starting_after and limit query parameters.

GET /v1/carriers?limit=10&starting_after=car_acme