Get users (leads)

Get leads. A visitor is considered as a “lead” if: * Name is defined (user property $name) * Email is defined (user property $email), * Phone is defined (user property $phone) * User ID is defined * User is subscribed to web-push * Has conversations

We use this method in the "Leads" admin panel section.

URL

GET https://api.dashly.app/apps/{id}/users

Parameters

Auth parameters.
id_as_string parameter.

Parameter	Type	Description
filters	Filters object	Defaults to all users
sort_prop	Optional[string]	User property to sort lead by before pagination. Defaults to $last_seen (last activity)
sort_order	Optional[asc/desc]	Sort order (asc for ascending order, desc for descending order). Defaults to desc
offset	Optional[integer]	Pagination. Start offset. Defaults to 0
limit	Optional[integer]	Pagination. Maximum number of users to fetch (from 1 to 50, defaults to 20)
convert_props_types	Optional[boolean]	Defaults to true. If not set (false), user properties are returned as strings

Note: optional fields of User object can not be included in this query.

Remarks

By default, all leads (without filters) are returned. To find the ones you need, use the filters field. For example, to get only leads from a given segment, those who came during current day or get leads by name, email, etc.

The data returned by this method is updated with a several minutes delay. Therefore, it may differ from the data in the lead card (if it has not updated yet).

Pagination in this method is slightly different from pagination in other methods. Instead of the usual paginate_position and paginate_count, offset and limit parameters are used. In case of receiving a large number of leads through pagination, extra may be added to the list. Therefore, it is possible that the same user will be in several consecutive requests.

For example, if offset=0, limit=20 for the first request, offset=20, limit=20 for the second request, and one new user is added between the calls at the top, then the twentieth user on the first call will be the first on the second call. You need to check the ID on your side to exclude duplicates. Another option is to use export to get a large number of users at a time (in this case we solve this problem for you).

You can not get more than 10000 leads using this method. This is a technical limitation. If you set offset + limit more than 10000 it will lead to an error. If you want to fetch many leads, please, use leads export feature in admin panel.

If the returned users are less than limit, then all users are returned. For example, if you get 5 users with limit=20, this means that all users are returned.

Answer

{
  "meta": {
    "status": 200
  },
  "data": {
    "total": 245,
    "users": [
      {
        "id": 3568,
        "presence": "offline",
        "props": {
          "$event_18_first": "2014-06-15T22:14:08",
          "$event_18_last": "2014-06-23T07:50:46",
          "$event_18_count": 4,
          "$last_contacted": "2016-02-12T15:33:31",
          "$email": "maks@gmail.com",
          "$sessions": 1,
          "$last_seen": "2014-06-17T08:56:03",
        }
      },
      ...
    ]
  }
}

The answer will contain an array with users.

The total field contains the total number of users who satisfy the specified filters.

The users field contains an array of users. The used format is slightly different from the usual User object.

Each user contains the fields: id (user id), presence (status) and props (properties).

More about user properties and user status

Example

curl -X GET  -H "Authorization: Token XXX" "https://api.dashly.app/apps/$self_app/users"