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, externalId, createdAt, lastResponseAt, lastUpdatedAt, archivedAt, doNotContact.
• View fields — the view's curated list.
• Reserved fields — never returned, regardless of view.

Detecting changes

lastUpdatedAt bumps on every write that changes the row. Three patterns:

• Webhooks — subscribe to user.updated; each delivery names the changedFields and carries the projected user. See Webhooks.
• Incremental sync — ?updatedSince=<iso>&sortBy=lastUpdatedAt&sortOrder=asc, follow pagination.nextCursor until null. Subtract 60 s from your watermark each run to catch in-flight writes.
• Full audit — sortBy=id&sortOrder=asc&limit=200, follow nextCursor. Every user in the view appears exactly once.

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

Fixed-window, per-token, not per-IP. Two independent counters:

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). On exceed: 429 with Retry-After. Please honor it. Higher limits for a token are available on request.

Idempotency

Send an Idempotency-Key header (≤128 chars, unique per token) on POST /users, POST /users/batch, PUT /users/by-recipient/:recipientId and DELETE /users/:userId. A retry with the same key and body returns the stored response with Idempotent-Replayed: true instead of running again. Keys expire after 24 hours.

• 409 idempotency_in_progress — the first request is still running.
• 422 idempotency_key_reused — same key, different body.
• Responses of 5xx are not stored; retry freely.

Errors

JSON body with error, often message and a machine-readable code, 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:

For user.created / user.updated, data adds changedFields (empty on create) and user — the user projected through the subscription's view, exactly as GET /users would return it to a token on that view. A subscription with no view gets the always-returned fields plus the changed values. Other events keep the identifying fields only.

When the change came through the API the envelope carries origin ({ kind, tokenId, tokenPrefix }), so a mirror can skip events its own writes produced.

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.

Manage via API

Same subscriptions as the dashboard, scoped to the token's agent. Requires webhooks:read / webhooks:write.

Deploy scripts: GET first, then PATCH the existing subscription rather than POSTing a duplicate.