Follow Up Boss provides a simple REST API that allows developers to integrate their applications quickly. API is in active development and will be extended to provide more functionality while keeping it backwards compatible.

API Endpoint URL has the following structure, https://api.followupboss.com/v1/people

• https:// - HTTPS is required for security, HTTP will not work.
• api.followupboss.com - API hostname, always the same.
• v1 - API version, currently v1 is the only version.
• people - resource name in plural, such as people, notes, etc.

Looking for code examples? You can find Bash and PHP examples here

Simply email us at api@followupboss.com and we'll help you to get started or answer any question you might have.

If you integrate with Follow Up Boss we ask that you register your system. Once registered, you will be provided with a unique system key. Every request to the API should include the registered 'X-System' and 'X-System-Key' headers.

On first glance system may look similar to the "source" attribute sent along with lead notification events. The difference is that the lead source describes the brand or marketing name a broker uses for a lead source, and system describes the system used.

Every user in Follow Up Boss has a unique API Key that can be obtained from "Admin" -> "API" screen. External applications use API Key to get authenticated and read/update data in Follow Up Boss on the user's behalf.

Authentication is done with HTTP Basic Authentication over HTTPS. Use API Key as the username and leave the password blank (or you can put any value as password if your HTTP client requires it).

Follow Up Boss API is available via HTTPS only. This ensures that API Key is always encrypted during transmission. API Key provides the same privileges as the user's login credentials and should be handled securely.

API key has the same access level as the user whom the key belongs to. For example, agent's API key allows access only to people assigned to that agent while broker's API key allows access to all people in the account.

Permission Levels

• Owner: The account owner has access to everything in the account.
• Admin (Broker): An admin has most access to everything but they can not access Webhooks.
• Agent: An agent only has access to the contacts they are assigned to, or are a collaborator on. They will also have restricted access to things like action plans.
• Lender: Similar to an agent, a Lender only has access to contacts they are assigned to, or are a collaborator on, and they will have even fewer actions they can do than an agent.

Rate limiting will soon be enforced by the API.

Rate Limiting is based on a sliding 10 second window.

Within every response from our API, the following headers indicate the current limit, remaining requests before reaching the limit, the window of time evaluated in seconds, and the context.

Additionally, we indicate the context for which this rate limit applies. Any given endpoint will only be subject to one context. For example /v1/events may have an 'events' context, for which there may be stricter limits, requests to this endpoint would not affect other contexts, such as 'global'.

Systems that exhaust their limits will receive a 429 (Too Many Requests) response code, and a Retry-After header.

If you receive a 429 response code, your request was not processed and you will have to retry the request. The Retry-After header indicates how long to wait (in seconds) before retrying (or sending any other request).

Here are the contexts available and their limits as they are currently set. We will make changes as needed, so always check the headers for the most up-to-date values applicable to your requests.

If you are making requests without a valid X-System-Key header, the allowed rate is much lower:

NOTE: submitting new leads with a POST request to /v1/events is currently not rate limited, as we want to ensure no leads are lost. However, this may change in the future, so please make sure your system can re-submit a lead if it receives a 429 response.

You may in some cases also receive a 429 (Too Many Requests) even if you still have requests remaining. Perhaps because we temporarily have less capacity than usual, or we notice an exceptionally high number of requests from a particular IP address or system.

Please make sure your system respects the 429 header even if X-RateLimit-Remaining shows you should have requests remaining.

If an API request is successful, the API returns a HTTP status code appropriate for that request (e.g. 200 OK, 201 Created, 204 No Content).

if the server cannot process your request, the API typically returns a 4xx HTTP status code. For example:

• 403 Forbidden: You do not have access to this resource
• 404 Not Found: This resource does not exist, it may have been deleted or it may have never existed at all.
• 429 Too Many Requests: This request was rate limited, see the Rate Limiting section for more info.
• 400 Bad Request: We could not process this request. Typically this means the endpoint does not support the request you made, perhaps the parameters supplied with the request were incorrect, or something else about the request was malformed. The response should be valid JSON, with an "errorMessage" key which explains why the request could not be processed.

If the server is unable to process a request because it is overloaded, or because we made a programming error, you may see a 5xx HTTP status code (e.g. 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout, etc..).

Systems should make sure to implement throttling logic when receiving a 5xx HTTP Status code.

A common technique is to use Truncated exponential backoff

Example:

1. Make a request to Follow Up Boss API.
2. If the request fails, wait 1 + random_number_milliseconds seconds and retry the request.
3. If the request fails, wait 2 + random_number_milliseconds seconds and retry the request.
4. If the request fails, wait 4 + random_number_milliseconds seconds and retry the request.

And so on, up to a maximum_backoff time.

Continue waiting and retrying up to some maximum number of retries, but do not increase the wait period between retries.

where:

• The wait time is min(((2^n)+random_number_milliseconds), maximum_backoff), with n incremented by 1 for each iteration (request).
• random_number_milliseconds is a random number of milliseconds less than or equal to 1000. This helps to avoid cases where many clients get synchronized by some situation and all retry at once, sending requests in synchronized waves. The value of random_number_milliseconds is recalculated after each retry request.
• maximum_backoff is typically 32 or 64 seconds. The appropriate value depends on the use case.

It's okay to continue retrying once you reach the maximum_backoff time. Retries after this point do not need to continue increasing backoff time. For example, if a client uses an maximum_backoff time of 64 seconds, then after reaching this value, the client can retry every 64 seconds. At some point, clients should be prevented from retrying infinitely.

How long clients should wait between retries and how many times they should retry depends on your use case and network conditions.

Follow Up Boss API uses JSON encoding. When sending POST and PUT requests, request body should contain JSON-encoded data to create or update a resource. We also recommend including a header indicating content type of the request body: Content-Type: application/json.

For example, to update first name on a person with ID = 123 you can use the following request:

Likewise, response body is also encoded using JSON format.

Please note the date format in the example above: 2012-04-23T02:23:11Z. It's ISO 8601 standard, we use that format for all date and time values.

Time is always expressed in UTC time zone.

On success for new resources, you will get a "201 Created" or "200 OK" response if an existing resource was updated.

In general, response bodies for creating or updating resources will be in the same format as returned by a GET request for that resource.

When listing resources in a collection you can filter results by specifying search conditions as query parameters in the URL. For example, to search person by email address you can use this:

You can specify multiple search criteria and they will be combined using "AND" logic. For example, to find past clients that came from Zillow use this request:

List methods that return a collection of resources are paginated using offset and limit query parameters. Default limit value is 10 and default offset value is 0. Resources are returned in reverse order by id, so by default, API returns the last 10 resources in a collection. To obtain the next page of 10 resources specify offset=10 query parameter, then offset=20 and so on. You can increase the number of resources returned at a time using the limit parameter. Maximum value for the limit parameter is 100.

For example, to return the third page of most recently created people with 25 people per page:

Response contains "_metadata" section that includes total number of records available and pagination parameters used in the request:

Why use descending order? It makes it easier to retrieve the most recent records, for example to get 5 most recently created people use:

The best way to send leads into Follow Up Boss from an IDX website, real estate portal, your custom website or any other lead source is to use event notifications endpoint (Example, POST /v1/events).

Advantages of using this method include:

• Avoid creating duplicates, Follow Up Boss will automatically search for existing contact and update it.
• Event information (inquiry, viewed property, saved property as a favorite, etc) is recorded and shown in contact history and dashboard.
• Agent is notified about new lead via email / text message.
• Action plan is applied to the lead (if configured and when particular event types are used).
• Correct agent is assigned as per Lead Flow screen.
• Automatic search for social profiles.

Email Templates need a way to incorporate contact information into the final email that is to be sent. The way we do it is by unique identifiable text within an email template.

For example if your email template looked like: Hello %contact_name%. And your contact's name was William Riker, the result of the email template would be Hello William Riker.

The following merge fields can be obtained with a call to /v1/users/:id.

The following merge fields can be obtained with a call to /v1/people/:id.

The following merge fields can be obtained with a call to /v1/events/:personId

The inquiry address merge field is intended to be used as the subject of an email without any surrounding text, it should perform some basic substitutions in case there is no inquiry event for the person:

If property.street is empty and %source_name% is not, then: %inquiry_address% is "Your property inquiry from %source_name%"

If both property.street is empty and %source_name% are empty, then: %inquiry_address% is "Your property inquiry"

Use the Events API, not the People API to send all data from an IDX website to Follow Up Boss

Make sure all these events are sent to Follow Up Boss:

• Registration
• Inquiry
• Saved Property
• Viewed Property
• Property Search
• Visited Open House
• All forms on the website send data to Follow Up Boss

Additional items to include

• Include system field in all API calls to identify your system vs other lead providers
• Set source field to be the domain of the website without "www.", e.g. mywebsite.com
• API key is secure and not exposed in browser
• PPC data ("campaign" section)
• Link to lead in your backend system if applicable ("sourceUrl" field)

Webhooks post JSON to a specific URL every time an event listed below is triggered. Webhooks remove the need to poll for changes. When an event occurs--for example a person is assigned to a different agent, this event will be sent to your system as an HTTP POST to the webhook URL configured for the peopleUpdated event.

Examples of what you might use webhooks for:

• Update a person's name in your database when it is changed in Follow Up Boss
• Update a person's email or phone in your database when it is changed in Follow Up Boss
• Re-assign a person in your system when it is re-assigned in Follow Up Boss
• When a Zillow lead is added to Follow Up Boss you add it to your IDX search website

Supported webhook events

People

peopleCreated, peopleUpdated, peopleDeleted, peopleTagsCreated, peopleStageUpdated

peopleUpdated
One or more of the following fields are updated in a person:

• Name name firstName lastName
• Emails emails
• Phone Numbers phones
• Address addresses
• Price price
• Background background
• Assigned Agent assignedTo assignedUserId
• Assigned Lender assignedLenderName assignedLenderId
• Contacted contacted
• Stage stage stageId
• Lead Source source sourceUrl
• Tags tags

peopleDeleted
When a person is deleted all associated data is deleted as well e.g. notes, calls, text messages, etc. There will not be any delete events triggered for these resources when this happens.

JSON sample of event notification:

{
    "eventId": "64d0ad74-3aab-4b30-89c9-7337398cf8b4",
    "eventCreated": "2016-12-12T15:19:21+00:00",
    "event": "peopleCreated",
    "resourceIds": [1234,5322,29456],
    "uri": "https://api.followupboss.com/v1/people?id=1234,5322,29456"
}

peopleTagsCreated
When a tag is added to a person, the payload will include the name of the new tag. Multiple tags and person ids may be included. Note: The webhook will fire regardless of whether a tag was previously removed and re-added to a contact.

JSON sample of event notification:

{
    "eventId": "e8d9f150-5dac-4c53-8c0f-06560dc4ec08",
    "eventCreated": "2019-07-01T17:22:28+00:00",
    "event": "peopleTagsCreated",
    "resourceIds": [
        40773,
        40772
    ],
    "uri": "https://api.followupboss.com/v1/people?id=40773,40772",
    "data": {
        "tags": [
            "Kingsbury"
        ]
    }
}

peopleStageUpdated
When a person's stage is updated, the payload will include the name of the new stage.

JSON sample of event notification:

{
    "eventId": "e0ac086a-879a-4d8b-869a-fe53151e34f4",
    "eventCreated": "2019-07-01T17:12:32+00:00",
    "event": "peopleStageUpdated",
    "resourceIds": [
        40942
    ],
    "uri": "https://api.followupboss.com/v1/people?id=40942",
    "data": {
        "stage": "Free Trial"
    }
}

Notes

notesCreated, notesUpdated, notesDeleted

Emails

emailsCreated, emailsUpdated, emailsDeleted

Tasks

tasksCreated, tasksUpdated, tasksDeleted

Appointments

appointmentsCreated
This webhook only fires when an appointment created in Follow Up Boss, not when we sync appointments created in Google Calendar.

Text Messages

textMessagesCreated, textMessagesUpdated, textMessagesDeleted

Calls

callsCreated, callsUpdated, callsDeleted

Email Marketing Events

emEventsOpened
People open an email marketing email.

emEventsClicked
People click a link in an email marketing email.

emEventsUnsubscribed
People unsubscribe from email marketing emails.

Deals

dealsCreated, dealsUpdated, dealsDeleted

People Events

eventsCreated
People perform an action on your IDX website, e.g. view a property.

Registering a webhook

Send an HTTPS POST to the /v1/webhooks endpoint with a JSON object that specifies the event and callback URL.

The response will be JSON encoded representation of the webhook created.

See /webhooks for detailed documentation of the /v1/webhooks endpoint.

Receiving webhook events

Create an endpoint that accepts HTTP POST requests at the URL specified in the registered webhook. The body of the request will be JSON encoded. To acknowledge the receipt, your endpoint should respond within 10 seconds with a 2XX HTTP status code such as 200 or 204. Any other response will indicate that you did not receive the webhook and we will continue to retry at various intervals for up to 8 hours.

For example, the endpoint at https://acmeleadprovider.com/callbacks/fub/peoplecreated would receive the following HTTP POST when a person is created in Follow Up Boss:

Handling webhook events

The endpoint that handles events should do an HTTP GET to the resource URI specified in the event. Then compare the response to the local database and apply changes that are found. The response format for the people endpoint can be found at /people

See the code samples below for handling webhook events:

Requesting webhook events

Individual webhook events can be requested from /webhookEvents/:id . This can useful if your system was unavailable to receive events for some reason and there are events older than 3 days that were missed.

Webhook best practices

Setup your system to de-couple receiving webhook events from fetching the resource specified in the event. For example--the web service that receives events could record the event in a local database table. A separate backend process could be created to monitor this table for new rows and fetch the resource specified in the event. By separating these, the web service that handles receiving webhooks is doing less and is, therefore less likely to fail. The process that processes the events can contain all the complex logic to fetch the resource from Follow Up Boss, reconcile with your local system and mark the event as processed in the table. If this process fails or breaks it can be debugged independently of the web service. The table that stores events is the source of truth as to what webhook events have been received and processed.

Debugging webhooks

Since webhooks require a publicly accessible URL to function they can be hard to test from your local machine. It is recommended that you use a service like Request Bin when you are developing your webhook endpoints.

Common webhook mistakes

• Make sure you provide the correct URL when registering a webhook. You can list all your webhooks at the /webhooks endpoint.
• Make sure the webhook endpoint is returning a 2XX HTTP status code such as 200
• When registering a webhook make sure you are setting the X-System header. You can also include the system param in the query string or post data. For example: https://api.followupboss.com/v1/webhooks/32?system=AcmeCo
• If you are setting up webhooks for multiple Follow Up Boss accounts be sure to include a Follow Up Boss account identifier in the registered webhook URLs. Your webhook URLs should look like this: https://acmeLeadProvider.com/callbacks/fub/account12/peopleCreated or https://acmeLeadProvider.com/callbacks/fub/peopleCreated?fub_account=12

You can notify Follow Up Boss when certain events occur on your website or system, for example user fills out a registration form on an IDX website, sends an inquiry about a property or submits Contact Us form. This is the only correct way to send leads and their activity to Follow Up Boss from an IDX website, real estate portal, your custom website or any other lead source.

New leads created by POST /v1/events will only trigger action plans if they are of the following types: "Registration", "Seller Inquiry", "Property Inquiry", "General Inquiry" "Visited Open House"

NOTE: when making a GET request to /v1/people, not all available fields are included in the response by default. Use the ?fields= argument to request exactly the fields you need. You can use ?fields=allFields during development to get all fields returned, but this may return very large responses so please update this to specify exactly the fields you need for your production deployments.

People response fields

Important Note

The best way to send leads into Follow Up Boss from an IDX website, real estate portal, your custom website or any other lead source is to use event notifications, i.e. POST /v1/events. Advantages of using this method include:

• Avoid creating duplicates, Follow Up Boss will automatically search for existing contact and update it;
• Event information (inquiry, viewed property, saved property as a favorite, etc) is recorded and shown in contact history and dashboard;
• Agent is notified about new lead via email / text message;
• Action plan is applied to the lead (if configured);
• Correct agent is assigned as per Lead Flow screen;
• Automatic search for social profiles;

Custom Fields

If the account has custom fields defined you can also set these when adding a person. You can use the customFields endpoint to see which custom fields are available in the current account.

Custom Fields

If the account has custom fields defined you can also set these when updating a person. You can use the customFields endpoint to see which custom fields are available in the current account.

To delete a custom field value on a person, set its value to null: