DocsBuilding AppsInstalling IntercomAPI & Webhook ReferenceCanvas Kit Reference
DocsApp StoreForumBlogYour Apps

List by Tag, Segment, Company

Example Tag Request

$ curl https://api.intercom.io/users?tag_id=3142 \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
intercom.users.find_all({ :tag_id => '30126' })
<?php
$user = $intercom->users->getUsers(["tag_id" => '730128']);
print_r($user->users[0]->email);
echo "\n";
?>
Map<String, String> params = Maps.newHashMap();
params.put("tag_id", "30126");
UserCollection users = User.list(params);
while (users.hasNext()) {
    out.println(users.next().getId());
}
Example Segment Request

$ curl https://api.intercom.io/users?segment_id=5926 \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept:application/json'
HTTP/1.1 200 OK

{
  "type": "user.list",
  "total_count": 105,
  "users": [
    {
      "type": "user",
      "id": "530370b477ad7120001d",
       ...
     },
     ...
  ],
  "pages": {
    "next": "https://api.intercom.io/users?tag_id=3142&per_page=50&page=2",
    "page": 1,
    "per_page": 50,
    "total_pages": 3
  }
}

# NB: Full User objects are returned
intercom.users.find_all({ :segment_id => '30126' })
<?php
$user = $intercom->users->getUsers(["segment_id" => '58135df83917e42135b2ea29']);
print_r($user->users[0]->id);
echo "\n";
?>
Map<String, String> params = Maps.newHashMap();
params.put("segment_id", "30126");
UserCollection users = User.list(params);
while (users.hasNext()) {
    out.println(users.next().getId());
}

You can fetch segmented users/leads by querying the users resource with a segment_id parameter, indicating the id of the segment to query with.

To fetch tagged users/leads, you can use a tag_id parameter to indicate the id of the tag. For information on tagging users see the section Tag or Untag Users, Companies & Leads (Contacts).

Note that you can not combine tag and segment parameters in the same request.

To list users belonging to a company, you can use the companies API. See the section List Company Users for details.

Request Parameters

Parameter

Required

Description

tag_id

no

The id of the tag to filter by.

segment_id

no

The id of the segment to filter by.

Returns

A pageable list of users and leads.

Like a plain company list, the result contains a pages object that indicates if more users exist via the next field.