Segments

List segments

List segments in the tenant and project derived from the access token with cursor pagination and optional filters.

Overview

Use this endpoint to list segments without sending cin, projectId, page-number pagination, or user identity fields. objectType is normalized to lowercase, segmentType is matched against the stored uppercase type, and status maps ACTIVE to non-archived segments and ARCHIVED to archived segments. If filters are changed while reusing a cursor, the request is rejected. It requires public api oauth access token authentication and the crm.segments.read scope.

GET/api/segments

cURL

GET

bash

curl --request GET \  --url 'https://crm.notifyy.io/api/segments?objectType=contact&segmentType=ACTIVE&status=ACTIVE&search=high%20value&limit=25' \  --header 'Authorization: Bearer nfy_public_api_access_token' \  --header 'Accept: application/json'

Authorization

Public API OAuth access token

crm.segments.read

Sample Request Body

This endpoint does not require a request body.

Sample Response

json

{  "success": true,  "message": "Segments retrieved successfully",  "data": {    "segments": [      {        "id": 999,        "name": "High value contacts",        "objectType": "contact",        "segmentType": "ACTIVE",        "status": "ACTIVE",        "description": "Segment for high intent contacts",        "currentVersion": 1,        "createdAt": "2026-08-01T09:15:30Z",        "updatedAt": "2026-08-01T09:15:30Z"      }    ],    "pagination": {      "nextCursor": "eyJ2ZXJzaW9uIjoxLCJyZXNvdXJjZSI6InNlZ21lbnRzIiwicGFnZSI6MiwibGltaXQiOjI1LCJvYmplY3RUeXBlIjoiY29udGFjdCIsInNlZ21lbnRUeXBlIjoiYWN0aXZlIiwic3RhdHVzIjoiYWN0aXZlIiwic2VhcmNoIjoiaGlnaCB2YWx1ZSJ9",      "hasMore": true    }  }}

Status Codes

Code	Description
200	Segments were returned.
400	Query parameters are invalid, the status filter is unsupported, or the cursor does not match the current query.
401	Public API access token is missing, invalid, expired, or revoked.

Headers

AuthorizationstringRequired

Public API OAuth bearer token.

Example: Bearer nfy_public_api_access_token

AcceptstringRequired

Expected response media type.

Example: application/json

Object	Description
Authorization string	RequiredPublic API OAuth bearer token. Example: Bearer nfy_public_api_access_token
Accept string	RequiredExpected response media type. Example: application/json

Query parameters

objectTypestringOptional

Lowercase object type filter such as contact, company, deal, ticket, appointment, meeting, product, order, lead, payment, or call.

Example: contact

segmentTypestringOptional

Segment type filter. Public API accepts ACTIVE or STATIC.

Example: ACTIVE

statusstringOptional

Segment lifecycle filter. Supported values are ACTIVE and ARCHIVED.

Example: ACTIVE

searchstringOptional

Case-insensitive segment name search.

Example: high value

limitintegerOptional

Cursor page size. Defaults to 50 and is capped at 100.

Example: 25

cursorstringOptional

Opaque cursor returned by a previous list response. Reuse it only with the same query filters and the same limit.

Object	Description
objectType string	OptionalLowercase object type filter such as contact, company, deal, ticket, appointment, meeting, product, order, lead, payment, or call. Example: contact
segmentType string	OptionalSegment type filter. Public API accepts ACTIVE or STATIC. Example: ACTIVE
status string	OptionalSegment lifecycle filter. Supported values are ACTIVE and ARCHIVED. Example: ACTIVE
search string	OptionalCase-insensitive segment name search. Example: high value
limit integer	OptionalCursor page size. Defaults to 50 and is capped at 100. Example: 25
cursor string	OptionalOpaque cursor returned by a previous list response. Reuse it only with the same query filters and the same limit.

Public Response Shape

The public list response excludes internal tenant and actor fields from BAU, including cin, projectId, createdBy, updatedBy, ownerId, and any internal project or user identifiers in query params.

Field

Type

integer

Description

Segment identifier.

Field

name

Type

string

Description

Segment name.

Field

objectType

Type

string

Description

Lowercase CRM object type.

Field

segmentType

Type

string

Description

Stored segment type such as ACTIVE or STATIC.

Field

status

Type

string

Description

Derived lifecycle state: ACTIVE or ARCHIVED.

Field

description

Type

string

Description

Segment description.

Field

currentVersion

Type

integer

Description

Current filter version if present.

Field

createdAt

Type

datetime

Description

Segment creation timestamp.

Field

updatedAt

Type

datetime

Description

Segment update timestamp.

Field	Type	Description
id	integer	Segment identifier.
name	string	Segment name.
objectType	string	Lowercase CRM object type.
segmentType	string	Stored segment type such as ACTIVE or STATIC.
status	string	Derived lifecycle state: ACTIVE or ARCHIVED.
description	string	Segment description.
currentVersion	integer	Current filter version if present.
createdAt	datetime	Segment creation timestamp.
updatedAt	datetime	Segment update timestamp.

Response fields

successboolean

Whether the request succeeded.

Example: true

messagestring

Human-readable result message.

Example: Segments retrieved successfully

data.segmentsobject[]

List of matching segments.

data.pagination.nextCursorstring | null

Cursor for the next page.

data.pagination.hasMoreboolean

Whether another page is available.

Example: true

Object	Description
success boolean	Whether the request succeeded. Example: true
message string	Human-readable result message. Example: Segments retrieved successfully
data.segments object[]	List of matching segments.
data.pagination.nextCursor string \| null	Cursor for the next page.
data.pagination.hasMore boolean	Whether another page is available. Example: true