Skip to main content
PATCH
/
apps
/
{app_id}
/
segments
/
{segment_id}
Update segment
curl --request PATCH \
  --url https://api.onesignal.com/apps/{app_id}/segments/{segment_id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION",
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ]
}
'
{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Update an existing segment’s name and/or filters. This API allows you to modify Segments programmatically without having to delete and recreate them.
The name parameter is always required, even if you’re not changing it. When filters are provided, all existing filters are replaced with the new ones. Omit the filters parameter to keep existing filters intact. The filters array cannot be empty—if provided, it must contain at least one filter.

​
How to use this API

​
Update segment name only

To update just the segment name without changing filters: 
{
  "name": "New Segment Name"
}

​
Update segment description

Update the optional description (max 255 characters). Pass an empty string to clear the existing description; omit the field to leave it unchanged. 
{
  "name": "YOUR_SEGMENT_NAME",
  "description": "YOUR_SEGMENT_DESCRIPTION"
}

​
Update segment filters

To update the segment filters (this replaces all existing filters), provide the name (required) and filters: 
{
  "name": "Updated Segment",
  "filters": [
    {"field": "session_count", "relation": ">", "value": "5"},
    {"operator": "AND"},
    {"field": "tag", "key": "subscription", "relation": "=", "value": "premium"}
  ]
}

​
Filter syntax

The filter syntax is identical to the Create segment API. Available filters include:
  • tag - Filter by Tags
  • last_session - Filter by last active time
  • first_session - Filter by first session time
  • session_count - Filter by number of sessions
  • session_time - Filter by total usage duration
  • language - Filter by user language
  • app_version - Filter by app version
  • location - Filter by GPS coordinates
  • country - Filter by country
Use AND and OR operators to combine filters: 
{
  "name": "Engaged Premium Users",
  "filters": [
    {"field": "tag", "key": "plan", "relation": "=", "value": "premium"},
    {"operator": "AND"},
    {"field": "session_count", "relation": ">", "value": "10"},
    {"operator": "OR"},
    {"field": "tag", "key": "vip", "relation": "=", "value": "true"}
  ]
}

​
Response

​
Success response

{
  "success": true,
  "id": "7ed2887d-bd24-4a81-8220-4b256a08ab19"
}

​
Error responses

Status CodeDescription
400Bad request - Invalid filters, duplicate segment name, or segment used by active Journey
403Forbidden - API not available for your plan
404Not found - Segment does not exist
429Rate limit exceeded

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

​
Content-Type
string
default:application/json; charset=utf-8
required

Path Parameters

​
app_id
string
default:YOUR_APP_ID
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

​
segment_id
string
default:YOUR_SEGMENT_ID
required

The segment_id can be found in the URL of the segment when viewing it in the dashboard.

Body

application/json
​
name
string
default:YOUR_SEGMENT_NAME
required

Required. The segment name. Maximum 128 characters.

​
description
string
default:YOUR_SEGMENT_DESCRIPTION

Optional human-readable description for the segment. Maximum 255 characters. Pass an empty string to clear; omit to leave unchanged.

Maximum string length: 255
​
filters
(Filter · object | Operator · object)[]

Optional. When provided, replaces all existing filters. Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and OR operators. See Create segment for filter syntax.

Required array length: 1 - 200 elements

Required. The filter object.

Response

200

​
success
boolean
default:true

true if the segment was updated successfully, false otherwise.

​
id
string

The UUID of the updated segment.