List automations
const url = 'https://api.getsitecontrol.com/v1/sites/1/automations?limit=50&order=oldest';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.getsitecontrol.com/v1/sites/1/automations?limit=50&order=oldest' \ --header 'Authorization: Bearer <token>'Automations of the site in ascending order of id (order=newest for the
latest first), each in the shape get_automation returns: its name, whether it is on
(is_active), trigger, entry condition, steps in order with their settings
and own conditions, folder and author. Call it to find an automation and its
id. Filters combine: every one given must match. Deleted
automations and follow-ups of widgets are not listed.
Lists keep their first 5 entries and texts their first 200 characters (links, trigger,
conditions and steps stay whole); truncated names what was cut, get_automation has it whole.
A page holds up to limit automations; while next_cursor is set, pass it
as cursor for the next page.
To keep a copy in sync, walk the whole list with the cursor and no filters
once. After that, pass updated_since set to the start of the previous walk
minus a margin of a few minutes, and merge by id.
updated_at moves when the automation itself changes: it is turned on or
off (by the user, through the API or by the system), renamed, reordered, or
its trigger, steps or condition change. A move to a folder is not a change,
nor are new runs or a change of an e-mail of the automation. A deleted
automation simply disappears. Repeat the full walk now and then to notice
moves and deletions.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”True: only automations that are on; false: off
True: only automations that are on; false: off
Only automations started by any of these trigger types; repeat for several
Only automations started by any of these trigger types; repeat for several
Only automations started by a form submit of this widget; widget id from list_widgets
Only automations started by a form submit of this widget; widget id from list_widgets
Part of the name, case ignored, or the exact id
Part of the name, case ignored, or the exact id
Only automations created at or after this moment; without an offset, taken as UTC; a plain date means its start
Only automations created at or after this moment; without an offset, taken as UTC; a plain date means its start
Only automations whose updated_at is at or after this moment: changed themselves; a move to a folder and a deletion are not changes; without an offset, taken as UTC; a plain date means its start
Only automations whose updated_at is at or after this moment: changed themselves; a move to a folder and a deletion are not changes; without an offset, taken as UTC; a plain date means its start
Only the items of this folder, an id from list_folders; 0 is General
Only the items of this folder, an id from list_folders; 0 is General
next_cursor of the previous page, sent with the same order; omit for the first
next_cursor of the previous page, sent with the same order; omit for the first
Items per page
Items per page
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Comma-separated fields to keep in each item, for example id,name; each item then carries only those fields and id. Omit for every field
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Order of the items: oldest first (default) or newest first; asc and desc mean the same
Responses
Section titled “Responses”One page of a list; next_cursor is null on the last page.
object
object
Pass it as automation_id
Name as shown in the dashboard
True: the automation is on
object
widget_submit: a visitor submits a form of a chosen widget.
The widgets whose forms start it, ids from list_widgets; empty while none is chosen
object
segment_join: a contact joins a chosen segment.
The segment whose new members start it, from list_segments
object
email_click: a contact clicks a link in an e-mail.
The links whose clicks start it, any link when empty
object
webhook: a request to the automation’s own webhook URL, or run_automation.
Where to send the request
object
shopify_customer_winback: a customer has not ordered for a chosen number of days.
Days without an order that start it
object
manual: another automation, a contact import, the dashboard or run_automation. shopify_order_paid: an order is paid. shopify_order_fulfilled: an order is fulfilled. shopify_checkout_abandoned: a checkout is abandoned. shopify_customer_subscribed: a customer subscribes to e-mail marketing. other: a trigger the dashboard does not offer.
Last change of the automation, its state or its structure; a move to a folder, new runs and changes of its e-mails do not move it
Null when the user was deleted or the automation was created without a user, by the system or the old API
object
Null for Support or for a user who was deleted
Null when the user has no name
The user’s sign-in e-mail; null for Support
Last change made in the editor
Who made the change at edited_at; null when unknown: by an API key, by a user deleted since, or before authors were recorded
object
Null for Support or for a user who was deleted
Null when the user has no name
The user’s sign-in e-mail; null for Support
object
0 is General, where items outside any folder are
The entry condition: a contact who does not match it when the trigger fires is not run (the run is ineligible). null when there is none. The tree is the one of segments, with the same operators and variables:
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.
What the automation does to a contact, in order. New type values may be added; strict clients must accept unknown ones
object
The step’s own id, kept while it exists
False: the step is turned off and skipped by every run
Its own condition, in the format of the automation’s conditions: a contact who does not match skips this step and goes on to the next one. null when there is none
The e-mail it sends; its subject and body: get_email
object
The step’s own id, kept while it exists
False: the step is turned off and skipped by every run
Its own condition, in the format of the automation’s conditions: a contact who does not match skips this step and goes on to the next one. null when there is none
The tags, from list_tags
object
The step’s own id, kept while it exists
False: the step is turned off and skipped by every run
Its own condition, in the format of the automation’s conditions: a contact who does not match skips this step and goes on to the next one. null when there is none
How long to wait
object
start_automation: starts another automation for the contact.
The step’s own id, kept while it exists
False: the step is turned off and skipped by every run
Its own condition, in the format of the automation’s conditions: a contact who does not match skips this step and goes on to the next one. null when there is none
The automation it starts
object
condition: the entry condition, in runs only. other: a step the dashboard does not offer.
The step’s own id, kept while it exists
False: the step is turned off and skipped by every run
Its own condition, in the format of the automation’s conditions: a contact who does not match skips this step and goes on to the next one. null when there is none
Parts shortened in the list, as paths; the card has them whole. Empty when nothing was cut
{ "items": [ { "trigger": { "type": "widget_submit" }, "steps": [ { "type": "send_email" } ], "truncated": [] } ]}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
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
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