Blog

Unsetting Fields on Leads

On June 25, we will release an update to the Leads API that allows integrations to unset fields on Leads. The current API does not allow unsetting a Lead’s phone number, for example, instead that change must be made directly in the CRM’s user interface. This change provides greater flexibility to enable the development of more advanced 3rd party integrations.

You can take advantage of this new capability via a new v2 Lead endpoint on the Incoming Leads API:

PATCH /sites/{site-uuid}/v2/leads/{lead-id}

As part of this change, existing integrations may begin receiving Lead messages that contain keys with empty values via the Outgoing Leads API. These empty values represent a Lead field that has been unset in the CRM or via the Incoming Leads API. Existing integrations may need to be updated to handle these empty values. Any local lead representation should be updated with the new, empty value.

For example, an update to a Lead to unset phone2:

curl -X POST 'https://receivers.leadrouter.realgeeks.com/rest/sites/{site-uuid}/leads/{lead-id}/activities' \ 
  -u '{user}:{password}' \
  -d '{"phone2":""}'

Will produce the following message on the Outgoing Leads API:

{
  "action": "updated",
  "id": ":lead_id",
  "partner_id": "001",
  "phone2": "", // <-- Notice new, empty field
  "site_domain": "testsite.realgeeks.com",
  "site_login_url": "http://testsite.realgeeks.com/member/quick_login/:lead_id/",
  "site_uuid": ":site_id",
  "source": "test",
  "source_system": "test"
}

Activities notifications using the API

A new feature was added to our API where clients can instruct the Lead Manager CRM to send a notification to the assigned Agent and/or Lender when an activity is created.

First make sure the notification setting Activity shared by another user is enabled.

notification settings - shared by another user

Now when sending an activity set the field notify_users to true

curl -X POST 'https://receivers.leadrouter.realgeeks.com/rest/sites/{site-uuid}/leads/{lead-id}/activities' \
-u '{user}:{password}' \
-d '[
    {
        "type": "note",
        "description": "Something happened",
        "notify_users": true,
        "source": "My System"
     }
]'

The assigned agent and/or the assigned lender will receive a notification. Here is the email notification received for the activity above:

email notification of activity shared by another user

New separate lead address fields

Our Lead object always had an address field. Now we introduced separate fields to send and receive the address in different components: street_address, city, state and zip.

address field still exists and corresponds to the full formatted address. If you are sending a lead to Real Geeks and have the address separated into multiple components use the separated fields. If you have the full address only use the address field.

{
  "street_address": "123 Mokulua Dr",
  "city": "Kailua",
  "state": "HI",
  "zip": "96734",
  "address": "123 Mokulua Dr, Kailua, HI 96734
}

Separate address fields are also available in our Zapier app.

New field “notes” added to Lead

We added a new field notes to the Lead object, corresponding to the Notes field of the Important Notes section in the lead details page of the Lead Manager CRM

Screenshot 2017-05-03 10.59.39

This field can be sent when creating or updating a lead using the Incoming API and will also be available in our Outgoing API.

Example request:

curl -X POST 'https://receivers.leadrouter.realgeeks.com/rest/sites/{site-uuid}/leads' \
    -u '{user}:{pass}' -v \
    -d '{
            "email": "lead@mail.com",
            "notes": "Important notes..."
        }'

We still have the activity of type note. These activities will be in the lead’s activity history, they don’t change the Notes field.

Here is an example of a note activity:

curl -X POST 'https://receivers.leadrouter.realgeeks.com/rest/sites/{site-uuid}/leads/{lead-id}/activities' \
    -u '{user}:{pass}' -v \
    -d '[
            {
                "type": "note",
                "description": "more notes...",
                "source": "Dialer"
            }
        ]'

Screenshot 2017-05-03 11.11.10

This field is also available in our Zapier app.

New activity: deleted

Real Geeks has added a new activity type to our Outgoing API:

{
  "description": "This lead was deleted from Lead Manager", 
  "source": "LeadManager",
  "type": "deleted"
}

This activity is sent when a lead is deleted from our Lead Manager, which also deletes the lead from the website, which means this lead no longer exists in Real Geeks.

This activity complements an existing one which notifies when a lead is deleted from the website only, but remains in the Lead Manager:

{
  "description": "This lead was deleted from the website",
  "source": "Website",
  "type": "deleted_from_website"
}

New “enabled” and “disabled” request types

We just added two new request types to our Outgoing Leads API allowing destinations to know when clients enable or disable an integration with them.

When an integration is enabled Real Geeks will send a POST to the destination URL with the following JSON body:

{
    "action": "integration_enabled",
    "partner_id": "{value or partner id}",
    "site_uuid": "{value or site uuid}"
}

And when a destination is disabled Real Geeks will send:

{
    "action": "integration_disabled",
    "partner_id": "{value of partner id}",
    "site_uuid": "{value of site uuid }"
}

When developers are also using the Incoming Leads API this request will help them store the site_uuid to be used on requests to that site.

Assign leads using the API

You can now assign leads to specific agents using our API, just send a was_assigned activity containing a user id. The activity format will look like this:

{
  "type": "was_assigned",
  "user": {"id": "12345"}
}

description field is optional and recommended, will be visible in the lead activity history in the Lead Manager CRM.

To find our the user id use our Users API. This feature works for both Agents and Lenders.

This activity can be sent as part of the the lead when creating or later using the activities endpoint. See our API endpoints for details.

Partial Leads

This week we announced Partial Leads in the Lead Manager CRM. This will allow importing leads and manually creating leads that only require one of the following: first name, last name, email, phone or address.

From the API point of view for a lead to be created you must provide at least one of: first_name, last_name, email, phone or address. source field is still required.

And for integrations receiving leads from our Outgoing API keep in mind that you could receive a lead being created missing those fields.

New assignment activities

We now offer new activities in the Outgoing Leads API with real-time information about lead assignment.

Manual and Automatic Assignment

A lead could be assigned to an Agent in the Lead Manager CRM in one of two ways: automatic or manual. Automatic lead assignment – standard Round-Robin, weighted or geographic – happens instantly the moment the lead is saved in the Lead Manager CRM and manual assignment requires human interaction.

Lead was assigned

When a lead is assigned, either automatically or manually, your destination will receive an activity with type set to "was_assigned". Keep in mind that this activity could be in the activities list of the new Lead or standalone in a "activity_added" request.

Here is an example "was_assigned" activity:

  {
   "type": "was_assigned",
   "source": "LeadManager",
   "description": "Lead was assigned to Jack Johnson",
   "created": "2016-07-06T23:51:00.052125851Z",
   "user": {
    "id": "14187",
    "role": "Agent",
    "name": "Jack Johnson",
    "email": "jack@music.com"
   },
  }

A similar activity is sent when a lead is reassigned to another Agent. In this case the description will contains a summary of what happened, like
“Lead was assigned from Jack Johnson to Jason Mraz”.

Lead was unassigned

There is a specific activity for when a lead is unassigned, "was_unassigned"

  {
   "type": "was_unassigned",
   "source": "LeadManager",
   "description": "Lead was unassigned from Jason Mraz",
   "created": "2016-07-06T23:20:54.030179169Z"
  }

Manual assignment

When automatic lead assignment is not configured with Round-Robin the assignment will be manual in the Lead Manager CRM. Since this manual process could potentially take a long time when a lead created in the Lead Manager CRM and the assignment will be manual a new activity is sent: "waiting_for_manual_assignment"

  {
   "type": "waiting_for_manual_assignment",
   "source": "LeadManager",
   "description": "Lead was created without being assigned to an agent",
   "created": "2016-07-06T23:21:44.858339012Z"
  }

Conclusion

These new activity types are a big step towards making lead assignment extensible within Real Geeks. Now other lead destinations have assignment information in real-time. The next steps are:

  • Allow clients to change lead assignment using the Incoming Leads API by sending these activity types.
  • Allow destinations and/or clients to decide if leads should wait to be assigned before sending them. This way destinations can receive only assigned leads.