Skip to content

Leads

Get Lead

  • Endpoint:
GET /leads/{id}
  • Allowed for:

users that has right lead.read

  • Filters :
Name Comment Value
excluded_user returns all users properties except the given user id ex: 3
user filter by the given user id ex: 3
query filter on id, last name, first name, mobile and email ex: "David P"
id filter by the given user id ex: 3
name filter on last name, first name ex: 3
mobile filter on mobile ex: 3
status filter on status (available: notYetContacted, calledNoReply, prospect, qualified, viewingsInProgress, contractSent, contractSigned, notReady, notInterested) ex: notYetContacted
source filter on source (available: propertyfinder, portal, socialMedia, online, offline, other) ex: propertyfinder
channel filter on channel. If source is defined, channel must be related to the defined source. ex: dubizzle
created filter on created date. An array or an defined interval. ex: 'from' => '2016-01-01', 'to' => '2017-01-01', or 'current_month'
user filter on the assigned user. ex: 'user' => 1
property filter on the properties selected by the lead. ex: 'property' => 1
created filter on created date. An array or an defined interval. ex: 'from' => '2016-01-01', 'to' => '2017-01-01', or 'current_month'
updated filter on updated date. An array or an defined interval. ex: 'from' => '2016-01-01', 'to' => '2017-01-01', or 'current_month'
legal_representative[name] filter on last name, first name ex: shi sha
legal_representative[mobile] filter on mobile or phone ex: shi sha
legal_representative[email] filter on email ex: shi.sha@gmail.com
passport filter on passport ex: RDR7800
passport_expire filter on passpert expire date. An array or an defined interval. ex: 'from' => '2016-01-01', 'to' => '2017-01-01', or 'current_month'
time_frame_from filter on time frame An array or an defined interval. ex: 'from' => '2016-01-01', 'to' => '2017-01-01', or 'current_month'
financial filter on financial ('cash', 'mortgage', 'other' ex: other
mortgage_status filter on mortgage status ('pre-approved', 'in-process', 'not-pre-approved' ex: not-pre-approved
bank filter on bank ex: emirates nbd
quality filter on quality ('spam', 'poor', 'average', 'good', 'excellent', 'hot' ex: average
address filter on address ex: jlt
pobox filter on pobox ex: 11987
city filter on city ex: dubai
country filter on country (2 chars) ex: AE
property_fields filter on custom fields added in property ex: fields => ['1' =>'shi']
lead_fields filter on custom fields added in lead ex: lead_fields => ['1' =>'shi']

You also can filter on lead's wishlist with the key wishlist in filters and define:

Name Comment Value
locations filter on location ex: [are.1.1]
from_price filter on from price (wishlist) ex: 50000
to_price filter on to price (wishlist) ex: 1000000
from_size filter on from size (wishlist) ex: 250
to_size filter on to size (wishlist) ex: 400
from_bathroom filter on from bathroom (wishlist) ex: 3
to_bathroom filter on to bathroom (wishlist) ex: 5
from_bedroom filter on from bedroom (wishlist) ex: 3
to_bedroom filter on to bedroom (wishlist) ex: 5
category filter on category (available: residential, commercial) ex: residential
types filter on property type (wishlist) ex: [2]

Curl example :

$ curl -X GET 'http://api-v2.mycrm.com/leads?filters[client]=1'

Curl example with custom fields:

$ curl -X GET 'http://api-v2.mycrm.com/leads?filters[property_fields]['1']=test&$filters[lead_fields]['2']=test'
  • Sorts (possible values are ASC or DESC for all sorts). Default value is ASC:
Name
id
last_name
email
mobile
user
status
created
size
type
time_frame
price

Curl example :

$ curl -X GET 'http://api-v2.mycrm.com/leads?sort=id&sort_order=DESC'
  • JSON response:
Name Type Read-only Comment
id integer yes Automatically assigned when the lead is created
user User no User attached to the lead (not expanded by default)
title string no Lead title (mr, ms, miss, mrs)
first_name string no Lead first name
middle_name string no Lead middle name
last_name string no Agent last name
email string no The lead's email
mobile string no The lead's mobile phone
address string no The lead's address
pobox string no The lead's pobox / postalcode
city string no The lead's city
country string no The lead's city
status string no 'notYetContacted', 'calledNoReply', 'prospect', 'qualified', 'viewingsInProgress', 'contractSent', 'contractSigned', 'notReady', 'notInterested'
quality string no 'spam', 'poor', 'average', 'good', 'excellent', 'hot'
financial string no 'other', 'cash', 'mortgage'
mortgage_status string no 'pre-approved', 'in-process', 'not-pre-approved'
source string no 'propertyfinder', 'portal', 'socialMedia', 'online', 'offline', 'other'
channel string no 'callTracking', 'sms', 'email', 'bayut', 'dubizzle', 'gulfNews', 'justProperty', 'justRentals', 'otherPortal', 'facebook', 'twitter', 'google', 'linkedIn', 'otherSocialMedia', 'ourWebsite', 'emailMarketing', 'onlineMarketing', 'otherOnline', 'phone', 'print', 'outdoor', 'expo', 'walkIn', 'referral', 'otherOffline' or a customer field if source is set to other
preferences [Preference] no Wish of the lead, what he looking for
time_frame string no '0','1','2','3','1-3','3-6','6-9','9-12'
created_at datetime yes Lead creation date (W3C format)
updated_at datetime yes Lead updated date (W3C format)
matching Matching yes Matching count for lead

Matching

Name Type Read-only Comment
count integer yes Total matching count
inventory_count integer yes Matching inventory properties count
mls_count integer yes Matching mls properties count

Here the wishlist data description:

Name Type Read-only Comment
types Type no type of the preference
locations Location no Location of the preference
from_price integer no Min price
to_price integer no Max price
from_size integer no Min size
to_size integer no Max size
from_bathroom integer no Min bathroom
to_bathroom integer no Max bathroom
from_bedroom integer no Min bedroom
to_bedroom integer no Max bedroom

Additional fields available with the expand headers:

Name Type Read-only Comment
user User[] no Full object
notes Note[] no array of Full object
preferences [Preference] no array of Full object (it will always be one if any)
  • JSON response example:
{
  "lead": {
    "id":                    35436,
    "first_name":            "Johnny",
    "last_name":             "Trump",
    "email":                 "johnny.t@gmail.om",
    "mobile":                "0478524147",
    "address":               "Dubai Marina",
    "pobox":                 "15109",
    "city":                  "Dubai",
    "country":               "UAE",
    "status":                "prospect",
    "quality":               "good",
    "financial":             null,
    "mortgage_status":       null,
    "source":                null,
    "channel":               null,
    "time_frame":            "0",
    "user": {
      "id":           1
    },
    "preferences":[ {
        "id" :                 "1",
         "locations":[{
             "id": "are.3.1200",
             "city": "Dubai",
             "community": "Jumeirah Lake Towers",
             "sub_community": "Lake Almas West",
             "tower": "Wind Tower 1",
             "latitude": 25.067359024462,
             "longitude": 55.137580800802
        }],
        "from_price":          120000,
        "to_price":            125000,
        "from_size":           900,
        "to_size":             1200,
        "from_bathroom":       2,
        "to_bathroom":         3,
        "from_bedroom":        2,
        "to_bedroom":          3,
        "offering_type":       "residential",
        "types": [{
            "id":2,
            "name": "Apartment",
            "category": "residential"
        }],
    } ],
    "created_at":            "2009-07-20T22:55:29Z",
    "updated_at":            "2011-05-05T10:38:52Z",
    "amenities": [{
          "id": 1,
         "name": "swimming pool"
    }],
    "fields": {
        "1": "2 pets", // id of the field => value of the field
        "3": true
      }
  }
}

The header X-MyCRM-Expand-Data will provide some additional data:

{
  "lead": {
    "id":                    35436,
    "first_name":            "Johnny",
    ...
    "user": {
      "id":           1,
      "first_name":   "Jean",
      "last_name":    "Pac",
      ...
    },
    "notes": [
      {
        "id": 935,
        "body": "This is a note",
        ...
      },
    ],
    "created_at":            "2009-07-20T22:55:29Z",
    "updated_at":            "2011-05-05T10:38:52Z",
  }
}

Get Leads

  • Endpoint:
GET /leads
  • Allowed for:

users that has right lead.read

  • JSON response:

This endpoint will return a list of Lead.

  • JSON response example:
{
  "leads": [
    {
      "id": 223443,
      "first_name": "Johnny",
      "preferences": []
      ...
    },
    {
      "id": 8678530,
      "first_name": "James",
       "preferences": [{
             "locations": [{
                   "id": "are.3.1200",
                   "city": "Dubai",
                   "community": "Jumeirah Lake Towers",
                   "sub_community": "Lake Almas West",
                   "tower": "Wind Tower 1",
                   "latitude": 25.067359024462,
                   "longitude": 55.137580800802
             }],
              "from_price":          120000,
              "to_price":            125000,
              ....
       }]
      ...
    }
  ]
}

Create Lead

  • Endpoint:
POST /leads
  • Allowed for:

users that has right lead.update

  • JSON request
Name Type Mandatory Comment
title string yes Lead title
first_name string yes Lead first name
middle_name string no Lead middle name
last_name string yes Lead last name
email string no The lead's email
mobile string yes The lead's mobile phone
category string yes The property category for lead's search
address string no The lead's address
pobox string no The lead's pobox / postalcode
city string no The lead's city
country string yes The lead's country
status string yes The lead's status
quality string no The lead's quality
source string yes The lead's source
source_channel string yes The lead's source
financial string yes The lead's financial
mortgage_status string no The mortgage status
user integer no The user attached to the lead - permission lead.update.other required
preference array yes Wish of the lead, what he looking for
notes Note no The lead's notes
properties Note no The properties selected by the lead
fields array  depends on feilds custom field list

Here the wishlist data description:

Name Type Mandatory Comment
types Type yes types of the preference
locations array yes Location IDs of the preference
from_price integer yes Min price
to_price integer yes Max price
from_size integer no Min size
to_size integer no Max size
from_bathroom integer no Min bathroom
to_bathroom integer no Max bathroom
from_bedroom integer no Min bedroom
to_bedroom integer no Max bedroom
offering_type string yes Offering Type of preference
amenities array yes Amenity IDs of the preference
  • JSON request example:
{
  "lead": {
      "id": 223443,
      "first_name": "Johnny",
      ...
      "notes": [
      "offering_type": "sale",
      "preference": {
          "locations":            ["are.2.15"],
          "from_price":          120000,
          "to_price":            125000,
          "from_size":           900,
          "to_size":             1200,
          "from_bathroom":       2,
          "to_bathroom":         3,
          "from_bedroom":        2,
          "to_bedroom":          3,
          "types": [2],
          "amenities": [1, 2]
      },
      ...
      notes: [
        {
            "body": "My note"
        }
      ],
      "properties": [1, 2, 3]
  },
}
  • JSON response:

This endpoint will return a Lead.

Update Lead

  • Endpoint:
PUT /leads/{id}
  • Allowed for:

users that has right lead.update

  • JSON request

The mandatory fields are similar than lead creation.

  • JSON request example:
{
  "lead": {
      "id": 223443,
      "first_name": "Johnny",
       "offering_type": "sale",
      "preference": {
            wishlist list  attribs
      }
      ...
  },
}
  • JSON response:

This endpoint will return a Lead.

Delete Lead

  • Endpoint:
DELETE /lead/{id}
  • Allowed for:

users that has right lead.update

  • JSON response:

This endpoint will return a 204 http code if success.

Patch

PATCH /leads/1
  • Allowed for:

users that has right lead.update (state action) users that has right lead.update, user.update (assignment action) users that has right lead.update, property.read (assignment action)

  • JSON request:

Some actions are available:

Change the status:

Name Type Mandatory Comment
op string yes Operation to execute (replace)
path string yes Path "/id/status" to update the state. id must be an integer or the wildcard *
value object yes state value data

Assign a lead to an agent:

Name Type Mandatory Comment
op string yes Operation to execute (replace)
path string yes Path "/id/assignment/user" to update the assignment. id must be an integer or the wildcard *
value integer yes Agent ID
  • JSON request example with mixed operations:
{
    "operations": [
        {"op": "replace", "path": "/status", "value": "notYetContacted"},
        {"op": "replace", "path": "/assignment/user", "value": "2" },
        {"op": "add", "path": "/assignment/property", "value": 3},
        {"op": "remove", "path": "/assignment/property", "value": 1},
        {"op": "add", "path": "/assignment/mls", "value": 112345},
        {"op": "remove", "path": "/assignment/mls", "value": 112345}
    ]
}
  • JSON response:

Will return a 204 http code.

Bulk Actions

PATCH /leads
  • Allowed for:

users that has right lead.update (state action) users that has right lead.update, user.update (assignment action) users that has right lead.update, property.read (assignment action)

  • JSON request:

Some actions are available:

Change the status:

Name Type Mandatory Comment
op string yes Operation to execute (replace)
path string yes Path "/id/status" to update the state. id must be an integer or the wildcard *
value object yes state value data

Assign a lead to an agent:

Name Type Mandatory Comment
op string yes Operation to execute (replace)
path string yes Path "/id/assignment/user" to update the assignment. id must be an integer or the wildcard *
value integer yes Agent ID
  • JSON request example with mixed operations:
{
    "operations": [
        {"op": "replace", "path": "/1/status", "value": "notYetContacted"},
        {"op": "replace", "path": "/1/assignment/user", "value": "2" },
        {"op": "add", "path": "/1/assignment/property", "value": 3},
        {"op": "remove", "path": "/1/assignment/property", "value": 1},
        {"op": "add", "path": "/1/assignment/mls", "value": 112345},
        {"op": "remove", "path": "/1/assignment/mls", "value": 112345}
    ]
}
  • JSON response:

Will return a 204 http code.

Bulk Deletes

DELETE /leads
  • Allowed for:

users that has right lead.update

  • JSON request:

An array of property ID. If you don't pass any ID, it will delete all leads.

  • JSON request example:
{
    "leads": [
        1, 2, 3
    ]
}
  • JSON response:

Will return a 204 http code.