Follow Up Boss API Query Parameters: A Complete Guide

What is the Follow Up Boss API and who uses it?

Follow Up Boss (owned by Zillow Group) exposes a REST API that lets developers read and write CRM data — contacts, notes, events, deal stages, action plans, and more. Teams use the API to sync leads from outside sources, push data into business-intelligence dashboards, trigger automations in other tools, and build custom reporting pipelines.

Every API call is authenticated with HTTP Basic Auth. Your API key goes in the username field; leave the password blank. Keys are available under Admin → My Account in the FUB dashboard.

What are the core query parameters for the People (Contacts) endpoint?

The GET /v1/people endpoint is the most commonly used. It returns a paginated list of contacts and accepts the parameters below.

How does pagination work in the Follow Up Boss API?

FUB uses offset-based pagination rather than cursor-based pagination. To walk through all contacts, increment offset by your limit value on each request until the response returns fewer records than limit (which signals the last page).

A typical loop in JavaScript looks like this:

const limit = 100;
let offset = 0;
let people = [];

while (true) {
  const res = await fetch(
    `https://api.followupboss.com/v1/people?limit=${limit}&offset=${offset}`,
    { headers: { Authorization: 'Basic ' + btoa(API_KEY + ':') } }
  );
  const { people: batch } = await res.json();
  people = people.concat(batch);
  if (batch.length < limit) break;
  offset += limit;
}

Keep requests under 100 records per page. The API enforces a rate limit; respect the Retry-After header if you receive a 429 response.

How do you filter contacts by date in Follow Up Boss?

Use updatedSince (ISO 8601, e.g., 2026-06-01T00:00:00Z) to pull only contacts modified after a given point in time. This is the correct approach for incremental sync — fetch all contacts once, then on subsequent runs pass the timestamp of your last successful sync as updatedSince.

There is no createdSince parameter on the People endpoint directly, but you can sort by created descending and stop when you reach a record older than your cutoff. For precise creation-date filtering, the GET /v1/events endpoint (which logs every lead-creation event) is often more reliable.

What parameters does the Events endpoint support?

The GET /v1/events endpoint tracks every activity in FUB — calls, texts, emails, notes, and status changes. Useful query parameters include:

• personId — Return events for a single contact
• type — Filter by event type (Call, Text Message, Email, Note)
• since — ISO 8601 timestamp; return events after this point
• limit / offset — Same pagination pattern as People

Combining personId with type=Call gives you a complete call history for a lead without pulling all event types.

How do you filter by assigned agent (assignedTo)?

Pass the FUB user ID of the agent as the assignedTo integer. To find user IDs, call GET /v1/users — this returns all users in your account including their numeric IDs. You can chain filters: ?assignedTo=42&stage=Active%20Buyer&limit=100 returns the first 100 active-buyer contacts assigned to agent 42.

Can you filter on custom fields via the API?

Standard FUB custom fields (text, number, dropdown) are stored as top-level properties on the person object once you define them in the FUB admin. You can filter by them using customField[fieldName]=value syntax on supported endpoints — but support varies by field type. For complex filtering across multiple custom fields, smart lists (saved searches in the FUB UI) can be read back via GET /v1/smartlists/{id}/people, which inherits all the same limit, offset, and sort parameters.

What are the Deals endpoint parameters?

The GET /v1/deals endpoint returns pipeline deals. Key parameters:

Common mistakes to avoid with Follow Up Boss API query parameters

• Not URL-encoding values. Stage names with spaces (e.g., Active Buyer) must be encoded as Active%20Buyer or your request will silently return no filter.
• Skipping pagination on large databases. Defaulting to limit=20 and offset=0 on every call means you are only ever seeing the first 20 records. Always paginate to completion on sync jobs.
• Ignoring rate limits. FUB enforces per-minute rate limits per API key. Build in exponential backoff when you receive a 429.
• Mixing ISO 8601 formats. The API expects UTC timestamps (Z suffix or explicit offset). A bare date like 2026-06-01 may be rejected or interpreted as midnight local time on the server.

How does Follow Up Ace use the FUB API internally?

Follow Up Ace (the AI layer that runs inside Follow Up Boss) uses the FUB API extensively to read contact data and write Ace Score fields back. The Ace Trove — which powers nightly contact analysis — uses date-filtered incremental syncs so only recently-updated contacts are reprocessed, keeping API usage efficient. If you are building your own integration alongside Ace, using updatedSince on incremental runs is the same pattern.

The Agentic surface includes 215 verified MCP tools that wrap FUB API operations in natural language — so rather than hand-crafting query strings, agents like Claude can ask "give me all hot leads assigned to Sarah updated this week" and Ace translates that to the correct API call automatically. See our API integration guide and FUB learning guides for more context.

Step-by-step: building an efficient contact sync with query parameters

1. Bootstrap sync. Call GET /v1/people?limit=100&sort=created&direction=asc&offset=0, paginate until done, and save the last updated timestamp from the final record.
2. Incremental syncs. On subsequent runs, call GET /v1/people?limit=100&updatedSince=<last_timestamp>. This returns only changed records.
3. Filter by agent for per-agent dashboards. Add &assignedTo=<userId> to scope to a single agent's pipeline.
4. Pull events for activity history. For each changed contact, optionally call GET /v1/events?personId=<id>&since=<last_timestamp> to get recent activity.
5. Respect the rate limit. Add a 200ms delay between pages on large syncs, and retry with backoff on 429 errors.

Following this pattern keeps your integration current without hammering the API or pulling redundant data. For a deeper look at webhook-based real-time updates (which complement query-based pulls), see our real-time API integration guide.