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"]`

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 source tags which use the Lead Source Update Behavior option. 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.

This API does not return any content. A 200 OK response should be considered as a confirmation of the change.
If the user does not have permissions on the lead, the reassignment will fail.
Reassignment results in a notification to the user the lead was assigned to.

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.

This API does not return any content. A 200 OK response should be considered as a confirmation of the change.
If the user does not have permissions on the lead, the reassignment will fail.

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

User scope is ignored if access token does not belong to a super admin

The response consists of three parts:

Matching elements

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

Display elements

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

Identifier element

Parameter	Description
lead_id	Id of the lead for further fetch

Search leads by ids

Search for leads with given ids.

Resource URL

GET /companies/<company_uuid>/leads/search/ids

JSON Parameters

Parameter	Description
ids	required List of lead ids to search

Example Request

curl https://api.metroleads.com/companies/<company_uuid>/leads/search/ids?ids=["633102bf-cbe7-43dc-90dd-89924797dae5", "945d695e-1797-4ca9-9c47-a9f9a277d314"]

Example Response

[
    {
        "allow_unmerge": false,
        "lead_id": "c3441a01-859e-48bf-ad59-69c91ee4a467",
        "source_tags": [
            "Roof And Floor",
            "disposition_answered",
            "disposition_missed"
        ],
        "lead_creation_time": "2019-01-09T11:50:51Z",
        "phones": [
            {
                "phone": "+12025551234",
                "type": "Work"
            }
        ],
        "lead_group": "5636140f-2ecd-44da-838f-be860d516f32",
        "lead_fields": {
            "customer_id_070": [
                "#1970"
            ]
        },
        "state": "open",
        "assigned_to": {
            "name": "Eugène Delacroix",
            "id": "bc4b25fc-bd01-4749-9647-f93cc2e17e16"
        },
        "user_assigned_to": "bc4b25fc-bd01-4749-9647-f93cc2e17e16",
        "emails": [
            {
                "type": "Work",
                "email": "asdf@asdf.com"
            }
        ],
        "name": "Mythili"
    },
    {
        "allow_unmerge": false,
        "lead_id": "bfaeef14-eb35-4bb8-bafd-3f264aa7e3a6",
        "source_tags": [
            "disposition_answered"
        ],
        "lead_creation_time": "2020-09-08T12:22:52Z",
        "phones": [
            {
                "phone": "+12025554567",
                "type": "Work"
            }
        ],
        "lead_group": "5636140f-2ecd-44da-838f-be860d516f32",
        "lead_fields": {
            "customer_id_070": [
                "#1977"
            ]
        },
        "state": "contacted",
        "assigned_to": {
            "name": "Mark Roberts",
            "id": "48d58b40-a31b-445b-bc0c-c8726e2c6641"
        },
        "user_assigned_to": "48d58b40-a31b-445b-bc0c-c8726e2c6641"
    }
]

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"
        }
    ]
}