This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
incoming_leads_api [2015/10/08 00:07] igor |
incoming_leads_api [2016/07/06 21:37] 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'' | + | |
- | * ''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 | | + | |
- | | ''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 "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 | | + | |
- | | ''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 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"]'' | | + | |
- | + | ||
- | + | ||
- | ====== Example code ====== | + | |
- | + | ||
- | Here is an example code in Python to send a new lead | + | |
- | + | ||
- | <code python> | + | |
- | import json | + | |
- | import requests | + | |
- | + | ||
- | # Listing to Leads (L2L) will have credentials to send Leads into Real Geeks, | + | |
- | # L2L will use the same credentials for every client | + | |
- | # | + | |
- | # On the Real Geeks side we know which clients will be allowed to receive | + | |
- | # requests from L2L | + | |
- | USERNAME = 'L2L' | + | |
- | 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, L2L will 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 = { | + | |
- | "email": "jack@gmail.com", | + | |
- | "first_name": "Jack", | + | |
- | "last_name": "Johnson", | + | |
- | "role": "Buyer", | + | |
- | "phone": "808-123-1234", | + | |
- | "created": "2015-04-01T08:41:51+00:00", | + | |
- | "source_details": "Craigslist Campaign", | + | |
- | "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"] | + | |
- | } | + | |
- | }, | + | |
- | ] | + | |
- | } | + | |
- | + | ||
- | # 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> | + |