CRM/Lead Manager
      Back to home
      1. Internal RG Wiki
      2. Internal Documents
      3. CRM/Lead Manager

      Outgoing API (Developers)

      This document is directed to developers implementing a destination for Real Geeks Leads. If you're a client trying to connect to a destination visit this page.

      Create a destination for Real Geeks Leads

      1. Ask Support for credentials to create a Lead Router Destination. We will give you a Real Geeks website and Real Geeks account.

      2. Visit our Lead Router. 

      3. Login with the Real Geeks credentials given and follow the steps to configure a Custom API as destination.

      At first your Custom API destination will be available only for your test site, so you can use your website, sign-up, perform searches, etc, to trigger requests to your API.

      When you're ready to go Live, let Support know and provide the following information:

      • Description: a description of your destination that will be visible to users connecting to it
      • Partner ID Label: a label for your Partner ID field, what it means to your system, ex.: “Account ID”, “Site Code”
      • Partner ID Help: is a longer description with instructions on how users will be able to access the Partner ID from your system, ex.: “In order to access your Account ID visit Settings from your Dashboard”

      Request Types

      We have two main entities: Lead and Activity. A lead is somebody with name and contact information that signed up in a website. An activity is something a lead has done, like performing a search, viewing a property, marking a property as favorite, etc.

      A destination is a single url that accepts HTTP POST requests with a JSON body. There are four types of requests sent to this url:

      • New Lead: a new lead signed up on the website
      • Update Lead: some contact details of an existing lead was updated on the website
      • Add activities: one or more activities were added to an existing lead
      • New Potential Seller Lead: a lead attempted to use the property valuation tool on the website but didn't complete the signup process. More on this later.

      We identify which type of request is being sent with the action field.

      New Lead

      Somebody signed up on the website, it will contain contact information and at least one activity. See Lead fields below.

      Lead action field will be set to “created”. activities field is always present too, indicating the first actions the user performed on the website.

      Update Lead

      Lead contact details were updated on the website. Lead action field will be set to “updated” . Lead identification fields will also be available: id , site_uuid , site_domain and partner_id

      activities could be present too, in this case the lead details should be updated and these activities should be added. Activities are never removed or updated, only added.

      Activity Added

      One or more activities are being added to a Lead. For this request the following fields are set:

      • id: Lead id, same as given on creation
      • site_uuid
      • site_domain
      • action: “activity_added”
      • partner_id
      • activities: list of one or more activities. See Activity fields below.

      Activity Added requests are always sent after the corresponding New Lead requests. But sometimes they can arrive in a different order since the network isn't always reliable.

      New Potential Seller Lead

      Real Geeks websites have a property valuation tool, users enter an address and it provides an estimate sale value for that property. It also shows the last sold date and price.

      In order to visualize this information users have to sign up, giving their contact details. If the user doesn't finish the sign up process their contact information is unknown, all we have is the address they looked for. This is called a Potential Seller Lead.

      Lead Fields

      Tables can't be imported directly. Please insert an image of your table which can be found here.

      Source values Activity Activity

      But since clients can have custom lead sources using Zapier or our Incoming API, this field could have any value any other string value

      Source values

      These are know values source field could have

      • “Website Property Search”
      • “Website Property Valuation”
      • “Website Agent Landing Page”
      • “Website Property Landing Page”
      • “zillow”
      • “trulia.com”
      • “realtor.com”

      Activity Fields

      Tables can't be imported directly. Please insert an image of your table which can be found here.

      Type values Property Property

      Type Values

      Activity type indicates what action was performed by the lead. It's one of these values:

      • “visited”: user visited the first for the first time (initial sign-up) or is back to the site after two hours of inactivity
      • “search_performed”: user performed a search on the website. Description will contain a summary of the search filters
      • “saved_search_added”: user not only performed a search but also saved it to their profile. Description will contain a summary of the search filters
      • “saved_search_removed”: user removed a saved search. Description is the same as “saved_search_added”
      • “property_viewed”: user visualized a property on the website. Description contains a summary of the property details and a link to it.
      • “favorite_property_added”: user marked a property as favorite. Description will contain a summary of the property and a link to it on the website.
      • “favorite_property_removed”: user removed a favorited property. Description is the same as “favorite_property_added”
      • “property_updates_email_sent”: our systems sent an email to the user with updates about their saved searches and favorited properties, with information like price changes and new properties available
      • “bad_email_flagged”: our systems detected that the email address this user signed up with is not valid, emails failed to be sent to it
      • “bad_email_unflagged”: our systems can now send emails to this user's email address
      • “opted_out”: user opted out of our property updates emails
      • “deleted_from_website”: user account was deleted from the website. Not that other systems, like our Lead Manager, could still have this lead saved.
      • “contact_emailed”: user sent a contact message.
      • “valuation_inquire”: user used the property valuation tool to see the estimated value of a property.
      • “shared_property_via_email”: a lead has shared a property by email with somebody else, the description will contain the property url and the name and email of the person they shared it with.

      Property Fields

      Tables can't be imported directly. Please insert an image of your table which can be found here.

      Request Headers

      All requests will also include the following custom HTTP headers.

      X-Lead-Router-Message-Id

      Contains an id for this message. This is helpful to identify retries of the same request. Here is an example value:

      X-Lead-Router-Message-Id: 7ca66bef-c704-47f2-b46e-0638291bae85

      X-Lead-Router-Signature

      Contains the signature of this request body using the configured secret key. See details on our Security section below.

      User-Agent

      User-Agent is a string with the format: “RealGeeks-LeadRouter/v1.0”, where v1.0 is the API version.

      Minor changes to the API that shouldn't affect clients will increase the minor version number (v1.1, v1.2, etc).

      Major changes to the API that could potentially affect clients will be notified beforehand and when they take place the major version number will increase (v2.0, v3.0, etc).

      Here is an example value:

      User-Agent: RealGeeks-LeadRouter/1.0

      Retries

      We retry every time we get a response with status code different than 200 up to 8 times, here is the behavior:

      • Wait 10min before for the second, third and forth attempts
      • Wait 30min before the 5th attempt
      • 1h before the 6th
      • 2h before the 7th
      • 4h before the 8th

      All attempts of the same request will contain the same value of X-Lead-Router-Message-Id header.

      To avoid retries return status code 406.

      Security

      In order to receive requests from Real Geeks your API needs to be open to the internet. For security reasons you probably want to limit the requests you receive to those coming from Real Geeks. The easier way to do this is to setup a secret token and validate the request.

      This hash will be available as header X-Lead-Router-Signature. We have a full example of APIs in Go and Python validating the signature below. Obviously, your language and server implementations may differ. There's a couple important things to point out:

      • Only the full request POST body is used to build the hash, no headers
      • Using a plain string comparison == is not advised. Use a constant time string comparison function
      not advised

      Sample code in Python using Flask

      # API server validating Real Geeks Signature

      Sample code in Go


      // API server validating Real Geeks Signature

      Back to top.