Skip to content

SalesmanSites Website Integration Guide

This guide is for developers building an individual salesperson's website. It explains how the site reads that salesperson's published inventory from SalesmanSites and sends shopper inquiries back to their Leads.

The short version: every website connection has its own keys. A key only ever returns one salesperson's published inventory, and only accepts inquiries for that salesperson. Drafts, archived vehicles, internal notes, and customer information are never available through this API.

Contents

  1. How the pieces fit together
  2. Getting your keys
  3. Authentication and allowed origins
  4. Endpoints
  5. Field reference
  6. Submitting inquiries correctly
  7. Keeping inventory current
  8. Errors
  9. Example code
  10. Launch checklist

1. How the pieces fit together

Part What it does
SalesmanSites app The salesperson adds vehicles, photos, and descriptions, publishes listings, and manages leads.
Integration API (/api/v1) Gives a connected website read access to that salesperson's published listings and accepts inquiries.
The salesperson's website Displays the inventory, and posts shopper inquiries to the API. Built separately (this is what you're building).

A typical flow:

  1. The salesperson publishes a vehicle in SalesmanSites.
  2. Your site requests GET /api/v1/vehicles and shows it.
  3. A shopper fills out "Is this available?" on the vehicle page.
  4. Your site sends POST /api/v1/leads. When you get a 201, the inquiry is saved in the salesperson's Leads and they are notified.
  5. The salesperson marks the vehicle Sold. It disappears from status=available results, and its detail endpoint returns availability: "sold".

Base URL

https://salesmansites.com/api/v1

When running SalesmanSites locally, the base URL is http://localhost:3000/api/v1.

2. Getting your keys

The salesperson (or SalesmanSites support) connects the website in My Website inside the app by entering the site's domain (for example jordansells.com). That creates a website connection with:

Credential Format Where it may be used
Publishable key ss_pub_… Browser code. Safe to embed in your site's JavaScript. Browser requests are only accepted from the connection's allowed origins.
Secret key ss_sec_… Server-side only (SSR, serverless functions, build scripts). Never ship it to a browser. Shown once when created; can be rotated.
Webhook signing secret whsec_… Your webhook endpoint, to verify events came from SalesmanSites.

Both keys are scoped to the same single connection, which belongs to exactly one salesperson account. Rotating a key stops the old one immediately.

3. Authentication and allowed origins

Send the key in the Authorization header:

Authorization: Bearer ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

X-Api-Key: <key> is also accepted. For simple GET requests from a browser, a publishable key may be passed as ?key=ss_pub_…. Secret keys are never accepted in URLs.

Allowed origins. Browser requests that use a publishable key must come from one of the connection's allowed origins:

  • https://<domain> and https://www.<domain> are allowed automatically.
  • Additional origins (a staging site, a preview deployment) can be added in My Website → Allowed origins.
  • For local development connections such as localhost:4001, http://localhost:4001 is allowed.

Requests from other origins are rejected with 403 origin_not_allowed, and the attempt is recorded for SalesmanSites support. Secret-key requests are server-to-server and don't receive CORS headers.

Rate limits (per connection):

Endpoint Publishable key Secret key
GET /site, GET /vehicles 120 / minute per visitor IP 600 / minute
GET /vehicles/{ref} 240 / minute per visitor IP 1,200 / minute
POST /leads 6 / minute per visitor IP 120 / minute

When a limit is reached you'll get 429 rate_limited with a Retry-After header (seconds).

4. Endpoints

GET /site

The connected salesperson's public profile and an inventory summary. Use it for your header, About section, and contact details.

curl https://salesmansites.com/api/v1/site \
  -H "Authorization: Bearer ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
{
  "data": {
    "connection": { "domain": "jordansells.com", "name": "Main website" },
    "salesperson": {
      "name": "Jordan Reyes",
      "title": "Sales Consultant",
      "bio": "Helping folks around Austin find the right truck.",
      "phone": "(512) 555-0142",
      "email": "jordan@example.com",
      "photo_url": "https://salesmansites.com/media/avatars/…/avatar-lq3k2.webp",
      "dealership": {
        "name": "Example Motors",
        "address": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "phone": "(512) 555-0100",
        "website": "https://examplemotors.com/",
        "hours": "Mon–Sat 9am–8pm
Sun closed",
        "brands": ["Ford", "Toyota"]
      }
    },
    "inventory": { "available_count": 12, "sold_count": 4, "last_updated_at": "2026-11-19T15:04:11.000Z" }
  }
}

GET /vehicles

Published inventory for this salesperson. Drafts and archived vehicles are never included.

Query parameter Values Default
status available, sold, all (available + sold) available
sort newest, updated, price_asc, price_desc, mileage_asc, year_desc newest
page 1 or more 1
per_page 1–100 24
make Exact make, e.g. Ford —
body_style Exact body style, e.g. SUV —
min_price, max_price Whole dollars —
curl "https://salesmansites.com/api/v1/vehicles?sort=newest&per_page=12" \
  -H "Authorization: Bearer ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"
{
  "data": [
    {
      "id": "cmi6u0xk40003ab12cd34ef56",
      "slug": "2021-ford-f-150-xlt-4ef56",
      "availability": "available",
      "title": "2021 Ford F-150 XLT",
      "year": 2021,
      "make": "Ford",
      "model": "F-150",
      "trim": "XLT",
      "condition": "used",
      "condition_label": "Used",
      "vin": "1FTEW1EP5MFA00000",
      "stock_number": "P2291",
      "price": 38900,
      "price_display": "$38,900",
      "mileage": 41200,
      "mileage_display": "41,200 mi",
      "body_style": "Pickup Truck",
      "exterior_color": "Carbonized Gray",
      "interior_color": "Black",
      "transmission": "10-Speed Automatic",
      "drivetrain": "4WD",
      "engine": "3.5L V6 Turbo",
      "fuel_type": "Gasoline",
      "doors": 4,
      "features": ["Tow package", "Backup camera", "Apple CarPlay"],
      "description": "This 2021 Ford F-150 XLT is ready for its next owner…",
      "cover_photo": { "id": "…", "position": 0, "width": 2048, "height": 1365, "alt": "2021 Ford F-150 XLT photo 1", "urls": { "thumb": "…", "medium": "…", "large": "…" } },
      "photos": [ { "id": "…", "position": 0, "width": 2048, "height": 1365, "alt": "…", "urls": { "thumb": "…", "medium": "…", "large": "…" } } ],
      "published_at": "2026-11-18T19:22:40.000Z",
      "updated_at": "2026-11-19T15:04:11.000Z",
      "sold_at": null
    }
  ],
  "meta": { "status": "available", "sort": "newest", "page": 1, "per_page": 12, "total": 1, "total_pages": 1, "generated_at": "2026-11-19T15:10:00.000Z" }
}

GET /vehicles/{id or slug}

One vehicle, with photos in the salesperson's chosen order (photos[0] is the cover).

  • Published vehicles return availability: "available".
  • Sold vehicles still return 200, with availability: "sold" and price: null, so an old link can show "This vehicle has been sold" instead of an error.
  • Drafts, archived or deleted vehicles, and vehicles that belong to anyone else return 404 vehicle_not_found.
curl https://salesmansites.com/api/v1/vehicles/2021-ford-f-150-xlt-4ef56 \
  -H "Authorization: Bearer ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Prefer linking with the slug (it's stable once a vehicle is first published). The id always works too.

POST /leads

Submit a shopper inquiry. See section 6 before you build your form.

curl https://salesmansites.com/api/v1/leads \
  -H "Authorization: Bearer ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a0e-6b7f-4b8f-9a5d-2f0f6c1d9e11" \
  -d '{
    "name": "Sam Carter",
    "phone": "(512) 555-0199",
    "email": "sam@example.com",
    "message": "Is this still available? Could I see it Saturday?",
    "type": "availability",
    "vehicle_id": "2021-ford-f-150-xlt-4ef56",
    "page_url": "https://jordansells.com/inventory/2021-ford-f-150-xlt-4ef56",
    "referrer": "https://www.instagram.com/",
    "utm": { "source": "instagram", "medium": "social", "campaign": "november-trucks" },
    "honeypot": "",
    "form_started_at": 1795120000000
  }'

201 Created — the inquiry was saved:

{ "data": { "id": "cmi6u3a1b0009ab12cd34ef56", "status": "received", "received_at": "2026-11-19T15:12:03.000Z", "duplicate": false } }

200 OK with "duplicate": true (and header Idempotent-Replayed: true) — this exact submission was already saved earlier. Treat it as success.

5. Field reference

Vehicle

Field Type Notes
id string Permanent identifier.
slug string URL-friendly identifier, stable after first publish.
availability "available" | "sold" Only these two values are ever returned.
title string Year, make, model, and trim combined.
year, make, model, trim number / string / string / string | null
condition "used" | "certified" | "new" | null condition_label is the display text.
vin, stock_number string | null
price integer | null Whole US dollars. null when sold.
price_display string Formatted price, or "Sold".
mileage integer | null Miles. mileage_display is formatted.
body_style, exterior_color, interior_color, transmission, drivetrain, engine, fuel_type string | null Free text set by the salesperson (often from VIN decoding).
doors integer | null
features string[] In the salesperson's order.
description string Plain text; may contain line breaks. Escape it when rendering.
cover_photo Photo | null Same as photos[0].
photos Photo[] Ordered.
published_at, updated_at, sold_at ISO 8601 string | null updated_at changes on any edit, including photo changes.

Photo

Field Type Notes
urls.thumb URL Up to 480 px on the long edge. Use for grids and thumbnails.
urls.medium URL Up to 1280 px. Use for listing pages.
urls.large URL Up to 2048 px. Use for full-screen galleries.
width, height integer Dimensions of the large version (use for aspect ratio).
alt string Default alt text.

Photo URLs are permanent, publicly cacheable WebP images with location metadata removed. Hotlinking them is expected.

Inquiry (request body for POST /leads)

Field Required Notes
name Yes 1–100 characters.
phone / email At least one Phone needs 10–15 digits. Email must be valid.
message No Up to 2,000 characters.
type No availability, test_drive, pricing, trade_in, general. Defaults to availability when vehicle_id is set, otherwise general.
vehicle_id No A vehicle id or slug from this connection. Must be available or sold.
preferred_contact No phone, text, or email.
page_url No The page the form was on. Shown to the salesperson.
referrer No document.referrer, if you have it.
utm No { source, medium, campaign, term, content }.
referral_code No Any referral or promo code your site captured.
submission_id Recommended Idempotency key (8–100 characters). The Idempotency-Key header takes precedence if both are sent.
honeypot Recommended Value of a hidden field humans never fill in. Send "".
form_started_at Recommended When the form was rendered (epoch milliseconds or ISO string).

6. Submitting inquiries correctly

Only show a confirmation after a 201 or 200. Any 4xx or 5xx response means nothing was saved. Keep the shopper's input in the form and show the error.

Always send an idempotency key. Generate one UUID per form render (not per click) and send it as Idempotency-Key. If the network drops and you retry, the same key returns the original receipt instead of creating a second lead. SalesmanSites also recognizes identical resubmissions within 10 minutes as duplicates.

Include the spam signals. Add a hidden honeypot input and record when the form was shown:

<div style="position:absolute;left:-9999px" aria-hidden="true">
  <label>Leave this empty <input name="company_website" tabindex="-1" autocomplete="off"></label>
</div>

Submissions that fill the honeypot, arrive within about 2.5 seconds of the form appearing, or are stuffed with links are quarantined: they get a normal-looking 201 (so bots learn nothing), but they never reach the salesperson's Leads.

Returning shoppers. If a shopper with the same email or phone inquires again, the new inquiry is added to their existing lead (with full history) rather than creating a duplicate. No action is needed on your side.

Retries. Retry 429 (after Retry-After), 500, 502, 503, and network errors with the same idempotency key. Do not retry 400, 401, 403, 404, or 422 without changing something.

7. Keeping inventory current

Salespeople change prices, swap photos, and mark vehicles sold throughout the day. Pick the approach that fits your site:

Server-rendered or dynamic sites — fetch on each request, or cache for up to 60 seconds. Every list and detail response includes an ETag. Send it back as If-None-Match and you'll get a 304 Not Modified with no body when nothing changed, so frequent checks are cheap.

Static sites (built ahead of time) — rebuild when SalesmanSites tells you something changed. Configure a webhook URL in My Website → Webhook, then trigger your rebuild (or revalidate the affected page) when an event arrives. As a safety net, also rebuild on a schedule (for example, every 15 minutes).

Rules that always apply

  • Remove anything that no longer appears in GET /vehicles?status=available. Never show a vehicle as available from an old cache after its status changes.
  • Use updated_at to detect edits, and always re-read photos with the vehicle; photo order and cover can change.
  • If a vehicle detail request returns 404, take the page down (or redirect to your inventory page).
  • If it returns availability: "sold", show a sold notice and hide the price and inquiry form, or offer "See similar vehicles".

Webhooks

SalesmanSites POSTs JSON to your webhook URL:

{
  "id": "evt_8Kp3V0qLx2NwT7cZaR1y",
  "type": "vehicle.sold",
  "created_at": "2026-11-19T15:20:44.000Z",
  "data": { "vehicle_id": "cmi6u0xk40003ab12cd34ef56", "slug": "2021-ford-f-150-xlt-4ef56", "availability": "sold", "updated_at": "2026-11-19T15:20:44.000Z" }
}
Event Sent when
vehicle.published A vehicle becomes available (first publish, or relisted after being sold).
vehicle.updated A live (available or sold) vehicle's details, price, description, or photos change.
vehicle.sold A vehicle is marked sold.
vehicle.unpublished A vehicle is moved back to draft, archived, or deleted. Remove it from your site.
profile.updated The salesperson changed their public profile or photo.
ping The salesperson pressed "Send test event".

Events are notifications, not data: re-fetch the vehicle (or the whole list) when you receive one. Delivery is attempted twice with a 5-second timeout; respond with any 2xx quickly. Failures are visible to the salesperson and to SalesmanSites support.

Verify every webhook. Each request has an X-SalesmanSites-Signature header like t=1795121244,v1=5f2c…. Compute HMAC-SHA256(secret, "<t>.<raw request body>") as hex and compare it to v1 in constant time. Reject requests where t is more than 5 minutes old.

import crypto from "node:crypto";

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

8. Errors

Every error uses the same shape:

{ "error": { "code": "validation_failed", "message": "Some fields need attention. Nothing was saved.", "fields": { "phone": "Provide a phone number or email address." } } }
Status Code Meaning
400 invalid_json, invalid_parameter Malformed body or query parameter.
401 missing_api_key, invalid_api_key No key, or the key isn't valid (it may have been rotated).
403 origin_not_allowed Browser request from an origin that isn't allowed for this key.
403 connection_disabled The website connection was disabled by the salesperson or support.
403 account_inactive The salesperson's account isn't active. Show your site's fallback content.
404 vehicle_not_found Not published, deleted, or not this salesperson's vehicle.
413 payload_too_large Request body over the limit.
422 validation_failed See fields for per-field messages. Nothing was saved.
422 vehicle_not_found vehicle_id on an inquiry doesn't match an available vehicle. Nothing was saved.
429 rate_limited Slow down; see Retry-After.
500 server_error Nothing was saved. Retry with the same idempotency key.

Each response carries an X-Request-Id header. Include it when contacting support.

9. Example code

Browser (publishable key)

<div id="inventory"></div>
<script>
  const API = "https://salesmansites.com/api/v1";
  const KEY = "ss_pub_XXXXXXXXXXXXXXXXXXXXXXXXXXXX";

  async function loadInventory() {
    const res = await fetch(`${API}/vehicles?per_page=24`, { headers: { Authorization: `Bearer ${KEY}` } });
    if (!res.ok) throw new Error("Inventory unavailable");
    const { data } = await res.json();
    const el = document.getElementById("inventory");
    el.replaceChildren(
      ...data.map((v) => {
        const card = document.createElement("a");
        card.href = `/inventory/${v.slug}`;
        const img = document.createElement("img");
        img.src = v.cover_photo?.urls.medium ?? "/placeholder.jpg";
        img.alt = v.cover_photo?.alt ?? v.title;
        const title = document.createElement("h3");
        title.textContent = v.title; // textContent avoids HTML injection
        const price = document.createElement("p");
        price.textContent = `${v.price_display} · ${v.mileage_display}`;
        card.append(img, title, price);
        return card;
      }),
    );
  }

  const formStartedAt = Date.now();
  const submissionId = crypto.randomUUID();

  async function sendInquiry(form, vehicleSlug) {
    const body = {
      name: form.name.value,
      phone: form.phone.value,
      email: form.email.value,
      message: form.message.value,
      type: "availability",
      vehicle_id: vehicleSlug,
      page_url: location.href,
      referrer: document.referrer || null,
      honeypot: form.company_website.value,
      form_started_at: formStartedAt,
    };
    const res = await fetch(`${API}/leads`, {
      method: "POST",
      headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json", "Idempotency-Key": submissionId },
      body: JSON.stringify(body),
    });
    const json = await res.json();
    if (res.status === 201 || res.status === 200) return { ok: true };
    return { ok: false, message: json.error?.message, fields: json.error?.fields ?? {} };
  }

  loadInventory();
</script>

Server (secret key, Node 18+)

const API = "https://salesmansites.com/api/v1";
const SECRET = process.env.SALESMANSITES_SECRET_KEY; // ss_sec_… — never expose to the browser

let cache = { etag: null, vehicles: [] };

export async function getInventory() {
  const res = await fetch(`${API}/vehicles?per_page=100`, {
    headers: { Authorization: `Bearer ${SECRET}`, ...(cache.etag ? { "If-None-Match": cache.etag } : {}) },
  });
  if (res.status === 304) return cache.vehicles;
  if (!res.ok) throw new Error(`SalesmanSites responded ${res.status}`);
  const { data } = await res.json();
  cache = { etag: res.headers.get("etag"), vehicles: data };
  return data;
}

export async function forwardInquiry(input, idempotencyKey) {
  const res = await fetch(`${API}/leads`, {
    method: "POST",
    headers: { Authorization: `Bearer ${SECRET}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
    body: JSON.stringify(input),
  });
  const json = await res.json();
  return { saved: res.status === 201 || res.status === 200, status: res.status, error: json.error };
}

10. Launch checklist

  • Inventory pages use GET /vehicles?status=available and remove vehicles that disappear from it.
  • Vehicle detail pages handle availability: "sold" and 404.
  • Photos use thumb / medium / large appropriately, with width/height to reserve space.
  • Descriptions and all other text are escaped when rendered.
  • Inquiry form sends an Idempotency-Key, honeypot, form_started_at, and page_url.
  • The confirmation message only appears after a 201 or 200.
  • Validation errors from fields are shown next to the right inputs, and the shopper's input is kept.
  • The secret key (if used) lives only in server environment variables.
  • Production and staging origins are listed in My Website → Allowed origins.
  • Webhook signatures are verified (if you use webhooks), and a scheduled refresh runs as a safety net.
  • A test inquiry from the live site shows up in the salesperson's Leads.