Leads

A lead is a prospective buyer or seller. Leads are generated from a source and are sent to a destination. The default source for leads within Real Geeks is your website, and the default destination is your Lead Manager CRM.

Once a lead is created, be it on the website or any other source, it’s given an id. This id is unique and used to to identify the lead when doing updates and when adding activities to it.

The following fields can be provided by the Incoming API and are available in the Outgoing API

Field name	Type	Presence	Description
id	string	optional	When creating a lead you can provide this ID, has to be a valid UUID. If not provided we’ll generate one
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
source_details	string	optional	Additional information about where and/or how this lead was generated. This field is displayed to users so provide a readable value.
email	string	optional *	Valid email address
second_email	string	optional *	Valid email address for a secondary contact
first_name	string	optional *
last_name	string	optional *
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
phone2	string	optional *	Alternate phone number for this lead. Same format asphone
address	string	optional *	Full formatted address. If you have separate address components use the fields below
street_address	string	optional *
city	string	optional *
state	string	optional *
zip	string	optional
role	string	optional	Lead role, one of "Buyer", "Seller", "Buyer and Seller", "Renter". When receiving leads from the Outgoing API this value could also be "Potential Seller", but to send Potential Seller leads use /potential-seller-leads endpoint from our API.
activities	list of objects	optional	List of activities. See Activities for details
region	string	optional	Is used by some sources to help destinations do geographic round-robin lead assignment. Lead Manager CRM displays this value as “Area”. The website sends the area of the first search.
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 in UTC. 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”
timeframe	string	optional	Timeframe is how long until the lead is ready to buy/sell. Allowed values: "Immediately", "1 Week", "2-4 Weeks", "30 Days", "60 Days", "90 Days", "3-6 Months", "6-12 Months", "1 Year Or More"
urgency	string	optional	Indicates how urgent this lead should be contacted.Value has to be one of the system values: "Cold", "Warm", "Hot", "Contacted", "Not Contacted". Or any custom value added in the Lead Manager CRM.
status	string	optional	Current status of this lead. Value has to be one of the system values: "Active", "Cancelled", "In Escrow", "Closed Escrow" and "Dead". Or any custom status added in the Lead Manager CRM.
notes	string	optional
tags	list of strings	optional

* at least one identification field is required to create a lead. You must provide at least one of: first_name, last_name, email, phone or address

Extra fields are available only for the Outgoing API.

Field name	Type	Presence	Description
action	string	required	Identify what type of request this is, one of “created”, “updated” or “activity_added”. Sometimes the value “unknown” is given, this is not common but happens if the client is using a lead source that does not identify which action was performed, should be handled as “update or create if doesn’t exist”
id	string	required	Every lead has a unique identifier, used when updating the lead or adding activities to it
partner_id	string	required	The ID provided by the Real Geeks client when connecting to this destination
site_uuid	string	required	The unique identifier of the site inside Real Geeks where this lead originated from. If you intend to reference the site inside your system prefer to use this id instead of the site_domain because sometimes clients change the site domain
site_domain	string	required	The domain of the site that originated the lead
site_login_url	string	required	An url agents can use to login as this lead on the website
agent_name	string	optional	Deprecated
agent_email	string	optional	Deprecated
source_system	string	required	Sometimes a single system could generate leads with more than one source, like your Real Geeks Website. This field indicate which system generated this lead to remove this ambiguity.

Source values

Leads originating from your Real Geeks website can have one of the following sources:

• “Website Property Search”
• “Website Property Valuation”
• “Website Agent Landing Page”
• “Website Property Landing Page”

Website leads will have source_system set to "Website".

Leads and activities originating from the Lead Manager CRM will have source and source_system set to "LeadManager".

If you’re sending leads using the API we advise to keep the source values to a minimum, ideally one. This way it can be added as an Additional Source in the Lead Manager CRM to be available in the advanced search.

For leads created using the Incoming Leads API the source_system is set automatically to the username you used to authenticate in the API.

Assigned Leads

To create leads assigned to a specific user add a was_assigned activity to the list of activities of the lead being created, should look like this:

"activities": [
  {
    "type": "was_assigned",
    "user": {"id": "12345"},
    "role": "agent",
    "description": "Optional description"
  }
]

id is the only required field for user. To find out the user id you need for your agents in the Lead Manager CRM use our users API.

Same rule applies we receiving leads from Real Geeks, you should expect to see  was_assigned activity.

This activity can be sent or received by itself using the activities endpoint, or embedded in the lead.

Read more about the was_assigned activity and the fields it contains.