How to Add Local Marketing Features to Your SaaS

# 1. Create the client (primaryRepresentativeId is one of your team members: GET /api/v1/team/members)
curl -X POST https://ai.synup.com/api/v1/clients \
  -H "Authorization: Bearer $SYNUP_API_KEY" -H "Content-Type: application/json" \
  -d '{ "businessName": "Grove Street Dental", "primaryContactEmail": "owner@grovestreetdental.example", "primaryRepresentativeId": "TEAM_MEMBER_ID" }'

# 2. Create a location under it
curl -X POST https://ai.synup.com/api/v1/locations \
  -H "Authorization: Bearer $SYNUP_API_KEY" -H "Content-Type: application/json" \
  -d '{ "clientId": "CLIENT_ID", "name": "Grove Street Dental Mission", "countryIso": "US", "street": "88 Grove St", "city": "San Francisco", "stateIso": "CA", "postalCode": "94105", "phone": "+1 415 555 0142", "categoryName": "Dentist" }'

# 3. Get the Google connect link to show the customer
curl "https://ai.synup.com/api/v1/connections/google/connect-url?locationId=LOCATION_ID&returnUrl=/connected" \
  -H "Authorization: Bearer $SYNUP_API_KEY"

const API = "https://ai.synup.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.SYNUP_API_KEY}`,
  "Content-Type": "application/json",
};

async function call(path, init = {}) {
  const res = await fetch(`${API}${path}`, { ...init, headers });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
  return body.data;
}

async function onboard(tenant) {
  const { client } = await call("/clients", {
    method: "POST",
    body: JSON.stringify({
      businessName: tenant.name,
      primaryContactEmail: tenant.ownerEmail,
      primaryRepresentativeId: process.env.SYNUP_REP_ID,
    }),
  });

  const locations = [];
  for (const site of tenant.sites) {
    const { locationId } = await call("/locations", {
      method: "POST",
      body: JSON.stringify({
        clientId: client.id,
        name: site.name,
        countryIso: site.country,
        street: site.street,
        city: site.city,
        stateIso: site.state,
        postalCode: site.postalCode,
        phone: site.phone,
        categoryName: site.category,
      }),
    });
    await call(`/locations/${locationId}`, { method: "PATCH", body: JSON.stringify({ storeCode: site.id }) });
    const { url } = await call(`/connections/google/connect-url?locationId=${locationId}&returnUrl=/connected`);
    locations.push({ siteId: site.id, locationId, googleConnectUrl: url });
  }
  return { clientId: client.id, locations };
}

import os
import requests

API = "https://ai.synup.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SYNUP_API_KEY']}"}

def call(method, path, json=None, params=None):
    r = requests.request(method, f"{API}{path}", headers=HEADERS, json=json, params=params, timeout=30)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{r.status_code}: {body.get('error')}")
    return body["data"]

def onboard(tenant):
    client = call("POST", "/clients", {
        "businessName": tenant["name"],
        "primaryContactEmail": tenant["owner_email"],
        "primaryRepresentativeId": os.environ["SYNUP_REP_ID"],
    })["client"]

    locations = []
    for site in tenant["sites"]:
        location_id = call("POST", "/locations", {
            "clientId": client["id"], "name": site["name"], "countryIso": site["country"],
            "street": site["street"], "city": site["city"], "stateIso": site["state"],
            "postalCode": site["postal_code"], "phone": site["phone"], "categoryName": site["category"],
        })["locationId"]
        call("PATCH", f"/locations/{location_id}", {"storeCode": site["id"]})
        url = call("GET", "/connections/google/connect-url",
                   params={"locationId": location_id, "returnUrl": "/connected"})["url"]
        locations.append({"site_id": site["id"], "location_id": location_id, "google_connect_url": url})
    return {"client_id": client["id"], "locations": locations}

curl -X POST https://ai.synup.com/api/v1/posts \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "LOCATION_ID",
    "name": "September whitening offer",
    "postType": "offer",
    "platforms": ["google"],
    "messageGoogle": "20% off teeth whitening this September. Book online.",
    "ctaType": "book",
    "ctaUrl": "https://grovestreetdental.example/book",
    "eventTitle": "September whitening offer",
    "eventStartAt": "2026-09-01T09:00:00Z",
    "eventEndAt": "2026-09-30T17:00:00Z",
    "scheduledFor": "2026-09-01T09:00:00Z"
  }'

async function schedulePost(locationId, post) {
  const data = await call("/posts", { method: "POST", body: JSON.stringify({ locationId, ...post }) });
  // data.status: draft | scheduled | active | error
  // data.missingPlatforms: platforms with no connection; data.missingFields: what a draft still needs
  return data;
}

def schedule_post(location_id, post):
    data = call("POST", "/posts", {"locationId": location_id, **post})
    # data["status"]: draft | scheduled | active | error
    # data.get("missingPlatforms"), data.get("missingFields")
    return data

curl -X POST https://ai.synup.com/api/v1/seo/keywords \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "locationId": "LOCATION_ID", "keywords": ["dentist san francisco", "teeth whitening near me"], "gridSize": 5, "distanceKm": 1.5 }'

# later
curl "https://ai.synup.com/api/v1/seo/keywords?locationId=LOCATION_ID" \
  -H "Authorization: Bearer $SYNUP_API_KEY"

async function trackKeywords(locationId, keywords) {
  return call("/seo/keywords", {
    method: "POST",
    body: JSON.stringify({ locationId, keywords, gridSize: 5, distanceKm: 1.5 }),
  }); // { keywords: [{ id, keyword }] }; results land asynchronously
}

async function rankOverview(locationId) {
  return call(`/seo/keywords?locationId=${locationId}`); // keywords, months, grid, stats, statCards
}

def track_keywords(location_id, keywords):
    return call("POST", "/seo/keywords",
                {"locationId": location_id, "keywords": keywords, "gridSize": 5, "distanceKm": 1.5})

def rank_overview(location_id):
    return call("GET", "/seo/keywords", params={"locationId": location_id})