Update a segment
📌 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
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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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
➤ 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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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
➤ 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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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
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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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
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 PUT https://control.pulsatehq.com/api/v2/apps/{app_id}/segments/{id} \
-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"
}
]
}
]
}