User Tools

Site Tools


outgoing_leads_api_developers

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
outgoing_leads_api_developers [2016/04/30 02:33]
igor [Activity fields]
outgoing_leads_api_developers [2016/07/06 21:38] (current)
igor
Line 1: Line 1:
-====== Outgoing Leads API for Developers ====== +This page has moved to https://developers.realgeeks.com/​outgoing-leads-api/
- +
- +
-** 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 [[outgoing_leads_api|this ​page]] ** +
- +
-====== How to create a destination for Real Geeks Leads ====== +
- +
-First send a message to our [[https://www.realgeeks.com/​support/​|Support]] asking for credentials to create a Lead Router Destination. ​ We will give you a Real Geeks website and Real Geeks account. +
- +
-Then visit our [[http://​leadrouter.realgeeks.com|Lead Router config]], login with the Real Geeks credentials given and [[outgoing_leads_api|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 [[https://​www.realgeeks.com/​support/​|let us 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 ====== +
- +
-All fields a lead could possibly have.  If a field is **optional** it might not be present in the JSON. +
- +
-^ Field name         ^ Type   ^ Presence ^ Description | +
-| ''​action'' ​        | string | required | Identify what type of request this is, one of ''"​created"'',​ ''"​updated"''​ or ''"​activity_added"''​. ​ Sometimes the value ''"​unknown"''​ is given, this is not common but happens if the client is using a lead source that does not identify which action was performed, should be handled as "​update or create if doesn'​t exist" | +
-| ''​id'' ​            | string | required | Every lead has a unique identifier, used when updating the lead or adding activities to it | +
-| ''​partner_id'' ​    | string | required | The ID provided by the Real Geeks client when connecting to this destination | +
-| ''​source'' ​        | string | required | Tells where the lead came from.  See **Source values** below | +
-| ''​site_uuid'' ​     | string | required | The unique identifier of the site inside Real Geeks where this lead originated from.  If you intend to reference the site inside your system prefer to use this id instead of the ''​site_domain''​ because sometimes clients change the site domain | +
-| ''​site_domain'' ​   | string | required | The domain of the site that originated the lead | +
-| ''​site_login_url''​ | string | required | An url agents can use to login as this lead on the website | +
-| ''​agent_name'' ​    | string | optional | If this lead was generated from an Agent Page on the website, the agent full name will be given here | +
-| ''​agent_email'' ​    | string | optional | If this lead was generated from an Agent Page on the website, the agent email will be given here | +
-| ''​email'' ​         | string | required | Valid email address of the lead | +
-| ''​first_name'' ​    | string | required | Lead first name | +
-| ''​last_name'' ​     | string | optional | Lead last name, not always given | +
-| ''​role'' ​          | string | required | One of "​Seller",​ "​Buyer"​ or "​Potential Seller"​ | +
-| ''​phone'' ​         | string | optional | Phone number. US numbers could be formatted as ''​808-123-1234''​ or ''​(808) 123-1234''​. International number format: ''​+55 83 1234-1234''​. ​ Note that a valid format is not guaranteed, since some clients have other lead sources besides their website ​ | +
-| ''​activities'' ​    | list of **Activity** | optional | List of activities, see **Activity** fields below | +
-| ''​created'' ​       | string | required | Timestamp of when this lead was created, using ISO 8601, ex.: ''"​2015-04-01T08:​41:​51+00:​00"''​ | +
- +
-=== 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"​ +
- +
-But since clients can have custom lead sources using Zapier or our Incoming API, this field could have any value any other string value +
- +
-====== Activity fields ====== +
- +
-^ Field name      ^ Type         ^ Presence ^ Description | +
-| ''​type'' ​       | string ​      | required | See **Type values** below | +
-| ''​description''​ | string ​      | required | Human readable description | +
-| ''​property'' ​   | **Property** | optional | In case this activity was related to a specific property. ​ If present it is a document with **Property** fields | +
-| ''​created'' ​    | string ​      | optional | Timestamp of when this activity was created, using ISO 8601, ex.: ''"​2015-04-01T08:​41:​51+00:​00"''​ | +
-| ''​source'' ​     | string | required | Tells where the activity came from.  Can be the same set of values as Lead ''​source''​ field | +
- +
-=== 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 +