How to Use API Docs for Follow Up Boss Integration

What is the Follow Up Boss API and what can it do?

The Follow Up Boss API is a RESTful HTTP interface that lets developers read and write data directly in the CRM — creating contacts, logging events, assigning tasks, and triggering automations — without clicking through the UI. Every action a human can take in Follow Up Boss has an API counterpart, which makes it the foundation of any serious integration.

Common use cases include:

• Pushing new leads from a website form or portal directly into FUB as contacts
• Syncing sold or under-contract status from your transaction management platform
• Logging call and text activity from a dialer like Kixie or Mojo
• Pulling contact lists into a BI tool or data warehouse for reporting
• Triggering smart drip campaigns the moment a lead's behavior changes

Where do I find the Follow Up Boss API documentation?

The official API reference lives at https://docs.followupboss.com. It documents every resource (People, Events, Deals, Tasks, Notes, Stages, Custom Fields, and more) with request/response examples and required field types. The docs are version-stable — Follow Up Boss maintains backward compatibility, so integrations built against v1 endpoints continue to work as the platform evolves.

A few sections worth bookmarking immediately:

• Authentication — where to generate and revoke API keys
• People — the primary contact object; most integrations start here
• Events — the activity feed that powers automations and action plans
• Webhooks — outbound push notifications when data changes
• Custom Fields — how to read and write non-standard contact properties

How does Follow Up Boss API authentication work?

FUB uses HTTP Basic Authentication. Your API key acts as the username; the password field is intentionally left blank. Every request must include an Authorization header or it will be rejected with a 401.

Step-by-step: setting up authentication

1. Generate your API key — log into Follow Up Boss, go to Admin > API, and copy your key. Treat it like a password; do not commit it to source control.
2. Base64-encode the credential — concatenate your key and a colon: API_KEY: (the colon is required even though there is no password), then base64-encode the result.
3. Add the header to every request:
   Authorization: Basic <base64-encoded-value>
Content-Type: application/json
4. Test with a simple GET — call GET https://api.followupboss.com/v1/people?limit=1 and confirm you receive a 200 with a contact object.

Most HTTP libraries abstract this for you. In Node.js with axios:

const axios = require('axios');

const response = await axios.get('https://api.followupboss.com/v1/people', {
  auth: { username: process.env.FUB_API_KEY, password: '' },
  params: { limit: 10 }
});

What are the most important Follow Up Boss API endpoints?

The API exposes dozens of resources, but the majority of integrations use a small core set. Here is a plain-English reference for the ones you will call most often.

How do I create or update a contact using the Follow Up Boss API?

Creating a lead is a single POST to /v1/people. If FUB detects a matching email or phone it merges the record rather than creating a duplicate — a behavior you can control with the dedupe parameter.

Steps to create a contact

1. Build a JSON body with at minimum firstName, lastName, and at least one of emails or phones (both are arrays of objects).
2. Include source (a string like "Website" or "Zillow") — this drives action plan assignments in FUB.
3. Add any custom field values under the customFields array using the field ID from GET /v1/customFields.
4. POST the body with your auth header.
5. Parse the response for the returned id — store it if you need to update the record later.

POST https://api.followupboss.com/v1/people
Authorization: Basic <token>
Content-Type: application/json

{
  "firstName": "Jordan",
  "lastName": "Rivera",
  "emails": [{ "value": "[email protected]", "type": "home" }],
  "phones": [{ "value": "5551234567", "type": "mobile" }],
  "source": "Website",
  "stage": "New Lead"
}

How do webhooks work in Follow Up Boss?

Webhooks let Follow Up Boss push data to your endpoint the moment something changes — a contact is created, a stage moves, a note is added — rather than you polling the API on a timer. For anything requiring real-time response (routing alerts, dialer triggers, AI analysis), webhooks are the right pattern.

How to register a webhook

1. Stand up an HTTPS endpoint that accepts POST requests and responds with a 200 within 5 seconds.
2. POST to /v1/webhooks with url (your endpoint), event (e.g., "personCreated"), and optionally a secret for payload signing.
3. FUB sends a test payload immediately — validate that your endpoint logs it correctly.
4. In production, verify the payload signature against your secret before processing.
5. Return a 200 quickly; do heavy work asynchronously (a background queue) so you never time out the delivery.

Available webhook events include personCreated, personUpdated, dealCreated, dealUpdated, taskCreated, noteCreated, and several others documented in the official reference.

What are the rate limits and pagination rules for the Follow Up Boss API?

FUB enforces rate limits to protect platform stability. The documented limit is 500 requests per minute per API key. Exceed it and you will receive a 429 response — implement exponential back-off with jitter rather than a fixed retry delay.

All list endpoints are paginated. Key parameters:

• limit — number of records per page (common max is 100)
• offset — zero-indexed position to start from
• Check the response _metadata object for total to know how many pages remain

For bulk exports (pulling your entire contact database), walk through pages sequentially rather than parallelizing requests — concurrent page fetches burn your rate limit quickly.

Common Follow Up Boss API integration patterns

Pattern 1 — Lead routing from a portal

A buyer submits an inquiry on Zillow or your IDX site. Your backend receives the form POST, maps fields to the FUB schema, and calls POST /v1/people with source: "Zillow". FUB's action plans fire automatically based on source.

Pattern 2 — Two-way sync with a transaction platform

Register a dealUpdated webhook so every stage change in your transaction management tool (e.g., under contract, closed) is mirrored as a deal update in FUB via PUT /v1/deals/{id}. This keeps the pipeline view accurate without manual entry.

Pattern 3 — AI layer via MCP connector

Rather than hand-rolling every API call in your codebase, you can expose Follow Up Boss to an AI assistant through Follow Up Ace's Model Context Protocol (MCP) connector. Follow Up Ace wires its 200+ MCP tools (verified: CORE CAPABILITIES (215 tools) in mcp-server/src/index.ts:206) over a single URL — Claude Desktop connects to https://followupace.com/mcp and ChatGPT plugins connect to the SSE endpoint at https://followupace.com/api/mcp/sse/ (verified: embed.js:4308-4309). This means an agent can search contacts, log notes, score leads, and trigger actions with natural language instead of raw HTTP calls.

See the Agentic page for a full breakdown of what those tools cover.

What should I know about Follow Up Boss custom fields via the API?

Custom fields let you store data that does not fit the standard contact schema — lead score values, neighborhood preferences, investor criteria, or any property-specific attribute. The workflow:

1. Call GET /v1/customFields to retrieve the list of field definitions, including each field's numeric id and type (text, number, dropdown, etc.).
2. When creating or updating a contact, pass custom field values as an array under customFields: [{ "id": 42, "value": "Investor" }].
3. When reading a contact, custom field values appear in the same customFields array on the response object.

If you are building an AI scoring system, custom fields are typically where computed scores get written back so they appear inside FUB's contact view. Follow Up Ace's Ace Trove uses this pattern for ACE lead scoring — writing engagement, intent, recency, quality, and velocity scores (verified fields: aceIntelligenceConfig.js:194-198) back to custom fields so every agent sees AI-generated scores directly in the CRM.

How do I handle errors from the Follow Up Boss API?

FUB returns standard HTTP status codes. Here is what each major code means in practice:

Best practices for a production Follow Up Boss integration

• Store API keys in environment variables, never hardcoded. Rotate them on team member departures.
• Use idempotent operations where possible. POST creates; PUT updates. If you are unsure whether a record exists, search first (GET /v1/people?email=...) and branch on the result.
• Queue background jobs for webhook processing. Accept the payload fast, acknowledge it, then process asynchronously. This prevents FUB retries from piling up when your processing is slow.
• Log every API call in development — request body, response status, and latency. FUB's API does not have a native request log, so yours is your only audit trail.
• Respect the rate limit budget. If you are syncing large contact lists, spread requests over time. At 500 requests/minute, a 10,000-contact import finishes in about 20 minutes at one record per call — batch where the API allows it.
• Handle deduplication explicitly. FUB deduplicates on email and phone, but your calling code should also track FUB contact IDs after creation so updates target the right record.
• Test against a staging FUB account before hitting production. Many brokerages keep a sandbox account with dummy contacts for exactly this purpose.

When does a direct API integration make sense vs. an AI connector?

Direct API integrations give you maximum control and are the right choice when you are building a custom data pipeline, connecting a proprietary internal tool, or writing business logic that needs to execute deterministically on every event.

An AI layer through MCP is the better path when the goal is natural-language access to CRM data — asking "which of my leads went cold this week?" and getting a ranked, actionable answer, rather than writing a query yourself. The two approaches are not mutually exclusive: many teams run a traditional API integration for data sync and add an MCP connector on top so agents and brokers can query and act on that data conversationally.

For teams on Follow Up Boss who want both layers, Follow Up Ace covers the AI side. The Ace Trove handles account-level scoring and analysis, the Agentic connector exposes 200+ CRM tools to Claude and ChatGPT, and the compliance layer scans outbound messages against Fair Housing rules before they send — all without you maintaining a custom integration.

Further reading

• MCP protocol: the technology making real estate AI actually useful
• Top 5 AI tools for Follow Up Boss integration
• Follow Up Ace guides and tutorials
• Follow Up Ace Agentic — natural language access to your CRM