Real Geeks Docs

User Tools

Site Tools

Trace:
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
Next revision 		Previous revision
incoming_leads_api [2015/06/24 02:04]
igor property fields 		incoming_leads_api [2016/07/06 21:37] (current)
igor
Line 1: Line 1:
-Other products can send leads to your 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: L2L +
-  * Password: s3cret +
- +
-These credentials must be provided on all requests, using [[https://en.wikipedia.org/wiki/​Basic_access_authentication|HTTP Basic Auth]] +
- +
-''​credentials = base64("​L2L:​s3cret"​)''​ +
- +
-and the HTTP header will look like: +
- +
-''​Authorization:​ Basic TDJMOnMzY3JldA==''​ +
- +
-Each product talking to Real Geeks has a single Username and Password, these credentials will be used for 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. +
- +
- +
-====== 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. +
- +
-===== 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** bellow for the supported fields for this request. +
- +
-On success response has status ''​200 OK''​ and empty body ''​{}''​. +
-On error see **Error Responses** bellow +
- +
-===== 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''​ +
-  * ''​source_details''​ +
-  * ''​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 | +
-| ''​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 "​Seller"​ or "​Buyer"​ | +
-| ''​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 | +
-| ''​source_details''​ | string | optional | There is a ''​source''​ field that is automatically set to your ''​username''​ given in the ''​Authorization''​ header. ​ If sources have extra information to identify where this lead came from they can use this field. | +
-| ''​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 | TODO: document options | +
-| ''​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 is being sold, how long it's been in the market | +
-| ''​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"​ | +
-| ''​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"​]''​ | +
incoming_leads_api.1435111456.txt.gz · Last modified: 2015/06/24 02:04 (external edit)

Page Tools

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki