followupboss

TypeScript SDK for the Follow Up Boss API.

Install

npm install @nikomart/followupboss

Configure

Follow Up Boss API-key authentication uses HTTP Basic auth with the API key as the username and a blank password. Registered integrations must also send the X-System and X-System-Key identification headers.

import { FollowUpBossClient } from "@nikomart/followupboss";

const fub = new FollowUpBossClient({
  apiKey: process.env.FUB_API_KEY!,
  system: process.env.FUB_SYSTEM!,
  systemKey: process.env.FUB_SYSTEM_KEY!,
});

The default API base URL is https://api.followupboss.com/v1. You can override it for tests or proxies:

const fub = new FollowUpBossClient({
  apiKey: "api-key",
  system: "ExampleApp",
  systemKey: "system-key",
  baseUrl: "https://api.followupboss.com/v1",
});

Send Leads and Events

Follow Up Boss recommends sending new leads through POST /events, not by directly creating people through POST /people. Event creation lets Follow Up Boss deduplicate contacts, record inquiry history, notify agents, and apply configured lead flows.

await fub.events.create({
  source: "Website",
  system: "Custom IDX",
  type: "Inquiry",
  message: "I would like more information.",
  person: {
    firstName: "Ada",
    lastName: "Lovelace",
    emails: [{ value: "[email protected]", type: "home" }],
  },
});

Search People

const page = await fub.people.list({
  limit: 25,
  email: "[email protected]",
  fields: ["firstName", "lastName", "emails"],
});

for (const person of page.people) {
  console.log(person.id, person.firstName, person.lastName);
}

Paginate

Collection resources expose both list() and paginate(). The iterator follows the Follow Up Boss _metadata.next cursor.

for await (const person of fub.people.paginate({ limit: 100, tags: ["Buyer"] })) {
  console.log(person.id);
}

Common Resources

await fub.notes.create({
  personId: 123,
  subject: "Follow up",
  body: "Call tomorrow morning.",
});

await fub.tasks.update(456, {
  personId: 123,
  name: "Call Ada",
  type: "Call",
  isCompleted: false,
});

const users = await fub.users.list({ email: "[email protected]" });
const stages = await fub.stages.list({ sort: "orderWeight" });

For endpoints without a convenience wrapper, use request():

const result = await fub.request("GET", "/customFields");

Errors and Rate Limits

Non-2xx responses throw FollowUpBossApiError. The error includes the status, parsed body, response headers, and rate-limit metadata from Follow Up Boss headers when present.

import { FollowUpBossApiError } from "@nikomart/followupboss";

try {
  await fub.people.list();
} catch (error) {
  if (error instanceof FollowUpBossApiError) {
    console.error(error.status, error.body, error.rateLimit);
  }
}

429 Too Many Requests responses can be retried by enabling retry options. Retry-After is respected.

const fub = new FollowUpBossClient({
  apiKey: process.env.FUB_API_KEY!,
  system: process.env.FUB_SYSTEM!,
  systemKey: process.env.FUB_SYSTEM_KEY!,
  retry: { maxRetries: 1 },
});

Development

npm install
npm run verify