Segments

Create a segment

Create an ACTIVE or STATIC CRM segment in the tenant and project derived from the access token.

Overview

Use this endpoint to create a CRM segment for one supported object type. ACTIVE segments require a filters payload. STATIC segments can be created without filters, and if filters are supplied, member resolution runs during creation. The public segment create flow routes by the segment objectType and reuses the shared BAU segment engine instead of a separate public-only implementation. It requires public api oauth access token authentication and the crm.segments.write scope.

POST/api/segments

cURL

POST

bash

curl --request POST \  --url 'https://crm.notifyy.io/api/segments' \  --header 'Authorization: Bearer nfy_public_api_access_token' \  --header 'Content-Type: application/json' \  --header 'Accept: application/json' \  --data '{  "name": "High value contacts",  "objectType": "contact",  "segmentType": "ACTIVE",  "description": "Segment for high intent contacts",  "filters": {    "logic": "AND",    "groups": [      {        "logic": "AND",        "filters": [          {            "propertyId": 101,            "property": "lifecyclestage",            "operator": "equals",            "value": "customer"          },          {            "propertyId": 102,            "property": "created_ts",            "operator": "LAST_N_DAYS",            "value": "30"          }        ]      }    ]  }}'

Authorization

Public API OAuth access token

crm.segments.write

Sample Request Body

json

{  "name": "High value contacts",  "objectType": "contact",  "segmentType": "ACTIVE",  "description": "Segment for high intent contacts",  "filters": {    "logic": "AND",    "groups": [      {        "logic": "AND",        "filters": [          {            "propertyId": 101,            "property": "lifecyclestage",            "operator": "equals",            "value": "customer"          },          {            "propertyId": 102,            "property": "created_ts",            "operator": "LAST_N_DAYS",            "value": "30"          }        ]      }    ]  }}

Additional Examples

Equality filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 101,          "property": "lifecyclestage",          "operator": "EQUALS",          "value": "customer"        }      ]    }  ]}

Numeric comparison filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 201,          "property": "amount",          "operator": "GT",          "value": "1000"        }      ]    }  ]}

String contains filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 301,          "property": "email",          "operator": "CONTAINS",          "value": "@notifyy.io"        }      ]    }  ]}

IN list matching filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 401,          "property": "status",          "operator": "IN",          "values": [            "OPEN",            "WON",            "QUALIFIED"          ]        }      ]    }  ]}

BETWEEN range filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 501,          "property": "amount",          "operator": "BETWEEN",          "from": 100,          "to": 500        }      ]    }  ]}

BETWEEN using legacy values array

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 502,          "property": "amount",          "operator": "BETWEEN",          "values": [            "100",            "500"          ]        }      ]    }  ]}

Null check filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 601,          "property": "phone",          "operator": "IS_NULL"        }      ]    }  ]}

Boolean convenience filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 701,          "property": "is_active",          "operator": "IS_TRUE"        }      ]    }  ]}

Relative date filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 801,          "property": "created_ts",          "operator": "LAST_N_DAYS",          "value": "30"        }      ]    }  ]}

Recurring date filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 802,          "property": "renewal_date",          "operator": "RECURS_MONTHS_AFTER",          "value": "1"        }      ]    }  ]}

Multi-select array filter

json

{  "logic": "AND",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 901,          "property": "tags",          "operator": "HAS_ALL",          "values": [            "vip",            "newsletter"          ]        }      ]    }  ]}

OR across groups filter

json

{  "logic": "OR",  "groups": [    {      "logic": "AND",      "filters": [        {          "propertyId": 101,          "property": "lifecyclestage",          "operator": "EQ",          "value": "customer"        }      ]    },    {      "logic": "AND",      "filters": [        {          "propertyId": 102,          "property": "email",          "operator": "CONTAINS",          "value": "@notifyy.io"        }      ]    }  ]}

Sample Response

json

{  "success": true,  "message": "Segment created successfully",  "data": {    "id": 999,    "name": "High value contacts",    "objectType": "contact",    "segmentType": "ACTIVE",    "description": "Segment for high intent contacts",    "currentVersion": 1,    "createdAt": "2026-08-01T09:15:30Z",    "updatedAt": "2026-08-01T09:15:30Z"  }}

Status Codes

Code	Description
201	Segment was created.
400	Request body is invalid, objectType is unsupported, filters is missing for ACTIVE segments, or a filter payload does not match the current public contract.
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

Content-TypestringRequired

Request body media type.

Example: application/json

AcceptstringRequired

Expected response media type.

Example: application/json

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

Request body

namestringRequired

Segment name. Duplicate names within the same tenant, project, and object type are rejected.

Example: High value contacts

objectTypestringRequired

Lowercase CRM object type. Only object types wired into the current segment filter execution context are supported.

Example: contact

segmentTypestringRequired

Segment type. Supported values are ACTIVE and STATIC.

Example: ACTIVE

descriptionstringOptional

Free-text segment description.

Example: Segment for high intent contacts

filtersobjectRequired

Filter definition for dynamic segment membership. Required for ACTIVE segments and optional for STATIC segments.

filters.logicstringRequired

Top-level group combiner. Supported values are AND and OR.

Example: AND

filters.groupsobject[]Required

One or more filter groups.

filters.groups[].logicstringOptional

Per-group combiner. Supported values are AND and OR. Defaults to AND in execution if omitted.

Example: AND

filters.groups[].filtersobject[]Required

Individual filter conditions.

filters.groups[].filters[].objectstringOptional

Optional object hint field exposed by the BAU DTO. The public create flow routes by the segment objectType rather than this field.

filters.groups[].filters[].propertyIdintegerRequired

Property ID used for property accessibility validation.

Example: 101

filters.groups[].filters[].propertystringRequired

Property internal name or hot-field name.

Example: lifecyclestage

filters.groups[].filters[].operatorstringRequired

Filter operator. Accepted canonical operators and aliases are documented in the operator matrix below.

Example: EQUALS

filters.groups[].filters[].valuescalarOptional

Single comparison value used by single-value operators such as EQ, GT, CONTAINS, and LAST_N_DAYS.

Example: customer

filters.groups[].filters[].valuesarrayOptional

Multi-value list used by operators such as IN, NOT_IN, CONTAINS_ANY, and HAS_ALL.

Example: ["OPEN","WON","QUALIFIED"]

filters.groups[].filters[].fromscalarOptional

Lower bound for BETWEEN and NOT_BETWEEN.

Example: 100

filters.groups[].filters[].toscalarOptional

Upper bound for BETWEEN and NOT_BETWEEN.

Example: 500

Object	Description
name string	RequiredSegment name. Duplicate names within the same tenant, project, and object type are rejected. Example: High value contacts
objectType string	RequiredLowercase CRM object type. Only object types wired into the current segment filter execution context are supported. Example: contact
segmentType string	RequiredSegment type. Supported values are ACTIVE and STATIC. Example: ACTIVE
description string	OptionalFree-text segment description. Example: Segment for high intent contacts
filters object	RequiredFilter definition for dynamic segment membership. Required for ACTIVE segments and optional for STATIC segments.
filters.logic string	RequiredTop-level group combiner. Supported values are AND and OR. Example: AND
filters.groups object[]	RequiredOne or more filter groups.
filters.groups[].logic string	OptionalPer-group combiner. Supported values are AND and OR. Defaults to AND in execution if omitted. Example: AND
filters.groups[].filters object[]	RequiredIndividual filter conditions.
filters.groups[].filters[].object string	OptionalOptional object hint field exposed by the BAU DTO. The public create flow routes by the segment objectType rather than this field.
filters.groups[].filters[].propertyId integer	RequiredProperty ID used for property accessibility validation. Example: 101
filters.groups[].filters[].property string	RequiredProperty internal name or hot-field name. Example: lifecyclestage
filters.groups[].filters[].operator string	RequiredFilter operator. Accepted canonical operators and aliases are documented in the operator matrix below. Example: EQUALS
filters.groups[].filters[].value scalar	OptionalSingle comparison value used by single-value operators such as EQ, GT, CONTAINS, and LAST_N_DAYS. Example: customer
filters.groups[].filters[].values array	OptionalMulti-value list used by operators such as IN, NOT_IN, CONTAINS_ANY, and HAS_ALL. Example: ["OPEN","WON","QUALIFIED"]
filters.groups[].filters[].from scalar	OptionalLower bound for BETWEEN and NOT_BETWEEN. Example: 100
filters.groups[].filters[].to scalar	OptionalUpper bound for BETWEEN and NOT_BETWEEN. Example: 500

Supported Object Types

The current segment filter execution path is wired only for the object types listed here. objectType must be lowercase.

Object Type

contact

Support Notes