Getting Started with Follow Up Boss
This page will help you get started with Follow Up Boss. You'll be up and running in a jiffy!
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.
Authentication
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.
Identification
If you integrate with Follow Up Boss we also ask you to identify your system using a 'X-System' header
X-System: AwesomeWebsiteBuilder
Or a "system" query argument:
GET /v1/calls?system=AwesomeWebsiteBuilder HTTP/1.1
Or a "system" key in a POST or PUT request:
POST /v1/events HTTP/1.1
Content-Type: application/json
...
{
"source": "MyAwesomeWebsite.com",
"system": "AwesomeSiteBuilder",
"person": { "firstName": "Mary", "lastName": "Mcmillan" },
...
}
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.
Requests and Responses
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:
PUT /v1/people/123 HTTP/1.1
Content-Type: application/json
...
{"firstName": "Mary"}
Likewise, response body is also encoded using JSON format.
{
"id": 123,
"created": "2012-04-23T02:23:11Z",
"updated": "2012-04-23T02:23:11Z",
"lastActivity": "2012-04-23T02:23:11Z",
"name": "Mary Mcmillan",
"firstName": "Mary",
"lastName": "Mcmillan",
"stage": "Lead",
"source": "Zillow",
}
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.
Searching
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:
GET /v1/people?email=john%40gmail.com
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:
GET /v1/people?stage=Past%20Client&source=Zillow
Pagination
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:
GET /v1/people?offset=50&limit=25
Response contains "_metadata" section that includes total number of records available and pagination parameters used in the request:
{
"_metadata": {
"collection": "people",
"offset": 50,
"limit": 25,
"total": 1000
},
"people": [
{
"id": 950,
"created": "2012-04-23T02:23:11Z",
},
{
"id": 949,
"created": "2012-04-22T02:23:11Z",
},
{
"id": 926,
"created": "2012-04-19T02:23:11Z",
}
]
}
Why use descending order? It makes it easier to retrieve the most recent records, for example to get 5 most recently created people use:
GET /v1/people?limit=5
Send in Leads
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.
Avoid sending leads through `POST /v1/people`.
Please do not use POST /v1/people
to send leads into FUB, it will only create a person but will not run any automations listed above. Instead, use POST /v1/events
.
Merge Fields
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
.
%agent_name%
name
%agent_first_name%
firstName
%agent_last_name%
lastName
%agent_email%
email
%agent_phone%
phone
The following merge fields can be obtained with a call to /v1/people/:id
.
%contact_name%
name
%contact_first_name%
firstName
%contact_last_name%
lastName
%contact_email%
emails[0].value
%contact_phone%
phones[0].value
%contact_address%
Combination of Fields:
addresses[0].street
addresses[0].city, addresses[0].code
%contact_street%
addresses[0].street
%contact_city%
addresses[0].city
%contact_state%
addresses[0].state
%contact_zipcode%
addresses[0].code
%contact_country%
addresses[0].country
`%source_name%
source
The following merge fields can be obtained with a call to /v1/events/:personId
%inquiry_address%
property.street
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"
IDX Integration
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
Use webhooks to be notified about events that happen in a Follow Up Boss account.
Require Owner Permissions
Only the owner has access to Webhooks.
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
Batch Updates
The following actions can result in a large number of people updates:
- Tags added or removed
- Stage updated
- Source updated
- Agent re-assigned
- Lender re-assigned
If one of these actions result in a large number of people being updated, the webhook event notification may be split into multiple requests.
Supported webhook events
People
peopleCreated
, peopleUpdated
, peopleDeleted
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"
}
Notes
notesCreated
, notesUpdated
, notesDeleted
Emails
emailsCreated
, emailsUpdated
, emailsDeleted
Tasks
tasksCreated
, tasksUpdated
, tasksDeleted
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.
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.
POST /v1/webhooks HTTP/1.1
Content-Type: application/json
X-System: AcmeLeadProvider
...
{
"event": "peopleCreated",
"url": "https://acmeLeadProvider.com/callbacks/fub/peopleCreated"
}
The response will be JSON encoded representation of the webhook created.
{
"id": 1244,
"status": "Active",
"event": "peopleCreated",
"url": "https://acmeLeadProvider.com/callbacks/fub/peopleCreated"
}
HTTPS Only
Callback URLs must be a secure endpoint
X-System Header is Required
The X-System HTTP Header is required for all requests to /v1/webhooks endpoints.
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 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 try the endpoint once an hour for up to 36 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:
POST /callbacks/fub/peoplecreated HTTP/1.1
Content-Type: application/json
...
{
"eventId": "152d60c0-79da-4018-a9af-28aec8a71c94",
"eventCreated": "2016-12-12T15:19:21+00:00",
"event": "peopleCreated",
"resourceIds": [1234,3244,3232],
"uri": "https://api.followupboss.com/v1/people?id=1234,3244,3232"
}
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:
const FUB_API_KEY = 'API Key for an Admin user in the Follow Up Boss Account';
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event_json = json_decode($input);
$event = $event_json->{'event'};
$resource_uri = $event_json->{'uri'};
// for peopleCreated and peopleUpdated events fetch the people
// at the resource URI
$curl = curl_init($resource_uri);
$headers = array(
'Authorization: Basic '. base64_encode(FUB_API_KEY . ":")
);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($curl);
curl_close($curl);
$remote_records = json_decode($result);
// Compare the remote record with your local record
http_response_code(200); // PHP 5.4 or greater
echo('OK');
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 Event Retries
If your system is unavailable or responds with an HTTP status code other than 2XX
such as 200
or 204
, FUB will retry every hour for up to 36 hours.
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 RequestBin 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 as200
- 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
orhttps://acmeLeadProvider.com/callbacks/fub/peopleCreated?fub_account=12
/events
Send in a lead or event related to a lead
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.
Important: 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", "Inquiry" and "Visited Open House".
"Inquiry" is a shorthand type for convenience, it will be automatically converted into "Property Inquiry" if property section is included in the request or "General Inquiry" otherwise.
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"
If you receive a 204 response with no response body, this indicates that the lead flow associated with this source has been archived and ignored.
/people
Search for contacts
People response fields
createdVia
This value indicates how this person was created. Possible values include "API", "Email Parsing", "Historic Email Parsing", "Import", and "Manually".
/people
Manually add a new contact
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;
Avoid sending leads through `POST /v1/people`.
Please do not use POST /v1/people
to send leads into FUB, it will only create a person but will not run any automations listed above. Instead, use POST /v1/events
.
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.
/people/:id
Update a contact
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:
{
"customBirthday": null
}
/calls
Search for calls
personId
may be 0
which indicates that this is a call from an unknown person to a number associated to the Follow Up Boss account.
/actionPlansPeople
List action plans applied to a particular person, or list people on a particular action plan
/templates
List all email templates
Templates use Merge Fields
Within templates, we need a way to modify the template with contact data. We call these Merge Fields. For more information, see Merge Fields.
/templates/:id
Retrieve a template by id, optionally merging fields
Templates use Merge Fields
Within templates, we need a way to modify the template with contact data. We call these Merge Fields. For more information, see Merge Fields.
/emEvents
List email marketing events
This endpoint returns information on marketing emails sent out and related statistics on opens, clicks, bounces, unsubscribes and spam reports. This includes information about email blasts and automated drip emails. Follow Up Boss has built-in email marketing functionality and also integrates with third-part email marketing tools, this API combines information about all those.
/emEvents
Notify Follow Up Boss about marketing emails sent, opens, clicks, bounces, unsubscribes and spam reports.
Use this endpoint to send information to Follow Up Boss about marketing emails sent out from your application and related events such as opens, clicks, bounces, unsubscribes and spam reports.
Before sending email marketing events you need to create an email campaign which represents a marketing email in your system. This could be a one-off email blast or automated drip email. Use POST /emCampaigns
endpoint to create an email campaign and save id field from the response - this is Follow Up Boss ID of the email campaign, then use that ID in the campaignId field when sending email marketing events to Follow Up Boss.
The following event types are supported:
delivered
- Email was sent out to a recipient.open
- Recipient opened the email.click
- Recipient clicked on a link in the email.bounced
- Email bounced, it means recipient's email server rejected the email. This is a generic bounce event, use it if your system doesn't distinguish between soft and hard bounces.soft-bounce
- Email bounced temporarily.hard-bounce
- Email bounced permanently.unsubscribe
- Recipient unsubscribed from further emails.spamreport
- Recipient reported email as spam.dropped
- Sending email wasn't attempted because of the previous history with recipient (bounced, unsubscribed, etc).
userId is an optional field that allows you to specify the ID of the user in Follow Up Boss that email was sent from. This is useful to display email correctly in Follow Up Boss including replacing merge fields with correct user name, email, etc. This field is optional and defaults to the current authenticated user (the user whose API key is being used to authenticate API request).
This endpoint allows sending multiple events in a batch request, this is especially useful for delivered
event type when you are sending out an email to a large number of recipients. You can send up to 1000 events per API request. When sending an email to a large number of recipients, we recommend breaking down the list of recipients into batches of 1000 and send each batch in a separate POST request to /v1/emEvents
endpoint.
/emCampaigns
List email marketing campaigns
Campaigns are marketing emails that are sent out to people in Follow Up Boss. These could be one-off email blasts, or automated drip emails. Follow Up Boss has built-in email marketing functionality and also integrates with third-part email marketing tools, this API combines information about all those. We use origin field to specify which email marketing tool was used for particular email campaign.
/emCampaigns
Create email marketing campaign
Use this endpoint to update Follow Up Boss about a new marketing email created in your system. This could be a one-off email blast or automated drip email. Set origin
field with the name of your system and originId
with your internal ID assigned to the new email.
You will get the id
field in the response - this is Follow Up Boss ID of the email campaign, save it in your system, you will need it later to post email marketing events - email sends, opens, clicks, bounces and unsubscribes.
You can use merge fields in the subject
and bodyHtml
:
%contact_name% - full name of the recipient
%contact_first_name% - first name of the recipient
%contact_last_name% - last name of the recipient
%contact_email% - email address of the recipient
%contact_phone% - phone number of the recipient
%contact_address% - full address of the recipient
%contact_street% - street address of the recipient
%contact_city% - city of the recipient
%contact_state% - state of the recipient
%contact_zipcode% - zip code of the recipient
%contact_country% - country of the recipient
%agent_name% - full name of the sender (user in FUB)
%agent_first_name% - first name of the sender (user in FUB)
%agent_last_name% - last name of the sender (user in FUB)
%agent_email% - email address of the sender (user in FUB)
%agent_phone% - phone number of the sender (user in FUB)
%inquiry_address% - address of the last property the recipient inquired about
%source_name% - lead source name of the recipient
Those merge fields will be replaced with their actual values when email is displayed in Follow Up Boss. If your system uses different convention for naming merge fields, replace them to match the fields listed above.
/emCampaigns/:id
Update email marketing campaign
Use this endpoint to update Follow Up Boss when a user edits marketing email in your system, for example changes email subject or body. This is more relevant for automated drip emails but may be applicable to one-off email blasts too when user saves email as a draft and later edits it before sending out.
/customFields
List all custom fields available in your account.
Custom fields can be used when adding an event, adding a person or updating a person. The account owner can add/edit/delete custom fields in Follow Up Boss, see using custom fields for more info.
/stages
Note about creating a new stage
When create a stage, the orderWeight for all stages will be recalculated.
/stages/:id
Note on updating
If the order weight changes, it will cause all other stages to recalculate the order.
If the isProtected
is true
, you can not update the name.
/webhooks
Get a list of webhoks
More about Webhooks
We have more details about webhooks in this article
/pipelines
Add a pipeline
Require owner permissions
Only the owner has access to create and modify pipelines.
/pipelines/:id
Update a pipeline
If you wish to modify the stages of a pipeline, you may do so by passing the id of the stage with your stage objects, as shown in the example above. Any stage objects that are missing ids will be created as new stages.
Require owner permissions
Only the owner has access to create and modify pipelines.