Developers / Agencies

Agency API

Send leads in, sell your plans from your own funnel, and get an event when a client pays.

This guide is for agencies on ServiceLocal and the developers and AI agents who build their funnels. It covers three things: sending leads in, selling your plans from your own funnel, and getting a signed event when a client pays or cancels.

No developer? Once your agency has its own domain (Settings › Domains), every plan has a buy link under Pricing › Plans. Paste it on any page and the lead pays you directly.

Quick start

  1. Get a key. In your agency console, open Settings › Funnels & API › API keys and create one. Keep it on your server.
  2. List your plans.
curl "https://app.servicelocal.ai/api/public/v1/offers?channel=api" \
  -H "X-ServiceLocal-Key: $SERVICELOCAL_API_KEY"
  1. Start a checkout for one plan and send the buyer to the url it returns.
curl -X POST https://app.servicelocal.ai/api/public/v1/checkouts \
  -H "X-ServiceLocal-Key: $SERVICELOCAL_API_KEY" \
  -H "Idempotency-Key: lead-8812-growth" \
  -H "Content-Type: application/json" \
  -d '{
    "offerKeys": ["<offerKey from step 2>"],
    "offerVersion": 2,
    "buyer": { "email": "[email protected]", "name": "Sam Lee", "phone": "+15551234567" },
    "successUrl": "https://youragency.com/thanks",
    "cancelUrl": "https://youragency.com/plans"
  }'
  1. Act on the webhook. Add an endpoint under Settings › Funnels & API › Webhooks. When client.activated arrives and its signature checks out, the client has paid and is live.

Keys and responses

WhatValue
Base URLhttps://app.servicelocal.ai
API keySettings › Funnels & API › API keys (owner only). Header X-ServiceLocal-Key: sl_live_…
Intake keySettings › Funnels & API › Leads. Header X-Intake-Key: …
Success body{ "status": "success", "data": … }
Error body{ "status": "error", "error": { "code": "<code>", "message": "…" } }. Validation errors add error.details
Key and rate-limit refusalsFlat: { "status": "error", "code": "UNAUTHORIZED", "message": "…" } (401) or "code": "RATE_LIMITED" (429)

Send leads

Send each lead from your form or funnel tool. ServiceLocal creates the lead under your agency and starts building their demo site under your brand.

POST https://app.servicelocal.ai/api/public/agency-intake
X-Intake-Key: <your intake key>
Content-Type: application/json
{
  "businessName": "Sunrise Plumbing",
  "email": "[email protected]",
  "phone": "+1 555 123 4567",
  "trade": "plumbing",
  "websiteUrl": "sunriseplumbing.com"
}
FieldRequiredWhat it is
businessNameYesThe lead's company name
emailYesThe lead's email: the demo goes here
phoneYesThe lead's phone
tradeNoThe service line, like plumbing
websiteUrlNoTheir current site: the demo builder reads it

GoHighLevel: in a workflow, add a Custom Webhook action, method POST, the URL above, a header X-Intake-Key with your key, and map your form fields to the body.

Sell your plans

Your plans are the ones you create under Pricing › Plans. Clients pay you directly, on your own connected Stripe account. Two things must be true before anything sells: your agency takes payments (Billing › Getting paid), or checkouts answer 409 agency_cannot_sell; and your own ServiceLocal plan is paid and active (Billing), or they answer 409 agency_subscription_required. A free trial makes demos but cannot sell.

Buy links live on your own domain, so they appear once one is connected under Settings › Domains. Then every active plan has one: open the plan's Buy link under Pricing › Plans and copy the link or the button HTML. The page asks for the buyer's email, name and phone, opens a checkout, and the buyer becomes your client. Links from the console arrive on your webhooks with empty metadata.

List your plans

GET /api/public/v1/offers?channel=api
X-ServiceLocal-Key: <your API key>

channel=api is required. The answer is data.offers, your active plans:

{
  "offerKey": "7c1e2a90-4b1d-4f0e-9a51-0c6a1d2f3b44",
  "version": 2,
  "kind": "client_plan",
  "merchant": "agency",
  "name": "Growth",
  "price": { "unit": "money", "currency": "usd", "cents": 29900 },
  "interval": "month",
  "setupFee": null,
  "firstPayment": { "unit": "money", "currency": "usd", "cents": 29900 },
  "includedMonthlyCredits": 5000,
  "perClientFee": null,
  "sheet": {
    "kind": "client_plan",
    "modules": [
      { "module": "website", "included": true },
      { "module": "booking", "included": true },
      { "module": "receptionist", "included": false },
      { "module": "web_assistant", "included": true }
    ]
  }
}

Start a checkout

POST /api/public/v1/checkouts
X-ServiceLocal-Key: <your API key>
Idempotency-Key: <8 to 200 characters, unique per sale attempt>
Content-Type: application/json
{
  "offerKeys": ["7c1e2a90-4b1d-4f0e-9a51-0c6a1d2f3b44"],
  "offerVersion": 2,
  "buyer": { "email": "[email protected]", "name": "Sam Lee", "phone": "+15551234567" },
  "successUrl": "https://youragency.com/thanks",
  "cancelUrl": "https://youragency.com/plans",
  "metadata": { "campaign": "spring", "contact_id": "abc123" }
}

The answer is 201 with data.checkoutId and data.url (the Stripe Checkout page). Redirect the buyer to url.

Retries are safe with the same Idempotency-Key:

Read a checkout back:

GET /api/public/v1/checkouts/<checkoutId>

data holds checkoutId, status (open, complete or expired) and clientId, which is set once the client has paid and is live.

Webhooks

Add up to 5 endpoints under Settings › Funnels & API › Webhooks. Each one gets every event and its own signing secret, shown once. The endpoint must be a public URL; use https.

EventWhen
client.activatedA client paid their first plan and is live
subscription.canceledA client's plan ended
{
  "event": "client.activated",
  "eventId": "6f0b6c1e-2d0a-4c55-9a7e-3d1f4b8e2a10",
  "occurredAt": "2026-11-05T10:00:00.000Z",
  "agencyId": "a1b2c3d4-…",
  "client": { "tenantId": "e5f6a7b8-…", "name": "Sunrise Plumbing", "ownerEmail": "[email protected]" },
  "plan": { "offerKey": "7c1e2a90-…", "version": 2, "name": "Growth", "amountCents": 29900, "currency": "usd", "interval": "month" },
  "stripe": { "subscriptionId": "sub_1Qx…" },
  "metadata": { "campaign": "spring", "contact_id": "abc123" }
}

How to receive them:

import crypto from 'node:crypto';

export function verifyServiceLocal(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1 ?? '', 'hex');
  const want = Buffer.from(expected, 'hex');
  return given.length === want.length && crypto.timingSafeEqual(given, want);
}

Example: a Node funnel server

import express from 'express';
import { verifyServiceLocal } from './verify.js';

const API = 'https://app.servicelocal.ai/api/public/v1';
const headers = { 'X-ServiceLocal-Key': process.env.SERVICELOCAL_API_KEY, 'Content-Type': 'application/json' };
const app = express();

app.get('/plans', async (_req, res) => {
  const answer = await fetch(`${API}/offers?channel=api`, { headers }).then((r) => r.json());
  res.json(answer.data.offers);
});

app.post('/buy', express.json(), async (req, res) => {
  // attemptId: a fresh id the page makes on each Buy click (crypto.randomUUID()) and resends only on a retry.
  const { attemptId, offerKey, offerVersion, email, name, phone, contactId } = req.body;
  const answer = await fetch(`${API}/checkouts`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': attemptId },
    body: JSON.stringify({
      offerKeys: [offerKey], offerVersion,
      buyer: { email, name, phone },
      successUrl: 'https://youragency.com/thanks', cancelUrl: 'https://youragency.com/plans',
      metadata: { contact_id: contactId },
    }),
  }).then((r) => r.json());
  if (answer.status !== 'success') return res.status(409).json(answer.error ?? answer);
  res.json({ url: answer.data.url });
});

app.post('/servicelocal-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-ServiceLocal-Signature') ?? '';
  if (!verifyServiceLocal(req.body.toString('utf8'), signature, process.env.SERVICELOCAL_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body.toString('utf8'));
  // Drop an eventId you have seen, then update the contact named in event.metadata.contact_id.
  res.sendStatus(200);
});

app.listen(3000);

Errors

HTTPCodeMeaning
400VALIDATION_ERRORThe body failed validation: see details
400idempotency_key_requiredA checkout without an Idempotency-Key header
401UNAUTHORIZEDKey missing, wrong or revoked
404offer_not_foundUnknown or retired plan: read the offers again
404checkout_not_foundNot a checkout this key started
409offer_version_changedThe price changed: read the offers again and show the new price
409agency_cannot_sellYour agency cannot take payments right now: check Billing › Getting paid
409agency_subscription_requiredYour own ServiceLocal plan is not paid and active: activate it under Billing
409buyer_already_clientThis email already pays you: send the buyer to sign in and manage their plan
409offer_not_on_key_accountThis key cannot sell that offer, or used an API it has no access to (payment links)
409idempotency_key_reusedThat Idempotency-Key was used for a different checkout
409open_payment_link_requiredThe retried checkout has closed: read it first
409checkout_not_createdThe first request never reached Stripe: use a new Idempotency-Key
429RATE_LIMITEDToo many requests from one IP. Per minute: offers 120, checkouts 60

For AI agents

Paste this into your AI agent (Claude, ChatGPT, Cursor or similar), then describe your funnel:

Build a sales funnel for my agency on ServiceLocal.
Read this first: https://servicelocal.ai/developers/agency-api.md

Keys are in server env vars, never in browser code:
  SERVICELOCAL_API_KEY     sells my plans
  SERVICELOCAL_INTAKE_KEY  sends my leads

My funnel: [who it is for, what it sells, which pages, which tools]

Follow the guide: list my plans, start checkouts on the server,
and act only on signed webhooks.

Not available yet

Not availableUse today instead
Payment links through the APIThe buy link on each plan, or a checkout per buyer
Creating or repricing plans through the APIPricing › Plans in your console
Payment on your own page (Stripe Payment Element)A hosted checkout or a buy link
Promotion codes, coupons, and refunds through the APINone. Codes work today only on ServiceLocal's own offers, not on an agency's plans