Retrieve a segment

Request

You can fetch the details of a single segment.

The segment name is returned HTML-escaped, for example & as &.

Requires the read_users_companies or write_users_companies OAuth scope.

Security

bearerAuth

Path

segment_idstringrequired

The unique identified of a given segment.

Example:123

Query

include_countboolean

Includes the count of contacts that belong to the segment. The count is added whenever this parameter has a value in the query string, even false or an empty one, so omit it entirely to leave it out. A bare include_count with no = adds no count.

Example:include_count=true

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

curl -i -X GET \
  'https://api.intercom.io/segments/123?include_count=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

Successful response

Bodyapplication/json

typestring

The type of object.

Value:"segment"

Example:"segment"

idstring

The unique identifier representing the segment.

Example:"56203d253cba154d39010062"

namestring

The name of the segment.

Example:"Active"

created_atinteger

The time the segment was created.

Example:1394621988

updated_atinteger

The time the segment was updated.

Example:1394622004

person_typestring

Type of the contact: contact (lead) or user.

Enum:"contact""user"

Example:"contact"

countinteger or null

The number of items in the user segment. It's returned when the request has include_count with a value. A company segment only gets a count when a contact segment has the same name, and it shows that segment's count.

Example:3

Response

{
  "type": "segment",
  "id": "6762f25f1bb69f9f2193bc26",
  "name": "John segment",
  "created_at": 1734537823,
  "updated_at": 1734537823,
  "person_type": "user"
}