incoming_leads_api
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
|
incoming_leads_api [2015/06/24 02:19] igor |
incoming_leads_api [2016/05/27 21:09] igor [Property fields] |
||
|---|---|---|---|
| Line 5: | Line 5: | ||
| First the product has to be registered and a username and password will be provided, example: | First the product has to be registered and a username and password will be provided, example: | ||
| - | * Username: L2L | + | * Username: mywebsite |
| * Password: s3cret | * Password: s3cret | ||
| These credentials must be provided on all requests, using [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic Auth]] | These credentials must be provided on all requests, using [[https://en.wikipedia.org/wiki/Basic_access_authentication|HTTP Basic Auth]] | ||
| - | ''credentials = base64("L2L:s3cret")'' | + | ''credentials = base64("mywebsite:s3cret")'' |
| and the HTTP header will look like: | and the HTTP header will look like: | ||
| - | ''Authorization: Basic TDJMOnMzY3JldA=='' | + | ''Authorization: Basic bXl3ZWJzaXRlOnMzY3JldA=='' |
| - | 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. | + | 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/ | To obtain credentials send a message to https://www.realgeeks.com/support/ | ||
| Line 23: | Line 23: | ||
| 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. | 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 ===== | ===== POST /sites/<site_uuid>/leads ===== | ||
| Line 50: | Line 55: | ||
| All activities listed in the activities will be added to the existing lead, activities are never deleted. | 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. | + | See **Lead Fields** below for the supported fields for this request. |
| On success response has status ''200 OK'' and empty body ''{}''. | On success response has status ''200 OK'' and empty body ''{}''. | ||
| - | On error see **Error Responses** bellow | + | On error see **Error Responses** below |
| ===== POST /sites/<site_uuid>/leads/<lead_id>/activities ===== | ===== POST /sites/<site_uuid>/leads/<lead_id>/activities ===== | ||
| Line 78: | Line 83: | ||
| * ''id'' | * ''id'' | ||
| - | * ''source_details'' | ||
| * ''activities'' | * ''activities'' | ||
| * ''created'' | * ''created'' | ||
| Line 102: | Line 106: | ||
| ^ Field name ^ Type ^ Presence ^ Description | | ^ Field name ^ Type ^ Presence ^ Description | | ||
| | ''id'' | string | optional | If no ''id'' is given we'll generate one, if given should be a valid UUID | | | ''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 | | | ''agent_id'' | string | optional | An identification of the Agent assigned to this lead | | ||
| | ''email'' | string | required | Valid email address | | | ''email'' | string | required | Valid email address | | ||
| | ''first_name'' | string | required | | | | ''first_name'' | string | required | | | ||
| | ''last_name'' | string | optional | | | | ''last_name'' | string | optional | | | ||
| - | | ''role'' | string | required | One of "Seller" or "Buyer" | | + | | ''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'' | | | ''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 | | | ''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 | | | ''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"'' | | | ''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"'' | | ||
| Line 117: | Line 121: | ||
| ^ Field name ^ Type ^ Presence ^ Description | | ^ Field name ^ Type ^ Presence ^ Description | | ||
| - | | ''type'' | string | required | TODO: document options | | + | | ''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 | | | ''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 | | | ''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"'' | | | ''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 ====== | ====== Property fields ====== | ||
| Line 139: | Line 143: | ||
| | ''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_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_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 | | + | | ''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" | | | ''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_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" | | | ''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"]'' | | | ''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 ====== | ====== Example code ====== | ||
| Line 154: | Line 161: | ||
| import requests | import requests | ||
| - | # Listing to Leads (L2L) will have credentials to send Leads into Real Geeks, | + | # There are your credentials are provided by us |
| - | # L2L will use the same credentials for every client | + | USERNAME = 'mywebsite' |
| - | # | + | |
| - | # On the Real Geeks side we know which clients will be allowed to receive | + | |
| - | # requests from L2L | + | |
| - | USERNAME = 'L2L' | + | |
| PASSWORD = 's3cret' | PASSWORD = 's3cret' | ||
| Line 165: | Line 168: | ||
| auth = requests.auth.HTTPBasicAuth(USERNAME, PASSWORD) | auth = requests.auth.HTTPBasicAuth(USERNAME, PASSWORD) | ||
| - | # Each Real Geeks client has a unique identifier, L2L will use this identifier | + | # Each Real Geeks client has a unique identifier, Use this identifier |
| # to specify which client will receive this Lead inside Real Geeks | # to specify which client will receive this Lead inside Real Geeks | ||
| SITE_UUID = '106994a2-ad21-4ab7-ad89-1c4ccd9ae8a5' | SITE_UUID = '106994a2-ad21-4ab7-ad89-1c4ccd9ae8a5' | ||
| Line 175: | Line 178: | ||
| # Lead format in JSON, see documentation for all supported fields | # Lead format in JSON, see documentation for all supported fields | ||
| lead = { | lead = { | ||
| + | "source": "My Website", | ||
| "email": "jack@gmail.com", | "email": "jack@gmail.com", | ||
| "first_name": "Jack", | "first_name": "Jack", | ||
| Line 181: | Line 185: | ||
| "phone": "808-123-1234", | "phone": "808-123-1234", | ||
| "created": "2015-04-01T08:41:51+00:00", | "created": "2015-04-01T08:41:51+00:00", | ||
| - | "source_details": "Craigslist Campaign", | ||
| "activities": [ | "activities": [ | ||
| { | { | ||
| Line 209: | Line 212: | ||
| "last_sold_date": "2015-12-25", | "last_sold_date": "2015-12-25", | ||
| "last_sold_price": "25000.99", | "last_sold_price": "25000.99", | ||
| - | "tags": ["kailua","oahu","12345"] | + | "tags": ["kailua","oahu","12345"], |
| + | "latitude": 21.29242539, | ||
| + | "longitude": -157.8501134, | ||
| } | } | ||
| }, | }, | ||
incoming_leads_api.txt · Last modified: 2016/07/06 21:37 by igor
Page Tools
