User Tools

Site Tools


incoming_leads_api

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
incoming_leads_api [2016/05/27 21:09]
igor [Property fields]
incoming_leads_api [2016/07/06 21:37] (current)
igor
Line 1: Line 1:
-Other products can send leads to Lead Manager using our Incoming Leads API.  ​This documentation is for developers looking to integrate with Real Geeks. +This page has moved to https://developers.realgeeks.com/​incoming-leads-api/
- +
-====== Authentication ====== +
- +
-First the product ​has to be registered and a username and password will be provided, example: +
- +
-  * Username: mywebsite +
-  * Password: s3cret +
- +
-These credentials must be provided on all requests, using [[https://en.wikipedia.org/​wiki/​Basic_access_authentication|HTTP Basic Auth]] +
- +
-''​credentials = base64("​mywebsite:​s3cret"​)''​ +
- +
-and the HTTP header will look like: +
- +
-''​Authorization:​ Basic bXl3ZWJzaXRlOnMzY3JldA==''​ +
- +
-Each product talking to Real Geeks has a single username and password, these credentials will be used to send leads to any Real Geeks client. ​ Each Real Geeks client has a unique identifier called **Site UUID**, internally we know which clients a product has access to. +
- +
-To obtain credentials send a message to https://www.realgeeks.com/​support/ +
- +
-====== Endpoints ====== +
- +
-We allow leads to be created, updated and activities to be added. ​ An activity is anything a lead has done, like sent a contact message or viewed a property. +
- +
-Base url: http://​receivers.leadrouter.realgeeks.com/​rest +
- +
-all paths bellow should be appended to the url above. +
- +
- +
-===== POST /​sites/<​site_uuid>/​leads ===== +
- +
-Create a new lead. +
- +
-  * ''​site_uuid''​ is the Client Identification inside Real Geeks. +
- +
-This endpoint assumes the lead doesn'​t exist yet, but our Lead Manager might decide they already have this lead (based on email or name, for example) and update it. +
- +
-See **Lead Fields** bellow for the supported fields for this request. +
- +
-One of the fields is ''​id'',​ so if clients want to update or add activities to this lead later they should generate an ''​id''​ and send with this request. ​ The only requirement is the ''​id''​ field needs to be a valid [[https://​en.wikipedia.org/​wiki/​Universally_unique_identifier|UUID]] string. +
- +
-On success response has status ''​201 Created''​ and empty json body ''​{}''​. +
-On error see **Error Responses** bellow +
- +
-===== PATCH /​sites/<​site_uuid>/​leads/<​lead_id>​ ===== +
- +
-Update an existing lead. Where +
- +
-  * ''​site_uuid''​ is the Client Identification inside Real Geeks +
-  * ''​lead_id''​ is the id of an existing lead +
- +
-All fields are optional. Only fields that are present are updated. Fields that are not present are left alone. +
- +
-All activities listed in the activities will be added to the existing lead, activities are never deleted. +
- +
-See **Lead Fields** below for the supported fields for this request. +
- +
-On success response has status ''​200 OK''​ and empty body ''​{}''​. +
-On error see **Error Responses** below +
- +
-===== POST /​sites/<​site_uuid>/​leads/<​lead_id>/​activities ===== +
- +
-Add one or more activities to an existing lead. +
- +
-  * ''​site_uuid''​ is the Client Identification inside Real Geeks +
-  * ''​lead_id''​ is the id of an existing lead +
- +
-Request body is a list of objects where each object has **Activity fields** +
- +
-On success response has status ''​200 OK''​ and empty body ''​{}''​. +
-On error see **Error Responses** bellow +
- +
-===== POST /​sites/<​site_uuid>/​potential-seller-leads ​===== +
- +
-  * ''​site_uuid''​ is the Client Identification inside Real Geeks +
- +
-Create a Potential Seller Lead, an anonymous lead that has the potential to become a seller lead. +
- +
-No contact information is available, no name, email or phone number. But it has at least one Activity of type ''​property_viewed''​ with a ''​property''​ field. +
- +
-The supported fields is a small subset of the Leads fields: +
- +
-  * ''​id''​ +
-  * ''​activities''​ +
-  * ''​created''​ +
- +
-See **Leads fields** and **Activity fields** bellow for details +
- +
-On success response has status ''​201 Created''​ and empty json body ''​{}''​. +
-On error see **Error Responses** bellow +
- +
- +
-====== Error responses ====== +
- +
-^ Status ​                   ^ When   ^ Body   ^ +
-| 401 Not Authorized ​       | ''​Authorization''​ header is missing or incorrect, or the given credentials doesn'​t have permission for this site | ''​{"​error":"​description"​}''​ | +
-| 400 Bad Request ​          | Request body doesn'​t contain a valid JSON document | ''​{"​error":"​description"​}''​ | +
-| 422 Unprocessable Entity ​ | Request body has valid JSON document but one of the fields did not validate | ''​{"​error":"​description"​}''​ | +
-| 500 Internal Server Error | Unknown error | Unspecified | +
-| 503 Service Unavailable ​  | API server is not responding ​ | Unspecified | +
- +
- +
-====== Lead Fields ====== +
- +
-^ Field name         ^ Type   ^ Presence ^ Description | +
-| ''​id'' ​            | string | optional | If no ''​id''​ is given we'll generate one, if given should be a valid UUID | +
-| ''​source'' ​        | string | required | Name of your source, where leads are coming from.  This will be displayed to agents so they know where this lead was generated | +
-| ''​agent_id'' ​      | string | optional | An identification of the Agent assigned to this lead | +
-| ''​email'' ​         | string | required | Valid email address | +
-| ''​first_name'' ​    | string | required | | +
-| ''​last_name'' ​     | string | optional | | +
-| ''​role'' ​          | string | required | One of ''"​Buyer"'',​ ''"​Seller"'',​ ''"​Buyer or Seller"''​ or ''"​Renter"''​ | +
-| ''​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''​ | +
-| ''​activities'' ​    | list of **Activity** | optional | List of activities, see **Activity** fields bellow | +
-| ''​region'' ​        | string | optional | Is used by some sources to help destination do geographic round-robin lead assignment | +
-| ''​created'' ​       | string | optional | When creating a lead this field is optional and if not provided will be set to the time the request was received. ​ When updating a lead this field will be ignored, it can't be updated. ​ Format must be a combined date and time according to ISO 8601, ex.: ''"​2015-04-01T08:​41:​51+00:​00"''​ | +
- +
- +
-====== Activity fields ====== +
- +
-^ Field name      ^ Type         ^ Presence ^ Description | +
-| ''​type'' ​       | string ​      | required | We have a list of [[http://​docs.realgeeks.com/​outgoing_leads_api_developers#​type_values|all supported types]] | +
-| ''​source'' ​     | string ​      | required | Name of your source, where activity is coming from | +
-| ''​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 | When creating a lead this field is optional and if not provided will be set to the time the request was received. ​ Format must be a combined date and time according to ISO 8601, ex.: ''"​2015-04-01T08:​41:​51+00:​00"''​ | +
- +
-====== Property fields ====== +
- +
-^ Field name                 ^ Type    ^ Presence ^ Description | +
-| ''​mls'' ​                   | string ​ | optional | MLS number | +
-| ''​url'' ​                   | string ​ | optional | Full absolute url to visualize property | +
-| ''​street_address'' ​        | string ​ | optional | Street portion of the address, ex: "123 Keolu Rd Unit 12" | +
-| ''​city'' ​                  | string ​ | optional | | +
-| ''​state'' ​                 | string ​ | optional | | +
-| ''​zip'' ​                   | string ​ | optional | | +
-| ''​beds'' ​                  | integer | optional | Number of bedrooms | +
-| ''​full_baths'' ​            | integer | optional | Number of full bathrooms | +
-| ''​half_baths'' ​            | integer | optional | Number of half bathrooms | +
-| ''​type'' ​                  | string ​ | optional | Human readable type, ex: "​Single Family Home" or "​Condo"​ | +
-| ''​sqft'' ​                  | string ​ | optional | Property square feet, has no format requirement | +
-| ''​listing_price'' ​         | string ​ | optional | If the property is being sold this is the price it's being listed for.  The supported format is a number with optional decimal places, ex.: "​100500"​ or "​100500.90"​ | +
-| ''​listing_status'' ​        | string ​ | optional | If the property is being sold this is the current status, any format is allowed. ex.: "For Sale" | +
-| ''​listing_days_on_market''​ | integer | optional | If the property has pending date, the number of days between list date and pending date. If the property has no pending date, but has a closing date, the number of days between list date and closing date.  If the property has no closing date, but has a list date, the number of days between list date and today. Otherwise, nothing| +
-| ''​list_date'' ​             | string ​ | optional | When this property was listed for sale. Format must be a combined date and time according to ISO 8601, ex.: “2015-04-01T08:​41:​51+00:​00” | +
-| ''​estimated_value'' ​       | string ​ | optional | Estimated value this property could be sold for, useful for Seller or Potential Seller leads. ​ Could be from an automated or personalized valuation. ​ The supported format is a number with optional decimal places, ex.: "​100500"​ or "​100500.90"​ | +
-| ''​last_sold_date'' ​        | string ​ | optional | Doesn'​t have any format requirement,​ could be something like ''"​2015-12-25"''​ | +
-| ''​last_sold_price'' ​       | string ​ | optional | If present will be a number with optional decimal places, ex.: "​100500"​ or "​100500.90"​ | +
-| ''​rent_price'' ​            | string ​ | optional | Monthly rent price, used if this property is for rent | +
-| ''​tags'' ​                  | []string| optional | Search tags, could be address components or any other field that destinations might use to easily implement a search feature. ​ For Real Geeks websites we send things like street address, neighborhood,​ state, island, mls number, etc. i.e. ''​["​kailua",​ "​212",​ "​oahu",​ "​981112"​]''​ | +
-| ''​latitude'' ​              | float   | optional | | +
-| ''​longitude'' ​             | float   | optional | | +
-| ''​year_built'' ​            | integer | optional | Year this property was built | +
-====== Example code ====== +
- +
-Here is an example code in Python to send a new lead +
- +
-<code python>​ +
-import json +
-import requests +
- +
-# There are your credentials are provided by us +
-USERNAME = '​mywebsite'​ +
-PASSWORD = '​s3cret'​ +
- +
-# Credentials are provided using HTTP Basic Auth ('​Authorization'​ header) +
-auth = requests.auth.HTTPBasicAuth(USERNAME,​ PASSWORD) +
- +
-# Each Real Geeks client has a unique identifier, Use this identifier +
-# to specify which client will receive this Lead inside Real Geeks +
-SITE_UUID = '​106994a2-ad21-4ab7-ad89-1c4ccd9ae8a5'​ +
- +
-# Each Real Geeks client has a specific URL to receive leads, based on the +
-# Site UUID +
-url = '​http://​receivers.leadrouter.realgeeks.com/​rest/​sites/'​+SITE_UUID+'/​leads'​ +
- +
-# Lead format in JSON, see documentation for all supported fields +
-lead = { +
-    "​source":​ "My Website",​ +
-    "​email":​ "​jack@gmail.com",​ +
-    "​first_name":​ "​Jack",​ +
-    "​last_name":​ "​Johnson",​ +
-    "​role":​ "​Buyer",​ +
-    "​phone":​ "​808-123-1234",​ +
-    "​created":​ "​2015-04-01T08:​41:​51+00:​00",​ +
-    "​activities":​ [ +
-        { +
-            "​type":​ "​contact_emailed",​ +
-            "​description":​ "Hi, I'm interested in buying a house in Hawaii",​ +
-            "​created":​ "​2015-04-01T08:​55:​55+00:​00",​ +
-        }, +
-        { +
-            "​type":​ "​property_viewed",​ +
-            "​description":​ "​I'​d like to visit this house",​ +
-            "​property":​ { +
-                "​mls":​ "​12345",​ +
-                "​url":​ "​http://​www.site.com/​property/​123",​ +
-                "​street_address":​ "123 Keolu Dr", +
-                "​city":​ "​Kailua",​ +
-                "​state":​ "​HI",​ +
-                "​zip":​ "​96734",​ +
-                "​beds":​ 2, +
-                "​full_baths":​ 3, +
-                "​half_baths":​ "​1",​ +
-                "​type":​ "​Condo",​ +
-                "​sqft":​ "​1340",​ +
-                "​listing_price":​ "​100500",​ +
-                "​listing_status":​ "For Sale",​ +
-                "​listing_days_on_market":​ 10, +
-                "​estimated_value":​ "​145000",​ +
-                "​last_sold_date":​ "​2015-12-25",​ +
-                "​last_sold_price":​ "​25000.99",​ +
-                "​tags":​ ["​kailua","​oahu","​12345"​],​ +
-                "​latitude":​ 21.29242539,​ +
-                "​longitude":​ -157.8501134,​ +
-            } +
-        }, +
-    ] +
-+
- +
-# Request body has to be in JSON format +
-body = json.dumps(lead) +
- +
-resp = requests.post(url,​ data=body, auth=auth) +
- +
-print(resp) +
-print(resp.text) +
-</code>+
incoming_leads_api.txt · Last modified: 2016/07/06 21:37 by igor