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.
Identification
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.
X-System: AwesomeWebsiteBuilder
X-System-Key: 560270f7914b5b4a5f4dc1793ebc2796On 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.
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).
Expired accounts and Authentication
Note that when an account expires, it enters a grace period, however the API key remains valid. Some endpoints may still be active so that there is no data loss (e.g. new lead POST to /v1/events) however the account may be in a locked down state and will receive a 403 Forbidden response for most other requests.
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
Rate limiting will soon be enforced by the API.
System Identification
Please ensure you have registered your system with Follow Up Boss as indicated in the Identification section.
If your system needs bigger limits, please email api@followupboss.com explaining your use case.
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'.
HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 156
X-RateLimit-Window: 10
X-RateLimit-Context: globalSystems 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).
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Window: 10
X-RateLimit-Context: global
Retry-After: 8Here 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.
POST.events
unlimited*
/v1/events
POST
events
20
/v1/events
GET
global
250
N/A
N/A
If you are making requests without a valid X-System-Key header, the allowed rate is much lower:
POST.events
unlimited*
/v1/events
POST
events
10
/v1/events
GET
global
125
N/A
N/A
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.
Error Responses
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 resource404 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.
Expired accounts and Authentication
Note that when an account expires, it enters a grace period, however the API key remains valid. Some endpoints may still be active so that there is no data loss (e.g. new lead POST to /v1/events) however the account may be in a locked down state and will receive a 403 Forbidden response for most other requests.
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:
- Make a request to Follow Up Boss API.
- If the request fails, wait 1 + random_number_milliseconds seconds and retry the request.
- If the request fails, wait 2 + random_number_milliseconds seconds and retry the request.
- 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.
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.comYou 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=ZillowPagination
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=25Response 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=5Send 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, peopleTagsCreated, peopleStageUpdated
peopleUpdated
One or more of the following fields are updated in a person:
- Name
namefirstNamelastName - Emails
emails - Phone Numbers
phones - Address
addresses - Price
price - Background
background - Assigned Agent
assignedToassignedUserId - Assigned Lender
assignedLenderNameassignedLenderId - Contacted
contacted - Stage
stagestageId - Lead Source
sourcesourceUrl - Tags
tags - Custom Fields
Custom Fields
If you want to view custom field data following a peopleUpdated event, make sure you add the query parameter fields=allFields to your GET /people request, custom fields are not returned by default.
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.
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"
}Limited number of webhooks per event
There is a limit to the amount of web hooks per event which can be registered. Unused webhooks should be disabled to prevent hitting the limit. If multiple endpoints for an event are desired, a single web hook should be registered which in turn handles the fan out to multiple endpoints. Keep in mind the best practices below about de-coupling the message receiving and workload so that the initial call does not timeout.
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 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:
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:
<?php
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 continue to retry for up to 8 hours. HTTP status codes of 406 or 410 result in the webhook being disabled.
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
2XXHTTP status code such as200 - When registering a webhook make sure you are setting the
X-Systemheader. 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/peopleCreatedorhttps://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
Available Response Fields
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.
Determining Lead Type
If you are trying to determine the lead type, such as "Buyer" or "Seller", this can be done by looks at the returned tags. If the lead is a "Seller" type, there will be a "Seller" tag initially set when the lead is created, otherwise the lead is a "Buyer".
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.