Segments

Update a segment

Renames a segment or replaces its conditions, written by the rules of create_segment, and returns the segment. A field left out stays as it is; a field sent unchanged is not a change, so the segment as read can be sent back with a new name. New conditions are checked in full, nested segments included. Automations triggered by joining the segment follow new conditions by themselves. A request that changes nothing writes nothing and keeps updated_at.

patch/v1/sites/{site_id}/segments/{segment_id}

Request

Base URL
https://api.getsitecontrol.com
Auth
HTTP bearer

Path parameters

site_idinteger required

segment_idinteger required

Segment id from list_segments

Request body

namestring

New name; surrounding spaces are trimmed. Leave out to keep it

conditionsunknown

Example request

{
  "conditions": {
    "op": "and",
    "args": [
      {
        "op": "and",
        "args": [
          {
            "op": "=",
            "args": [
              "{{$contact.isSubscribed}}",
              "S"
            ]
          },
          {
            "op": "ina",
            "args": [
              "{{$contact.tags}}",
              [
                12,
                15
              ]
            ]
          }
        ]
      },
      {
        "op": "or",
        "args": [
          {
            "op": ">",
            "args": [
              "{{$contact.date}}",
              "2026-01-01"
            ]
          },
          {
            "op": "in",
            "args": [
              "{{$contact.email}}",
              "@example.com"
            ]
          }
        ]
      }
    ]
  }
}

Response

Successful Response

idinteger required

Segment id; list_contacts takes it as segment_id

namestring required

Name; several segments may share one

conditionsobject required

Which contacts belong to the segment: a tree of conditions, applied to the contacts as they are at the moment it is used.

Conditions are the condition language of the Getsitecontrol admin, with its own variable names and codes; they are not the field names and values of Contact. A segment written here can be edited in the admin, and the variables below are the ones the admin's condition editor offers.

A node is an object with exactly op and args. A group has op and or or and nodes in args; a leaf has the variable {{$contact.<name>}} as the first argument, then its values: none for * (is set) and undefined (is not set), two for between and !between, one for the rest. To negate, use the opposite operator; there is no not node.

The admin editor shows a root group whose args are groups, each holding leaves, as in the example; write that shape so the segment stays editable there. {"op": "and", "args": []} matches every contact of the site. Conditions are saved as sent.

Values are integers, strings or, for ina and !ina, a list of them.

Operator	Meaning
=, !=	equals, differs
ina, !ina	any of the list, none of it
<, >, between, !between	compare; between includes both ends
^, $, in, match (and !-forms)	starts with, ends with, contains, wildcard * without case
*, undefined	is set, is not set

Text operators other than match are case sensitive, except on $contact.email: a contact's email is stored lowercase and compared without case by every operator. In ^, $, in, match and their negations _ matches any single character and % is a plain character.

Variable	Operators	Value
$contact.email, phone, firstName, lastName	text operators, =, !=, ina, !ina, *, undefined	string
$contact.country	=, !=, ina, !ina, *, undefined	ISO 3166-1 alpha-2, upper case
$contact.date	=, !=, <, >, between, !between, *, undefined	date the contact was added
$contact.isSubscribed	=	marketing status: S subscribed, U unsubscribed, B bounced
$contact.emailQuality	=, !=, ina, !ina, *, undefined	Corp+, Corp corporate, Pers+, Pers personal (+ is the higher grade), Edu education, Gov government, Risk risky, Temp disposable, Unk unknown
$contact.tags	=, !=, ina, !ina, *, undefined	tag ids from list_tags
$contact.segments	=, !=, ina, !ina	ids from list_segments, as integers
$contact.emailSend, emailOpen, emailClick	=, !=, ina, !ina, *, undefined	e-mail id, as email_id of a broadcast
$contact.emailSendCount, emailOpenCount, emailClickCount	=, !=, <, >, between, !between, *, undefined	integer, not negative
$contact.emailSendDate, emailOpenDate, emailClickDate	as $contact.date	the latest event
$contact.$shopifySpent, $shopifyOrders	as the counts	integer
$contact.$shopifyOrderDate	as $contact.date	the latest order
$contact.<field id>	by the field type from list_contact_fields: text, integer, number, date or datetime	as the field; boolean and other fields are refused

ina and !ina on tags and segments take at least one id. On $contact.tags, = means the contact has that tag among its tags.

$contact.isSubscribed compares the stored status code as the admin does: S does not match a contact who confirmed double opt-in, U does not match one who never subscribed or awaits double opt-in, and B matches every bounced contact. The contact statuses subscribed, unsubscribed and bounced are the broader groups.

Ids are integers or strings of digits. A number is a 32-bit integer or a string holding one. A date is YYYY-MM-DD or ISO 8601 with an offset. For $contact.date, $shopifyOrderDate and datetime fields, a value at midnight is a whole day: = and != cover the day, and the second value of between runs to its end. Date fields and $contact.email*Date compare with midnight exactly.

Nested segments may not form a cycle. A list must reference each nested segment once, and not one nested inside another.

Conditions are checked the way they run: nested segments must exist and the whole tree must compile, so an unknown variable or a value of the wrong type is refused. Conditions saved in the admin are returned as they are and may use other variables and values.

created_atstring date-time required

updated_atstring date-time required

A move to another folder does not change it

Example response

{
  "conditions": {
    "op": "and",
    "args": [
      {
        "op": "and",
        "args": [
          {
            "op": "=",
            "args": [
              "{{$contact.isSubscribed}}",
              "S"
            ]
          },
          {
            "op": "ina",
            "args": [
              "{{$contact.tags}}",
              [
                12,
                15
              ]
            ]
          }
        ]
      },
      {
        "op": "or",
        "args": [
          {
            "op": ">",
            "args": [
              "{{$contact.date}}",
              "2026-01-01"
            ]
          },
          {
            "op": "in",
            "args": [
              "{{$contact.email}}",
              "@example.com"
            ]
          }
        ]
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.