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"},
    "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.