Segments: Create
📌 Segment Structure
Section titled “📌 Segment Structure”Each segment includes:
name: Name of the segment.
groups: Array of rule groups.
join_type: “+” implies OR within the group.
rules: Array of rule objects inside a group.
Logical Combination
- AND logic is achieved by separating rules into different groups.
- OR logic is achieved by combining multiple rules inside a single group.
✅ Rule Types & Use Cases
Section titled “✅ Rule Types & Use Cases”Personal Rules
Section titled “Personal Rules”➤ Alias & Email
Match Types: equal, not_equal, starts_with, ends_with, contains
Use Case: Find users whose alias does not equal “john”, sample payload:
{ "name": "Alias Not John", "groups": [ { "join_type": "+", "rules": [ { "type": "alias", "match_value": "john", "match_type": "not_equal" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Alias Not John","groups":[{"join_type":"+","rules":[{"type":"alias","match_value":"john","match_type":"not_equal"}]}]}'Use Case: Find users whose emails ends with pulsatehq.com. This will grab all pulsate users, sample payload:
{ "name": "Pulsate users", "groups": [ { "join_type": "+", "rules": [ { "type": "email", "match_value": "pulsatehq.com", "match_type": "ends_with" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Pulsate users","groups":[{"join_type":"+","rules":[{"type":"email","match_value":"pulsatehq.com","match_type":"ends_with"}]}]}'➤ Age
Match Types: less, more, equal, not_equal, between
Use Case: Find users aged between 20 and 30, sample payload:
{ "name": "Age 20-30", "groups": [ { "join_type": "+", "rules": [ { "type": "age", "match_value": "20", "match_end_value": "30", "match_type": "between" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Age 20-30","groups":[{"join_type":"+","rules":[{"type":"age","match_value":"20","match_end_value":"30","match_type":"between"}]}]}'Activity Rules
Section titled “Activity Rules”➤ Signup
Match Types: less, more
Timeframes: minutes, hours, days, weeks, months, years
Use Case: Find users who signed up less than 10 days ago, sample payload:
{ "name": "Recent Signups", "groups": [ { "join_type": "+", "rules": [ { "type": "signup", "match_type": "less", "match_value": "10", "time_frame": "days" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Recent Signups","groups":[{"join_type":"+","rules":[{"type":"signup","match_type":"less","match_value":"10","time_frame":"days"}]}]}'➤ Last Active
Match Types: less
Timeframes: minutes, hours, days, weeks, months, years
Use Case: Users active in last 24 hours, sample payload:
{ "name": "Active Recently", "groups": [ { "join_type": "+", "rules": [ { "type": "last_active", "match_type": "less", "match_value": "24", "time_frame": "hours" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Active Recently","groups":[{"join_type":"+","rules":[{"type":"last_active","match_type":"less","match_value":"24","time_frame":"hours"}]}]}'➤ Last Contacted/Last Contacted Admin
Match Types: less, more, between, equal, not_equal
Timeframes: minutes, hours, days, weeks, months, years
Use Case: Contacted between 2 to 5 days ago, sample payload: (for last contacted admin, you can change type to last_contcated_admin)
{ "name": "Contacted 2–5 Days Ago", "groups": [ { "join_type": "+", "rules": [ { "type": "last_contacted", "match_type": "between", "match_value": "2", "match_end_value": "5", "time_frame": "days" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Contacted 2–5 Days Ago","groups":[{"join_type":"+","rules":[{"type":"last_contacted","match_value":"2","match_end_value":"5","match_type":"between", "time_frame": "days"}]}]}'➤ Push Opt-Out / Email Unsubscribed
Match Types: equal
Values: “true”, “false”
Use Case: Users opted out of push notifications, sample payload:
{ "name": "Push Opt-Out", "groups": [ { "join_type": "+", "rules": [ { "type": "opt_out", "match_type": "equal", "match_value": "true" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Push Opt-Out","groups":[{"join_type":"+","rules":[{"type":"opt_out","match_value":"true","match_type":"equal"}]}]}'Email unsubscribed: Users opted out of emails, sample payload:
{ "name": "Email Unsubscribed", "groups": [ { "join_type": "+", "rules": [ { "type": "email_unsubscribed", "match_type": "equal", "match_value": "true" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Email Unsubscribed","groups":[{"join_type":"+","rules":[{"type":"email_unsubscribed","match_value":"true","match_type":"equal"}]}]}'Location Rules
Section titled “Location Rules”➤ Location
Match Type: between (range in meters)
Structure: Center + Radius
Use Case: Users within 1km of New York center, sample payload:
{ "name": "New York Area", "groups": [ { "join_type": "+", "rules": [ { "type": "location", "match_type": "between", "match_value": "1000", "locations": [ { "type": "point", "values": { "center": [40.7127753,-74.0059728], "radius": 1000 } } ] } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"New York Area","groups":[{"join_type":"+","rules":[{"type":"location","match_value":"1000","match_type":"between", "locations":[{"type":"point","values":{"center":[40.7127753,-74.0059728],"radius":1000}}]}]}]}'Device Rules
Section titled “Device Rules”Common Fields: device_guid, device_app_version, device_os_version, device_sdk_version
Match Types: equal, not_equal, starts_with, ends_with, contains
➤ Device sdk version
Use Case: Users on SDK version >= 2.0.0
{ "name": "SDK v2", "groups": [ { "join_type": "+", "rules": [ { "type": "device_sdk_version", "match_type": "starts_with", "match_value": "2" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Sdk v2","groups":[{"join_type":"+","rules":[{"type":"device_sdk_version","match_value":"2","match_type":"starts_with"}]}]}'➤ Device push permission
Match Type: equal
Values: true, false, not_set
Use case: Users whose device’s push permission is true, sample payload:
{ "name": "Device with pushes allowed", "groups": [ { "join_type": "+", "rules": [ { "type": "device_push_permission", "match_type": "equal", "match_value": "true" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Devices with pushes allowed","groups":[{"join_type":"+","rules":[{"type":"device_push_permission","match_value":"true","match_type":"equal"}]}]}'➤ Device location permission
Match Type: equal
Values: true, false, not_set
Use case: Users whose device’s location permission is true, sample payload:
{ "name": "Device with location allowed", "groups": [ { "join_type": "+", "rules": [ { "type": "device_location_permission", "match_type": "equal", "match_value": "true" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Devices with location allowed","groups":[{"join_type":"+","rules":[{"type":"device_location_permission","match_value":"true","match_type":"equal"}]}]}'➤ Device type
Match Type: equal
Values: web, ios, android, any
Use case: iOS Users, sample payload:
{ "name": "iOS Users", "groups": [ { "join_type": "+", "rules": [ { "type": "device_type", "match_type": "equal", "match_value": "ios" } ] } ]}sample payload:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"IOS Users","groups":[{"join_type":"+","rules":[{"type":"device_type","match_value":"ios","match_type":"equal"}]}]}'🧠 Combined Use Case Example
Section titled “🧠 Combined Use Case Example”Use case: Users who signed up less than 10 days ago AND use iOS, sample payload:
{ "name": "Recent iOS Users", "groups": [ { "join_type": "+", "rules": [ { "type": "signup", "match_type": "less", "match_value": "10", "time_frame": "days" } ] }, { "join_type": "+", "rules": [ { "type": "device_type", "match_type": "equal", "match_value": "ios" } ] } ]}sample curl:
curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Recent IOS Users","groups":[{"join_type":"+","rules":[{"type":"signup","match_value":"10","match_type":"less", "time_frame": "days"}]}, {"join_type":"+","rules":[{"type":"device_type","match_value":"ios","match_type":"equal"}]}]}'Use case: Users aged 18–25 who use Android and are active in the last 1 hour
{ "name": "Young Active Android Users", "groups": [ { "join_type": "+", "rules": [ { "type": "age", "match_type": "between", "match_value": "18", "match_end_value": "25" } ] }, { "join_type": "+", "rules": [ { "type": "device_type", "match_type": "equal", "match_value": "android" } ] }, { "join_type": "+", "rules": [ { "type": "last_active", "match_type": "less", "match_value": "1", "time_frame": "hours" } ] } ]}Use case: Users whose alias starts with “a” OR ends with “z” OR contains “test”
{ "name": "Flexible Alias Match", "groups": [ { "join_type": "+", "rules": [ { "type": "alias", "match_type": "starts_with", "match_value": "a" }, { "type": "alias", "match_type": "ends_with", "match_value": "z" }, { "type": "alias", "match_type": "contains", "match_value": "test" } ] } ]}Use case: Users whose age is less than 18 OR more than 65
{ "name": "Younger or Elderly Users", "groups": [ { "join_type": "+", "rules": [ { "type": "age", "match_type": "less", "match_value": "18" }, { "type": "age", "match_type": "more", "match_value": "65" } ] } ]}Use Case: Users with Device OS Version “16.1” OR “17.0” OR “18.0”
{ "name": "Multiple OS Versions", "groups": [ { "join_type": "+", "rules": [ { "type": "device_os_version", "match_type": "equal", "match_value": "16.1" }, { "type": "device_os_version", "match_type": "equal", "match_value": "17.0" }, { "type": "device_os_version", "match_type": "equal", "match_value": "18.0" } ] } ]}Use case: Users who are either aged <18 or >65 AND have Push Permission = true
{ "name": "Elderly or Youth with Push Enabled", "groups": [ { "join_type": "+", "rules": [ { "type": "age", "match_type": "less", "match_value": "18" }, { "type": "age", "match_type": "more", "match_value": "65" } ] }, { "join_type": "+", "rules": [ { "type": "device_push_permission", "match_type": "equal", "match_value": "true" } ] } ]}Use Case: Users whose alias starts with ‘dev’ OR email contains ‘@test.com’ AND have push permission enabled
{ "name": "Dev/Test Users with Push Enabled", "groups": [ { "join_type": "+", "rules": [ { "type": "alias", "match_type": "starts_with", "match_value": "dev" }, { "type": "email", "match_type": "contains", "match_value": "@test.com" } ] }, { "join_type": "+", "rules": [ { "type": "device_push_permission", "match_type": "equal", "match_value": "true" } ] } ]}Use case: Users aged 18–25 OR 50–65 AND device app version equals ‘3.1.0’
{ "name": "Younger or Older Users on v3.1.0", "groups": [ { "join_type": "+", "rules": [ { "type": "age", "match_type": "between", "match_value": "18", "match_end_value": "25" }, { "type": "age", "match_type": "between", "match_value": "50", "match_end_value": "65" } ] }, { "join_type": "+", "rules": [ { "type": "device_app_version", "match_type": "equal", "match_value": "3.1.0" } ] } ]}POST /apps/{app_id}/segmentsPath Parameters
Section titled “Path Parameters”| Name | Type | Required | Description |
|---|---|---|---|
app_id |
string | No | id of the pulsate app |
Headers
Section titled “Headers”| Name | Type | Required | Description |
|---|---|---|---|
Authorization |
string | Yes | {my_admin_api_token} |
Content-Type |
string | No | application/json |
Body Parameters
Section titled “Body Parameters”| Name | Type | Required | Description |
|---|---|---|---|
segment |
object | Yes | Segment to be inserted |
segment.name |
string | Yes | Name of the segment |
segment.groups |
array_object | Yes | A group contains rules, with at least one rule matching the user. For a segment with multiple groups, all groups must match. |
segment.groups[].rules |
array_object | Yes | Single rule to be matched against a user |
segment.groups[].rules[].type |
string | No | Rule type e.g alias, email, age etc |
segment.groups[].rules[].time_frame |
string | No | Time frame used for rules, which data_type attribute is date_ago, with exception of anniversary_today match_type e.g days, weeks, months, years |
segment.groups[].rules[].match_type |
string | No | Match type for rule |
segment.groups[].rules[].match_value |
string | No | Match value of the rule depending upon match type |
segment.groups[].rules[].match_end_value |
string | No | To be used when match type is between. |
segment.groups[].rules[].locations |
array_object | No | Last recorded location of a user to be matched against. Currently only supported location type has a shape of a circle. |
segment.groups[].rules[].locations[].values |
object | No | |
segment.groups[].rules[].locations[].values.center |
array_string | No | Center location of a location circle in a format of: [longitude, latitude]. |
segment.groups[].rules[].locations[].values.radius |
int | No | Radius of a location circle in metres. |
segment.groups[].rules[].locations[].values.type |
string | No | point |
Request Example
Section titled “Request Example”curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Alias Not John","groups":[{"join_type":"+","rules":[{"type":"alias","match_value":"john","match_type":"not_equal"}]}]}'curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"New York Area","groups":[{"join_type":"+","rules":[{"type":"location","match_value":"1000","match_type":"between", "locations":[{"type":"point","values":{"center":[40.7127753,-74.0059728],"radius":1000}}]}]}]}'curl -X POST https://control.pulsatehq.com/api/v2/apps/{app_id}/segments \ -H "Authorization: {your_admin_api_token}" \ -H "Content-Type: application/json" \ -d '{"name":"Recent IOS Users","groups":[{"join_type":"+","rules":[{"type":"signup","match_value":"10","match_type":"less", "time_frame": "days"}]}, {"join_type":"+","rules":[{"type":"device_type","match_value":"ios","match_type":"equal"}]}]}'Responses
Section titled “Responses”200 Alias Not John
{ "segment": { "name": "Alias Not John", "groups": [ { "join_type": "+", "rules": [ { "type": "alias", "match_value": "john", "match_type": "not_equal" } ] } ], "id": "segment_id" }}