---
name: servicelocal-agency-funnels
description: Build or change a sales funnel for an agency on ServiceLocal - send leads to the intake API, sell the agency's own plans with hosted checkouts, and act on signed webhooks. Use whenever a task touches a ServiceLocal agency's landing page, lead form, checkout or webhook receiver.
---

# ServiceLocal agency funnels

The full guide is the source of truth: https://servicelocal.ai/developers/agency-api.md
Read it before writing code, and again when an answer surprises you.

## Ask first

- Who the funnel is for, which plan or plans it sells, which pages it has.
- Which tools it runs on (GoHighLevel, a website builder, your own server).
- Whether the agency only needs a buy link: with its own domain connected, every plan has one under Pricing › Plans, no code needed.

## Workflow

1. **Leads in.** POST each lead to `https://app.servicelocal.ai/api/public/agency-intake` with header `X-Intake-Key` from `SERVICELOCAL_INTAKE_KEY`. Body: `businessName`, `email`, `phone`, optional `trade` and `websiteUrl`.
2. **Show the plans.** `GET https://app.servicelocal.ai/api/public/v1/offers?channel=api` with header `X-ServiceLocal-Key` from `SERVICELOCAL_API_KEY`. Render the name, `firstPayment`, `price` and `sheet.modules` from the answer.
3. **Sell.** From the server, `POST /api/public/v1/checkouts` with an `Idempotency-Key` header, one `offerKeys` entry, the `offerVersion` you showed, `buyer.email`, `buyer.name`, `buyer.phone`, `successUrl`, `cancelUrl` and your contact id in `metadata`. Redirect the buyer to `data.url`.
4. **Events out.** Receive webhooks on a public `https` endpoint. Verify `X-ServiceLocal-Signature` on the raw body, drop an `eventId` already seen, and act on `client.activated` and `subscription.canceled`.

## Rules

- Keys live in server env vars only: never in browser code, page HTML, a prompt or a repository.
- Never hardcode prices or plan ids: read the offers before each render.
- The success page proves nothing. Trust the signed webhook, or `GET /api/public/v1/checkouts/<checkoutId>` reading `complete`.
- `409 offer_version_changed`: read the offers again and show the new price.
- One `Idempotency-Key` per buy attempt, resent only to retry the same body. On `409 open_payment_link_required`, read the checkout; if `expired`, sell again with a new key.
- Selling needs Getting paid set up and the agency's own ServiceLocal plan active (`agency_cannot_sell`, `agency_subscription_required`).
- Answer webhooks with 2xx within 10 seconds; do slow work after answering.
