Follow Up Boss User Management API Guide

Auth method: HTTP Basic Auth (API key as username, empty password)

Setup steps

1. Log in to Follow Up Boss as an admin.
2. Navigate to Admin > API in account settings.
3. Generate or copy the API key.
4. Use the API key as the HTTP Basic Auth username with an empty password in all requests.
5. Include the header: Authorization: Basic base64(apiKey:)

List Users

• Method: GET
• URL: https://api.followupboss.com/v1/users
• Watch out for: Returns only users belonging to the authenticated API key's account. Deleted/deactivated users may not appear.

Request example

GET /v1/users?limit=20&offset=0
Authorization: Basic <base64(apiKey:)>

Response example

{
  "users": [
    {"id": 1, "name": "Jane Smith", "email": "jane@example.com", "role": "Admin"}
  ],
  "_metadata": {"total": 45, "limit": 20, "offset": 0}
}

Get User by ID

• Method: GET
• URL: https://api.followupboss.com/v1/users/{id}
• Watch out for: Returns 404 if the user ID does not exist in the account.

Request example

GET /v1/users/42
Authorization: Basic <base64(apiKey:)>

Response example

{
  "id": 42,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "Agent",
  "isAdmin": false
}

Create User

• Method: POST
• URL: https://api.followupboss.com/v1/users
• Watch out for: Creating a user counts against the account's seat limit. Duplicate email addresses return a 422 error.

Request example

POST /v1/users
Content-Type: application/json

{"name": "Alice Brown", "email": "alice@example.com", "role": "Agent"}

Response example

{
  "id": 99,
  "name": "Alice Brown",
  "email": "alice@example.com",
  "role": "Agent",
  "created": "2024-01-15T10:00:00Z"
}

Update User

• Method: PUT
• URL: https://api.followupboss.com/v1/users/{id}
• Watch out for: Uses PUT (full or partial update accepted in practice). Omitting fields may not clear them; verify behavior against current docs.

Request example

PUT /v1/users/99
Content-Type: application/json

{"name": "Alice B. Brown", "phone": "+15551234567"}

Response example

{
  "id": 99,
  "name": "Alice B. Brown",
  "phone": "+15551234567",
  "updated": "2024-01-16T08:30:00Z"
}

Delete User

• Method: DELETE
• URL: https://api.followupboss.com/v1/users/{id}
• Watch out for: Deleting a user is irreversible via API. Leads assigned to the deleted user may need reassignment beforehand.

Request example

DELETE /v1/users/99
Authorization: Basic <base64(apiKey:)>

Response example

HTTP 204 No Content

List Teams

• Method: GET
• URL: https://api.followupboss.com/v1/teams
• Watch out for: Team membership is managed at the user level via teamId; there is no separate team-member assignment endpoint documented.

Request example

GET /v1/teams
Authorization: Basic <base64(apiKey:)>

Response example

{
  "teams": [
    {"id": 5, "name": "East Coast Team", "memberCount": 8}
  ]
}

• Rate limits: Follow Up Boss enforces rate limits per API key. The official docs state a limit of 1,000 requests per 10 minutes per API key.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When the limit is exceeded the API returns HTTP 429. The docs mention rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) but do not explicitly document a Retry-After header.
• Pagination method: offset
• Default page size: 20
• Max page size: 100
• Pagination pointer: offset / limit

• Webhooks available: Yes
• Webhook notes: Follow Up Boss supports outbound webhooks that fire on CRM events. Webhooks are configured in the admin UI or via the API under /webhooks. They deliver JSON payloads via HTTP POST to a configured URL.
• Alternative event strategy: No dedicated user-lifecycle webhook events (e.g., user.created, user.deactivated) are documented. Polling the /users endpoint is the recommended approach for user-change detection.
• Webhook events: lead.created, lead.updated, lead.deleted, appointment.created, appointment.updated, note.created, task.created, task.updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Follow Up Boss does not offer a native SCIM 2.0 endpoint.
• No IdP connectors (Okta, Entra ID, Google Workspace, OneLogin) are officially supported for SCIM provisioning.
• User provisioning must be performed via the REST API or manually through the admin UI.

Three integration scenarios are well-supported by the documented endpoints.

First, provisioning a new agent to a team: GET /v1/teams to retrieve the target teamId, then POST /v1/users with role='Agent' and the resolved teamId;

a 201 response confirms the record.

Second, deprovisioning a departing user: list their assigned leads via GET /v1/people?userId={id}, issue individual PUT /v1/people/{leadId} calls to reassign each lead's ownerId, then DELETE /v1/users/{id}

there is no bulk-reassign endpoint, so large lead counts require batching within the rate limit.

Third, syncing from an external HR system: paginate GET /v1/users exhausting _metadata.total, diff against the HR roster by email, then POST/PUT/DELETE accordingly;

because no user-lifecycle webhooks exist, this sync must be scheduled (e.g., nightly polling).

Provision a new agent and assign to a team

1. GET /v1/teams to retrieve the target team ID.
2. POST /v1/users with name, email, role='Agent', and teamId set to the retrieved team ID.
3. Verify the response returns HTTP 201 with the new user's id.
4. Optionally GET /v1/users/{id} to confirm the user record is correct.

Watch out for: If the account has reached its seat limit, the POST will fail. Verify seat availability in the admin UI or by checking the current user count against the plan limit before provisioning.

Deprovision a departing user and reassign their leads

1. GET /v1/users to identify the departing user's id.
2. GET /v1/people?userId={id} to list leads assigned to that user.
3. PUT /v1/people/{leadId} for each lead to reassign ownerId to a replacement agent.
4. DELETE /v1/users/{id} to remove the user from the account.

Watch out for: Lead reassignment must be done before deletion; there is no bulk-reassign endpoint, so this may require multiple PUT calls. Deletion is permanent and cannot be undone via API.

Sync user roster from an external HR system

1. GET /v1/users?limit=100&offset=0 (paginate until _metadata.total is exhausted) to build a current user list.
2. Compare against the HR system's active employee list by email.
3. POST /v1/users for net-new employees not present in Follow Up Boss.
4. PUT /v1/users/{id} to update changed fields (name, phone, role) for existing users.
5. DELETE /v1/users/{id} for users present in Follow Up Boss but terminated in the HR system.

Watch out for: No webhook fires on user changes, so this sync must be scheduled (e.g., nightly). Rate limit of 1,000 req/10 min may require batching for large rosters.

The absence of SCIM and user-lifecycle webhooks is the primary integration trap. Without SCIM, every IdP connector that expects a /scim/v2/Users endpoint will fail silently or require a middleware translation layer, adding surface area to the identity graph that must be maintained independently.

Without user.created or user.deactivated webhook events, any downstream system relying on real-time deprovisioning signals must fall back to polling - introducing a latency window where a terminated user's access may persist until the next scheduled sync cycle. Additionally, the PUT /v1/users/{id} endpoint uses full-or-partial update semantics that are not precisely documented;

field-clearing behavior should be validated against live responses before relying on it in automated workflows. Creating users via API consumes paid seats, so provisioning logic must gate on seat availability or handle 4xx errors gracefully to avoid silent provisioning failures.