Create a segment
const url = 'https://api.getsitecontrol.com/v1/sites/1/segments';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","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"]}]}]}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.getsitecontrol.com/v1/sites/1/segments \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "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" ] } ] } ] } }'Creates a segment from a name and conditions, a tree of op/args
nodes in the admin’s condition language described with the conditions
field, and returns it. The segment is created in General,
folder.id 0. Names need not be unique, so a repeated call creates another
segment. Use segment_id of the result with list_contacts.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with Idempotency-Replayed: true instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.
Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with Idempotency-Replayed: true instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Name; surrounding spaces are trimmed, need not be unique
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.
{ "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" ] } ] } ]}Responses
Section titled “Responses”object
Segment id; list_contacts takes it as segment_id
Name; several segments may share one
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.
Folder the segment is in; folders come from list_folders
object
0 is General, where items outside any folder are
A move to another folder does not change it
{ "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" ] } ] } ] }}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
True when the response is a stored one, replayed
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
segment_conditions_invalid: the conditions cannot run. metadata.problem says why: reference_not_found (a nested segment does not exist), segment_cycle (nested segments form a cycle or repeat in one list), not_compilable (an unknown variable, operator or value). validation_failed: the body itself is malformed
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds