List segments

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

Listing segments

Make a GET request to https://webapi.inboxroad.com/api/v2/segments/ with a valid X-API-Key.

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

Response fields

Field name	Description
pagination	Pagination metadata for the results.
items	List of segment objects.

Segment object

Field name	Description
id	Unique identifier of the segment (UUID).
name	Name of the segment.
color	Hex color assigned to the segment.
status	Build state: PENDING, RUNNING, DONE, or FAILED.
total_count	Number of matching contacts. Only meaningful when status is DONE; otherwise null.
created_at	Date and time the segment was created.
updated_at	Date and time the segment was last updated.

Note

Segments are built asynchronously. A freshly created or recently edited segment has status PENDING/RUNNING and a null total_count until its build completes (DONE).

Example response

{
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_count": 8,
    "total_pages": 1
  },
  "items": [
    {
      "id": "92a6ef72-c74e-4e37-bd84-9e8fbb83fef4",
      "name": "Active Subscribers",
      "color": "#7cb7de",
      "status": "DONE",
      "total_count": 1824,
      "created_at": "2026-05-10T09:00:00Z",
      "updated_at": "2026-05-21T11:15:00Z"
    }
  ]
}

Query parameters

Param name	Possible values	Description
page	Integer	1-based page number. Default 1.
page_size	Integer	Results per page. Default 25.
search	String	Search segments by name.
ordering	asc, desc	Sort direction. Default desc.
order_by	name, total_count, created_at, updated_at	Field to sort by. Default updated_at.

For example:

curl -X GET 'https://webapi.inboxroad.com/api/v2/segments/?page=1&page_size=10&order_by=name&ordering=asc' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Pagination

Field name	Description
page	Current page number.
page_size	Number of results per page.
total_count	Total number of segments.
total_pages	Total number of available pages.