Page contents
Other products can send leads to Lead Manager CRM using our Incoming Leads API. This documentation is for developers looking to integrate with Real Geeks.
We offer a clients to this API in Python and Ruby.
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 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.
Visit this page to request API access
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: https://receivers.leadrouter.realgeeks.com/rest
all paths below should be appended to the url above.
POST /sites/{site-uuid}/leads
Create a new lead.
-
site_uuidis the Client Identification inside Real Geeks.
This endpoint assumes the lead doesn’t exist yet, but our Lead Manager CRM might decide they already have this lead (based on email or name, for example) and update it.
See Leads 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 UUID string.
On success response has status 201 Created and empty json body {}. On error see Error Responses below
PATCH /sites/{site-uuid}/leads/{lead-id}
Update an existing lead. Where
-
site_uuidis the Client Identification inside Real Geeks -
lead-idis 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 Leads 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_uuidis the Client Identification inside Real Geeks -
lead_idis the id of an existing lead
Request body is a list of objects where each object has Activity fields
Example body:
[ { "type": "contact_emailed", "description": "Hi, I'm interested in buying a house in Hawaii", "created": "2015-04-01T08:55:55+00:00" }, { "type": "note", "description": "A new note!" } ]
On success response has status 200 OK and empty body {}. On error see Error Responses below
-
site_uuidis 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 propertyfield.
The supported fields is a small subset of the Leads fields:
-
id -
activities -
created
See Leads and Activity for details.
On success response has status 201 Created and empty json body {}. On error see Error Responses below.
-
site_uuidis the Client Identification inside Real Geeks lead_idis the Lead Identification inside Real Geeks
Returns the lead data including their was_assigned activities.
See Leads and Activity for details.
On success response has status 200 OK and json body with lead data. On error see Error Responses below.
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 |
Example code
Here is an example code in Python to send a new lead:
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)
Here is an example code using cURL to send a new lead (you will need to fill in the site_uuid and your basic auth token):
curl --location --request POST 'https://receivers.leadrouter.realgeeks.com/rest/sites/<site_uuid>/leads' \
--header 'Authorization: Basic <basic_auth_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"first_name": "RG",
"last_name": "Test Lead",
"email": "atestlead@thisisnotareallead.com",
"street_address": "123 Kailua Rd",
"city": "Kailua",
"state": "HI",
"zip": "96734",
"notes": "I am a note",
"activities": [
{
"type": "important_date_added",
"description": "Hi, I'\''m interested in buying a house in Hawaii",
"created": "2022-04-01T08:55:55+00:00"
}
]
}'
Going live
Once your integration is developed and ready to make requests to Real Geeks clients you need to ask each client to grant access to their site.
Your credentials remain the same, but you need to be granted access for each client site and know what is that site uuid.
In order to do that you have a URL that looks like:
https://leadrouter.realgeeks.com/dev/{your-company-id}/grant/
When clients visit this URL they will see all sites they own in Real Geeks:
They just need to check which sites they are granting access to and click save
At this point the client can now receive data from your integration through the incoming API and an email is sent to the developer responsible for the integration containing the site uuid. Note how the site uuid is also now visible to the client so they can copy and paste somewhere to let the developer know.
This step is not fully automated, either the client needs to let the developer know what is the site uuid or the developer need to check his email and find the site uuid there.
If you prefer to automate this step you can create a Destination using our Outgoing API. When clients enable a Destination on their site the first request we send is an integration_enabled request which contains the site_uuid, and at this point we also include this site as one of the sites your API credentials have access to. So everything our client needs to do is connect to a Destination and that will give the integration access to both Outgoing and Incoming APIs
Developers 