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/09/30 01:08] igor [PATCH /sites/<site_uuid>/leads/<lead_id>] |
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 24: | Line 24: | ||
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/ | + | Base url: http://receivers.leadrouter.realgeeks.com/rest |
all paths bellow should be appended to the url above. | all paths bellow should be appended to the url above. | ||
Line 83: | Line 83: | ||
* ''id'' | * ''id'' | ||
- | * ''source_details'' | ||
* ''activities'' | * ''activities'' | ||
* ''created'' | * ''created'' | ||
Line 107: | 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 122: | 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 144: | 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 159: | 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 170: | 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 180: | 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 186: | 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 214: | 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, | ||
} | } | ||
}, | }, |