Lead Queries

You can get more details about Lead data structure from here

Queries

Get a lead

Retrieves complete information for a lead.

Resource URL

GET /companies/<company_uuid>/leads/<lead_uuid>

Example Request

curl "https://api.metroleads.com/companies/c5dff108-7b2c-4e30-8203-d359d9dcf6b1/leads/d3cdf0e8-9cf4-4206-9ef8-0eaf12941593"

Example Response

{
  "lead_id": "d3cdf0e8-9cf4-4206-9ef8-0eaf12941593",
  "name": "John Doe",
  "source_tags": [
    "Google Organic"
  ],
  "emails": [
    {
      "type": "Work",
      "email": "john@example.com"
    },
    {
      "type": "Personal",
      "email": "john@example.net"
    }
  ],
  "phones": [
    {
      "phone": "+15552221111",
      "type": "Work"
    },
    {
      "phone": "+15553332222",
      "type": "Mobile"
    }
  ],
  "state": "open",
  "assigned_to": {
    "name": "Mark Kelley",
    "id": "1cf095b5-b7c4-4058-8c03-2c64a3d8bff3"
  },
  "lead_group": "d0260355-1760-4c96-982e-733536d5fae5",
  "lead_fields": {
    "simple_text_field": [
      "single_value"
    ],
    "multiple_simple_fields": [
      "value_a", "value_b", "value_c"
    ],
    "date_field": [
      "2014-10-01"
    ],
    "date_time_field": [
      "2015-02-16T07:00:00Z"
    ],
    "multiselect_field": [
      [
        "value_a1",
        "value_a2"
      ]
    ],
    "currency_field": [
      {
        "unit": "EUR",
        "value": 100000
      }
    ],
    "url_field": [
      "https://metroguild.com"
    ],
    "complex_field_address": [
      {
        "state": [
          "CA"
        ],
        "zip_code": [
          "90274"
        ],
        "coutry": [
          "USA"
        ],
        "address_line_1": [
          "1 Rodeo Drive"
        ]
      }
    ]
  },
  "last_event_time": 1435101010
}

Create a Lead

Creates a new lead with identifiers. Returns the list of created lead ids. Generally this is a list that contains only one lead id.

Resource URL

POST /companies/<company_uuid>/leads/create

JSON Body Parameters

Parameter Description
email required Email address of the lead
phone required Phone of the lead
source_tags List of source tags to be set for the lead. E.g. ["Google Ads"]
additional_source_tags List of source tags added to the existing list on the lead. E.g. ["AOL"]. additional_source_tags should not be used with source_tags

Any one of email or phones is mandatory.

Example Request

curl "https://api.metroleads.com/companies/c5dff108-7b2c-4e30-8203-d359d9dcf6b1/leads/create" -d '{"phone":"+919916991010","source_tags":[""]}'

Example Response

{
  "lead_ids": ["73a882fc-678b-4e35-9fe9-b5675e22ddd0"]
}

Modify a lead

Updates lead with new information.

Resource URL

POST /companies/<company_uuid>/leads/<lead_uuid>/modify

JSON Parameters

A valid JSON containing parameters that need to be updated for the lead. Refer to create lead for basic parameters.

Example Request

curl https://api.metroleads.com/companies/<company_uuid>/leads/<lead_uuid>/modify -X POST -H "Content-Type: application/json" -d '{'valid': 'json'}'

Example Response

Returns the affected lead ids

{
    "lead_ids": [
        "ad7d8cc5-ef6d-46dc-b1e0-27532063d2f8"
    ]
}

The examples below show what a request JSON as POST body might look like

Example Request Body JSON - Updates name for lead

{ "name": "John D" }

Example Request Body JSON - Updates name for lead

{
  "lead_fields": {
    "multiselect_field": [
      [
        "value_a1",
        "value_a2",
        "value_a3",
        "value_a4",
        "value_a5",
        "value_a6"
      ]
    ]
  }
}

Example Request Body JSON - Updates a lead field that has count > 1 with 2 values

{
  "lead_fields": {
    "submitted": [
      "2015-06-25T18:30:00Z",
      "2015-06-05T18:30:00Z"
    ]
  }
}

Upsert a Lead

A special case API that uses the create semantics to either create a lead if not present and update if already present. The API resolves existing leads using the identifiers sent as part of create lead parameters such as phone/email. Please see parameters for create or update lead.

Please note an update will overwrite existing data for the lead fields. Exceptions are created to append source tags using additional_source_tags parameter. Please use upsert carefully.

Resource URL

POST /companies/<company_uuid>/leads/upsert

Assign a lead

Assigns the lead to a user based on the user email.

Resource URL

POST /companies/<company_uuid>/leads/<lead_uuid>/assign

JSON Parameters

Parameter Description
to_user_email required Email of the user to assign to

Example Request

curl https://api.metroleads.com/companies/<company_uuid>/leads/<lead_uuid>/assign -X POST -H "Content-Type: application/json" -d '{"to_user_email":"mark@example.com"}'

Unassign a lead

Unassigns the lead.

Resource URL

POST /companies/<company_uuid>/leads/<lead_uuid>/unassign

JSON Parameters

Parameter Description
from_user_email required Email of the user it is currently assigned to. This is used to avoid race/stale conditions.

Example Request

curl https://api.metroleads.com/companies/<company_uuid>/leads/<lead_uuid>/unassign -X POST -H "Content-Type: application/json" -d '{"from_user_email":"mark@example.com"}'

Search leads

Search for leads with the given query. The search by default is performed only within the basic fields; name, phone, and email for a lead. To expand your search in custom lead fields, please use search_fields parameter.

Resource URL

GET /companies/<company_uuid>/leads/search

JSON Parameters

Parameter Description
q required Search query which should be minimum 3 characters in length.
user_scope Search for leads within this user's scope.
search_fields Comma separated list of fields to limit search in. For complex fields, the format is complex-field-name.sub-field-name. E.g. address.city
exclude_notes Set to true or 1 if want to exclude notes. Default true
exclude_emails Set to true or 1 if want to exclude emails. Default true
exclude_reminders Set to true or 1 if want to exclude reminders. Default true

Example Request

curl https://api.metroleads.com/companies/<company_uuid>/leads/search?q=john&user_scope=mark@example.com

Example Response

[
  {
    "lead_id": "c6b054f0-c281-11e4-b5ee-0000f9130006",
    "phone": "+1115991010",
    "user_assigned_to": "462caf85-0000-0000-0000-0b77b8a0ca7e",
    "field_value": "John Doe",
    "field_name": "name",
    "search_field_name": "name",
    "email": "john.doe@example.com",
    "name": "John Doe"
  },
  {
    "lead_id": "0d6a0cbc-0000-0000-0000-0680f913eb06",
    "phone": "+1115991212",
    "user_assigned_to": "cd3308f7-0000-0000-0000-807ec4050000",
    "field_value": "John Bobby",
    "search_field_name": "name",
    "field_name": "name",
    "email": "john.bobby6@example.com",
    "name": "John Bobby"
  }
]

Notes

The response consists of three parts:

Parameter Description
search_field_name The internal field name that is passed in the search query and matched with the result.
field_name The readable field name in which the query result was found
field_value Value of the field

Depending on the data present in the lead, all fields are optional but at least one will be returned for display purposes

Parameter Description
name Name of the lead
phone Any one phone of the lead
email Any one email of the lead
Parameter Description
lead_id Id of the lead for further fetch

Merge leads

API will allow to merge all fields of primary lead (which is in the URL path) to the secondary lead (which is with parameter). It will keep all the non-conflicting fields of both the leads. In case of conflicting fields, primary lead field will get priority. To prioritize fields of secondary lead, list of fields can be passed in retain_fields parameters. If you want to retain both field values, (union them), merge_fields parameter can be used.

The API returns the id of the merged lead

Resource URL

POST /companies/<company_uuid>/leads/<primary_lead_uuid>/merge

JSON Body Parameters

Parameter Description
with required Secondary lead id
retain_fields List of fields to be retained from the secondary lead in case of field conflict.
merge_fields List of fields to be merged in case of conflict. These fields will be merged from both leads.

Example Request

curl -X POST https://api.metroleads.com/companies/e0f6e62a-12f6-4e45-83e1-adeca63cbe98/leads/1a31a2a2-6043-4801-86f5-307a0214ef3e/merge -H "Content-Type: application/json" -d '{"with": "202939bc-fd72-41f1-843a-db8123521fc2", "retain_fields": "name", "merge_fields": "address"}'

Example Response

{
  "status": "success",
  "merged_lead_id": "2282c053-c14e-4f1f-bbf1-7bd4eb490880"
}

Change state

Changes the state to the name and returns affected lead ids.

Resource URL

POST /companies/<company_uuid>/leads/<lead_uuid>/change_state

JSON Body Parameters

Parameter Description
state required Name of the state to set

Example Request Body

{"state":"open"}

Example Response

{
  "lead_ids": ["9aec9a25-9f03-4b16-9f33-5cdb3306d1e4"]
}

Recent Leads

Lists recently modified leads. Used primarily for streaming changes information.

Resource URL

GET /companies/<company_uuid>/leads/recent_leads

JSON Body Parameters

Parameter Description
tz_offset Offset in mins from GMT (e.g. 330 for India (+05:30))
relative Lead modified relative (e.g. last_month, last_week)
from Lead modified from date. An ISO timestamp e.g. 2019-11-07T23:59:59Z
to Lead modified to date. An ISO timestamp e.g. 2019-12-07T23:59:59Z
created_relative Lead created time relative (e.g. last_month, last_week)
created_from Lead created from date. An ISO timestamp e.g. 2019-11-07T23:59:59Z
created_to Lead created to date. An ISO timestamp e.g. 2019-12-07T23:59:59Z

Any of the relative or (from, to) is required to limit data. Data is currently limited to a 7 day window and maximum 500 results.

Please refer to Relative Date Range Constants for valid relative date values.

Example Request Body

{"tz_offset":330, "relative":"this_month", "created_relative": "this_month"}

Example Response

{
    "count": 1,
    "leads": [
        {
            "lead_id": "de1e49fd-26d4-4d05-96c4-b4e5e9ac7c62",
            "source_tags": [
                "Website"
            ],
            "lead_creation_time": "2019-11-15T10:01:39Z",
            "phones": [
                {
                    "phone": "+919916991010",
                    "type": "Work"
                }
            ],
            "lead_group": "5636140f-2ecd-44da-838f-be860d516f32",
            "state": "unqualified",
            "assigned_to": {
                "name": "Ram Joshi",
                "id": "eb2bc9aa-2470-4024-8606-484c96360861"
            },
            "emails": [
                {
                    "type": "Work",
                    "email": "ram.joshi@example.com"
                }
            ],
            "name": "Ram Joshi"
        }
    ]
}