Buy your first lead

Steps

1. 1

   List opportunities

   You only get leads that match your saved filters; add filterId for one filter. Opportunities are anonymised (no name, contact data or street) and sorted by most recent homeowner activity.

   Both lists on this page are paged: limit (default 16, max 100); pass nextCursor back as cursor — it is absent on the last page.

   curl Copy

   # Your filters and their IDs
   curl https://demo.api.lead.zolar.tech/api/public/v2/installer/filters \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"
   
   # Leads you can buy, across all filters or for one
   curl "https://demo.api.lead.zolar.tech/api/public/v2/installer/opportunities?filterId=[FILTER ID]" \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"

   Response (one row) Copy

   {
     "id": "[LEAD ID]",
     "leadPhase": "CUSTOMER_LEAD",
     "postalCode2Digit": "12",
     "city": "Musterstadt",
     "country": "de",
     "price": { "value": 49, "isPromo": false },
     "source": { "displayName": "My Marketplace" }
   }

2. 2

   Buy it

   Send the price.value you just read — it is the same for EXCLUSIVE and NONEXCLUSIVE — with the filterId that surfaced the lead.

   curl Copy

   curl -X POST https://demo.api.lead.zolar.tech/api/public/v2/installer/opportunities/[LEAD ID]/buy \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]" \
     -H "Content-Type: application/json" \
     -d '{
       "filterId": "[FILTER ID]",
       "priceType": "NONEXCLUSIVE",
       "price": [PRICE.VALUE FROM THE OPPORTUNITY]
     }'

   409 means the price changed (or the lead is gone) — fetch the opportunity again and retry with the new price.

   If the marketplace limits purchases, the opportunity shows buyLimitRemaining and buyLimitPeriodEnd (when the limit resets). A 201 returns the bought lead with full contact data, as in GET /installer/leads.

3. 3

   Get the contact data

   GET /installer/leads lists your bought leads, newest first, with full contact data and a leadOfferId.

   Filter with status, updatedSince (at most 90 days back) or isNew (open leads whose homeowner confirmed their interest again). Leads stay listed after their personal data is anonymised for privacy or retention.

   curl Copy

   curl https://demo.api.lead.zolar.tech/api/public/v2/installer/leads \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]"

4. 4

   Update its status

   Optional

   Use the leadOfferId, not the lead ID; statuses are OPEN, CONTACTED, QUALIFIED, NOT_REACHED, NOT_INTERESTED, WON and LOST — the stages of the My Jobs board in the portal.

   curl Copy

   curl -X PATCH https://demo.api.lead.zolar.tech/api/public/v2/installer/leads/[LEAD OFFER ID] \
     -H "Authorization: Bearer sk_[YOUR DEMO KEY]" \
     -H "Content-Type: application/json" \
     -d '{ "status": "CONTACTED" }'