API Reference

Authentication

Bearer token in the Authorization header. Tokens are 64 chars prefixed ext_agent_.

Create a token

1. Log in to app.teamsquared.ai.
2. Open Settings → API Tokens.
3. Click New token, name it, pick the scopes and bound view, then create.
4. Copy the full token immediately — see the warning below.

Scopes

Tokens carry one or more case-sensitive resource:permission scopes that gate which endpoints they can call. Scopes are picked in the UI when the token is created (Settings → API Tokens → New token) and can't be changed afterward — issue a new token to widen or narrow access. Missing scope → 403.

Data model & views

Similar to a spreadsheet, the data model is flexible. Views (shown in the left sidebar of the dashboard below) define a filtered subset of users with limited data for a specific purpose. Every API token is bound to a view; the view determines which fields are returned on reads and which fields callers can filter or sort by.

What reads return

• Always returned — id, recipientId, createdAt, lastResponseAt, lastUpdatedAt.
• View fields — the view's curated list.
• Reserved fields — never returned, regardless of view.

Detecting changes

lastUpdatedAt bumps on every mutation. Two patterns:

• Poll-and-diff — track the last lastUpdatedAt per user; skip when unchanged.
• Incremental sync — pass ?updatedSince=<iso>, then save the max lastUpdatedAt from the batch for next loop.

const TOKEN = process.env.TOKEN;
const API = 'https://api.teamsquared.ai/api/v1';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// Stand-in for the ERP's own table. The ERP — not the API —
// owns the record of when it last saved each user.
const erp = {
  records: new Map(),
  save(u) {
    this.records.set(u.id, {
      recipientId: u.recipientId,
      name: u.name ?? null,
      savedLastUpdatedAt: u.lastUpdatedAt,
    });
  },
  newestSavedAt() {
    return [...this.records.values()]
      .map((r) => r.savedLastUpdatedAt).sort().at(-1);
  },
};

async function initialSync() {
  const limit = 20;
  let offset = 0;
  while (true) {
    const url = new URL(`${API}/users`);
    url.searchParams.set('limit', String(limit));
    url.searchParams.set('offset', String(offset));
    const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });
    const { users, pagination } = await res.json();

    for (const u of users) {
      erp.save(u);
      const mres = await fetch(`${API}/users/${u.id}/chat-messages?limit=100`,
        { headers: { Authorization: `Bearer ${TOKEN}` } });
      const { messages } = await mres.json();
      console.log(JSON.stringify({ user: u, chatMessages: messages }, null, 2));
      await sleep(1000); // stay under 60 req/min
    }

    if (!pagination.hasMore) break;
    offset += limit;
    await sleep(1000);
  }
}

// In production, fired by a webhook subscription on user.updated:
// the ERP exposes an HTTP handler, the API POSTs the change, and
// the handler calls periodicSync(). Polling is a fallback.
async function periodicSync() {
  const since = erp.newestSavedAt();
  const url = new URL(`${API}/users`);
  url.searchParams.set('updatedSince', since);
  url.searchParams.set('limit', '200');
  const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });
  const { users } = await res.json();
  const changed = [];
  for (const u of users) {
    const existing = erp.records.get(u.id);
    if (existing && existing.savedLastUpdatedAt === u.lastUpdatedAt) continue;
    erp.save(u);
    changed.push(u);
  }
  console.log(JSON.stringify({ changed }, null, 2));
}

await initialSync();
await periodicSync();

Rate limiting

60 req/min/token, fixed-window. Per-token, not per-IP.

On exceed: 429 with Retry-After. Please honor it.

Errors

JSON body with error, often message, plus context (recipientId, fieldName, …).

Create a subscription

Settings → Webhooks → Create Webhook. Set:

• Name — internal label.
• Destination URL — HTTPS endpoint that will receive deliveries.
• Events — one or more (see below).
• User Types — which user types fire this webhook. Defaults to Live.

The signing secret (whsec_…) is shown once. Copy it immediately — it can't be retrieved later.

Row ⋯ menu: Send test event, Pause / Resume, Delete.

Events & user types

Fires only when event matches and the user's type is in the subscription's User Types list.

Payload

POST, Content-Type: application/json, three signing headers:

data is intentionally minimal — fetch full state from the API if you need it.

Receiving & verifying

Drop-in Node.js / Express handler. Verifies the signature in constant time, then processes the event.

• Use express.raw() — JSON-parsing changes byte order and breaks the signature.
• Compare with timingSafeEqual to avoid timing attacks.
• Return 2xx within 10 s. Defer slow work.

Retries & testing

Any 2xx acknowledges (body ignored). Anything else retries with exponential backoff: 30 s → 1 min → 2 min → 4 min → … capped at 24 h, up to 8 attempts. After that the event stays Failed.

Each delivery times out after 10 seconds.

Send test event (row ⋯ menu) fires a synthetic webhook.test envelope synchronously and reports the response status in a toast.