Developer API · updated 2026-08-22

Push and read leads (the CRM and funnel endpoint)

POST /v1/leads is the write endpoint of the API: your website forms, GoHighLevel funnels or ad landing pages push prospects straight into Dumpster Controls, where your team sees them in the Customers screen under Leads and converts them with one click.

1. 1

   Create a lead

   POST /v1/leads with a JSON body. Only name is required:

   curl -X POST -H "Authorization: Bearer dc_live_..." \
     -H "Content-Type: application/json" \
     -d '{"name":"Jane Smith","phone":"5551234567","email":"[email protected]","address":"4830 Collins Rd, Jacksonville, FL","size_label":"20 Yard","note":"Garage cleanout, needs it Saturday"}' \
     https://gcwyoiihrupbfqqlcurh.supabase.co/functions/v1/api-v1/v1/leads

   A 201 returns the created lead. Field limits: name 120, phone 40, email 200, address 300, size_label 60, note 2000 characters.

2. 2

   Deduplication

   If the same phone or email was already pushed within the last 10 minutes, the API returns 200 with the EXISTING lead and existing: true instead of creating a duplicate. Funnel tools that double-fire are handled for you. Phone numbers are normalized to digits (plus a leading +, when present) for storage and matching.

3. 3

   Quota and the window

   Leads deliberately do NOT consume the free plan's 10-minute window, because a prospect can fill your form at any hour. The free plan allows 200 leads per day (429 lead_quota_exceeded beyond that); paid plans are unlimited.

4. 4

   Read leads back

   GET /v1/leads (page, per_page) lists leads newest first with their status: new, contacted, converted or discarded.

5. 5

   What your team sees

   Every pushed lead appears instantly in Customers, in the Leads panel, with a "new" badge. From there the office marks it contacted, converts it into a real customer, or discards it. The lead.created webhook also fires, so you can chain automations.