Dumpster Controls · agent page

This is the agent-optimized version of https://dumpstercontrols.io/help/api/push-and-read-leads: the same content as the human page, without scripts, styles, animations or navigation. People should open the full page.

Canonical page
https://dumpstercontrols.io/help/api/push-and-read-leads
Last updated
2026-10-13
Tokens
883 tokens (cl100k_base), within the 2,500-token budget for a help page
Size
7.5 KB for this page, against 24 KB for the human page (68% smaller)
Markdown
https://dumpstercontrols.io/help/api/push-and-read-leads.md, or send Accept: text/markdown to the canonical URL
Cite as
Push and read leads (the CRM and funnel endpoint). Dumpster Controls. https://dumpstercontrols.io/help/api/push-and-read-leads (accessed 2026-11-16).
More for agents
Facts sheet · llms.txt · llms-full.txt · All agent pages · Product manual

Developer API · updated 2026-10-13

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. ## 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":"jane@example.com","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. ## 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. ## Leads 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 includes 200 leads per day (429 lead_quota_exceeded beyond that); the paid plan has no daily lead count.
  4. ## Read leads back
    ```
    GET /v1/leads (page, per_page) lists leads newest first with their status: new, contacted, converted or discarded.
    ```
  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.

Troubleshooting

My funnel posts twice and I see one lead. Bug?

No, that is the 10-minute deduplication working. The second response had existing: true.

Can the API create an order directly?

Not in v1, by design. Leads are the safe entry point; a human converts them. Order creation carries payment and scheduling consequences we keep behind the app's own flows.

Related guides

© 2026 Dumpster Controls. All rights reserved. Made in the USA.