Get segment

If you have questions regarding this API, please visit our API FAQ page.

Retrieving a segment

Make a GET request to https://webapi.inboxroad.com/api/v2/segments/{segment_id}/ with a valid X-API-Key. The response includes the segment’s full rule definition.

curl -X GET 'https://webapi.inboxroad.com/api/v2/segments/{segment_id}/' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Path parameters

Param name	Description
segment_id	Unique identifier of the segment (UUID).

Response fields

Field name	Description
id	Unique identifier of the segment (UUID).
name	Name of the segment.
color	Hex color assigned to the segment.
description	Description of the segment (may be null).
rules_json	The segment definition. See Segment rules.
contact_list_ids	Contact list ids (UUIDs) the segment draws from.
status	Build state: PENDING, RUNNING, DONE, or FAILED. FAILED means the rules could not be built — see when rules are checked.
total_count	Number of matching contacts. Only meaningful when status is DONE.
created_at	Date and time the segment was created.
updated_at	Date and time the segment was last updated.
display_fields	Default columns to surface when rendering this segment’s contacts (see below).

Display field object (display_fields[])

Field name	Description
label	Human-readable field label.
contact_column_name	Underlying contact column key.
data_type	Data type of the field.
choices	Allowed values for choice fields, or null.

Example response

{
  "id": "92a6ef72-c74e-4e37-bd84-9e8fbb83fef4",
  "name": "Active Gmail Subscribers",
  "color": "#7cb7de",
  "description": "Subscribed users who opened in the last 30 days",
  "rules_json": {
    "any": [
      {
        "all": [
          { "kind": "field", "field": "status", "operator": "equals", "value": "subscribed" },
          { "kind": "activity", "metric": "open", "operator": "count_gte", "value": 1,
            "days_window": { "mode": "last", "days": 30 } }
        ]
      }
    ]
  },
  "contact_list_ids": ["0fd3d5b4-1c0a-4e91-8a4f-0f17dc6dc5ab"],
  "status": "DONE",
  "total_count": 1824,
  "created_at": "2026-05-10T09:00:00Z",
  "updated_at": "2026-05-21T11:15:00Z",
  "display_fields": [
    { "label": "Email", "contact_column_name": "email", "data_type": "email", "choices": null }
  ]
}

Possible response codes

Status code	Description
200	Segment retrieved successfully.
400	Segment not found, or not owned by your account.
401	Unauthorized.
422	segment_id is not a valid UUID.
429	Rate limit exceeded. See Rate limiting.