Using the API

The API gives you (or your developer) direct read and write access to the leads NeighborStack captures for your account — for wiring into your own software when Zapier isn't the right fit. All endpoints live under https://www.neighborstack.com, accept and return JSON, and require HTTPS.

Authentication

Every request is authenticated with an API key sent in the X-API-Key header. Generate keys in your dashboard under Settings → Integrations → Generate API Key. A key grants full access to your account's leads — treat it like a password. Keys are shown once at creation and can be revoked anytime; up to 5 keys can be active per account.

curl https://www.neighborstack.com/api/zapier/me \
  -H "X-API-Key: nbs_live_..."

GET /api/zapier/me

Verifies a key and returns the account it belongs to — use it as a connection test.

{ "id": "clx...", "businessName": "Bob's Roofing", "email": "bob@example.com" }

The Lead object

Webhook deliveries and all lead endpoints return the same lead shape. Field names are stable — new fields may be added over time, but existing ones are never renamed or removed.

List recent leads

GET /api/zapier/leads?limit=3

Returns an array of your newest leads, most recent first. limit defaults to 3, max 50.

Create a lead

POST /api/zapier/leads

curl -X POST https://www.neighborstack.com/api/zapier/leads \
  -H "X-API-Key: nbs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "+15125550142",
    "service_type": "Lawn Care",
    "customer_name": "Maria Santos",
    "service_description": "Weekly mowing",
    "urgency": "this_week",
    "estimated_value": 320
  }'

customer_phone and service_type are required. Optional: customer_name, customer_first_name, customer_last_name, customer_email, customer_address, service_description, urgency, budget_range, status, priority, lead_source, estimated_value. Returns the created Lead object with status 201.

Find leads

GET /api/zapier/leads/search?phone=+15125550142

Search by phone or email (one is required). Returns up to 5 matches, newest first; an empty array means no match.

Update a lead's status

POST /api/zapier/leads/:id/status

{ "status": "qualified" }

Allowed values: new, contacted, qualified, quoted, booked, won, lost. Returns the updated Lead object. Moving a lead into qualified fires the lead.qualified webhook.

Errors

Errors return a JSON body with a human-readable message:

{ "error": "customer_phone and service_type are required" }