API changelog

This is the change history of the Cooledge API contract: the endpoints, fields and webhook events you build against. It is for integrators who need to know when the API surface changes and whether a change can affect their code.

This is not the product "what's new". Customer-facing feature announcements live in the Cooledge changelog. This page only records changes to the API contract.

Versioning policy

The API is versioned by path, starting at v1 (for example /v1/customers). Two kinds of change can happen, and they are treated differently:

Additive changes are backward compatible. New fields on a response, new optional request parameters, new endpoints and new webhook event types are all additive. They do not break code that does not use them, so they can ship inside the current version without a version bump and without a dated entry being required for every one. The most important consequence for you: tolerate unknown fields. Ignore any field or event type you do not recognise rather than failing on it, because new ones can appear at any time.
Breaking changes get a new API version. Removing or renaming a field, changing a field's type or meaning, removing an endpoint or tightening validation in a way that rejects requests that used to work are all breaking. A breaking change ships under a new version path so your existing integration keeps working against the version it was built for. Every breaking change gets a dated entry on this page so you can see what moved and when.

When in doubt, code defensively: read the fields you need, ignore the rest and do not assume the set of fields or event types is fixed.

Changes

2026-06-28: opt-in lead notifications on create

POST /v1/leads now accepts an optional notify boolean. It defaults to false, so nothing changes for existing integrations. Set it to true to send the business owner the same new-lead email and push notification that the chat widget and website forms send, which is what you want when a lead comes from a connected form or app. Leave it off (or omit it) for bulk imports and syncs so the owner is not flooded with alerts. The business's own lead-notification email setting still applies, so an owner who has turned those emails off will not get one even when you pass notify: true.

2026-06-23: lead lifecycle events reworked

The lead events now track the lead's real lifecycle from capture to won. These are additive and meaning-preserving for the event names, but the lead payloads changed, so check the notes below if you consume them.

New lead.won event. A lead now reports when the deal is won. It fires once, when a quote is accepted, when a quote is paid, when the first invoice is paid on a lead that never had a quote or when the lead is marked won manually. Creating a job does not win a lead. See lead.won.
lead.converted redefined. It now fires once when a lead becomes an active opportunity, meaning its first quote or job is created or it is qualified manually. It no longer fires on customer linking at creation. The payload drops customer_was_created and adds converted_via (quote, job or manual), quote_id and job_id. See lead.converted.
lead.created now fires for every owned lead. It fires for leads from the portal, your website forms, the API and inbound GoHighLevel, not only API and GoHighLevel leads. The payload field type is renamed to lead_type (for example inbound or marketplace) and the site_id field is removed. customer_id is usually null at creation. See lead.created.
v1 leads-create parameter renamed. On POST /v1/leads the auto_convert field is renamed to auto_create_customer, which is what it actually controls.

2026-06-17: v1 initial release

The first public version of the Cooledge API. The launch surface is:

Resources. Read and manage customers and their sites, jobs, quotes, invoices, bookings and leads, plus the /v1/me identity endpoint that returns the business a key belongs to and the scopes it holds.
Webhook events. Twelve event types across customers, leads, quotes, invoices, jobs and bookings, listed in full on the events index. Every delivery is signed and carries a stable event id for deduping.
Cursor pagination. List endpoints return a data array and a next_cursor, paged with an opaque cursor. See Pagination and errors.
RFC 7807 errors. Every error response is problem-details JSON with a stable type URN, a status and an optional detail. See Pagination and errors.
API-key authentication. Requests are authenticated with the X-Api-Key header. See Authentication for the key format and the scope list.

Where to go next

Getting started walks through your first call.
The API reference is the endpoint-by-endpoint specification.
The events index lists every webhook event type.