Group conditions

A group is defined by a rule. This page is the reference for that rule: how the parts combine, every condition type you can use, and which ids a condition needs. The rule is the filter object you send to POST /segments (create a group) and POST /segments/preview (count who a rule would match without saving it).

How a rule is built

{
  "operator": "AND",
  "conditions": [{ "field": "tag", "operator": "has", "value": "newsletter" }],
  "requiredConditions": [{ "field": "consent", "operator": "active" }],
  "excludeConditions": [{ "field": "tag", "operator": "has", "value": "do-not-contact" }]
}

Key	Required	Meaning
`operator`	Yes	`AND` or `OR`: how the conditions in `conditions` are joined.
`conditions`	Yes	The main list. A contact matches it by satisfying all of them (`AND`) or any of them (`OR`).
`requiredConditions`	No	Conditions every member must also satisfy. Always joined with `AND`, whatever `operator` says.
`excludeConditions`	No	Conditions that remove contacts. A contact who satisfies any one of them is left out.

The three lists combine like this: a contact is in the group when it matches conditions (joined by operator), and matches every condition in requiredConditions, and matches none of the conditions in excludeConditions. A list that is empty or left out is skipped. With only excludeConditions, the group is everyone except the contacts those conditions match.

Each list holds at most 20 conditions. A longer list is a 400 VALIDATION_ERROR.
A rule needs at least one condition across the three lists. A rule with none is refused with 422 EMPTY_FILTER.
Unknown keys are refused, in the rule and in every condition (400 VALIDATION_ERROR, with the path of the bad key in the message). Send only the keys this page lists for the condition’s type.
A condition is an object whose field names its type. Every type is listed below, each with its own keys.
A few condition shapes are refused in some lists (see “Conditions refused in some lists” below). They get 422 CONDITION_NOT_SUPPORTED.
Unsubscribed contacts are never members of a group, whatever the rule says.
Time windows (withinDays, value in days and the like) count back from the moment the rule is evaluated, so the same rule matches different contacts as time passes.
Where a condition has a “never happened” form (not_viewed, not_clicked, not_enrolled), it also matches contacts who have no record at all. Each section below says so where it matters.

Ids in conditions

Some conditions point at one of your documents, products, folders, broadcasts or groups by id. Every id is checked against your own account. An id that is not in your account gets 422 REFERENCE_NOT_FOUND, with details.path (where in the rule) and details.kind (document, product, tier, cta, folder, broadcast or step). A tag condition that names a tag you do not have gets 422 TAG_NOT_FOUND with details.tag. A group_membership condition that names a group you do not have gets 422 GROUP_REFERENCE_NOT_FOUND with details.groupIds. An id that is not a UUID is a 400 VALIDATION_ERROR.

Id	Where to get it
tag (by name, not id)	`GET /tags`: use the tag’s `name`, spelled exactly (case matters).
`groupId`	`GET /segments`.
`documentId`	`GET /documents`.
`productId`	`GET /products`. Archived products are hidden unless you pass `status=archived` or `status=all`.
`folderId`	`GET /folders`. A course is a folder: use its `id`.
`broadcastId`	`GET /email/broadcasts`.
`tierId`, `ctaId`, `stepId` (email step)	No public endpoint returns these ids yet. They are accepted and checked, but you can only use one you already have.

Where an id is optional, leaving it out widens the condition to “anywhere in your account” (for example, document_view without documentId means any of your documents). Each section says what the id-free form means.

Condition types

`tag`

Contacts who carry (or do not carry) one of your tags, matched by the tag’s exact name.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`tag`	The condition type.
`operator`	string	required	`has`, `not_has`	Whether the contact carries the tag.
`value`	string	required	1-50 characters	The tag’s name, spelled exactly (case matters). Get it from `GET /tags`. It must be one of your tags, or the call is refused with `TAG_NOT_FOUND`.

Operator	Matches
`has`	Contacts who currently carry the tag.
`not_has`	Contacts who do not carry it, including contacts with no tags at all.

{ "field": "tag", "operator": "has", "value": "newsletter" }

`document_view`

Contacts who viewed (or never viewed) your documents, with optional limits on which document, how recently, how often and how far they read.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`document_view`	The condition type.
`operator`	string	required	`viewed`, `not_viewed`	Whether the contact viewed.
`documentId`	string (uuid)	optional	a document id	One of your documents, from `GET /documents`. Left out: any of your documents.
`withinDays`	integer	optional	1-365	Only views in the last this many days. Not allowed together with `viewedFrom` / `viewedTo`.
`minCount`	integer	optional	1-1000	The contact viewed the same document at least this many times. Meant for `viewed`.
`minScrollPct`	integer	optional	1-100	The contact read at least this far down (percent) in at least one visit. Meant for `viewed`.
`viewedFrom`	string (date)	optional	`YYYY-MM-DD`	Start of a fixed date range, in Korea Standard Time (KST). Needs `viewedTo`.
`viewedTo`	string (date)	optional	`YYYY-MM-DD`	End of the range, in KST, inclusive. Needs `viewedFrom` and must not be earlier than it.

Operator	Matches
`viewed`	Contacts with at least one view that fits the limits you set.
`not_viewed`	Contacts with no view that fits the limits. With no limit, that means never viewed, in all history. With `withinDays` or a date range, it means no view in that window; they may have viewed earlier.

With a window (withinDays, or viewedFrom and viewedTo), a contact counts as having viewed when their most recent view falls inside it. minCount and minScrollPct are lifetime figures: only the window is about recency, so “3 views within 30 days” means 3 views in total and the latest one in the last 30 days.
A visit to a folder or course that contains the document counts as viewing it. minScrollPct counts only direct views of a document, not folder visits.
withinDays cannot be combined with viewedFrom / viewedTo. viewedFrom and viewedTo go together, and viewedFrom must be on or before viewedTo.
minCount and minScrollPct are meant for viewed. With not_viewed they are accepted and flip: the contact has no view that reached that count or depth.

{
  "field": "document_view",
  "operator": "viewed",
  "documentId": "3f2b8c1a-9d4e-4a7b-8c3d-5e6f7a8b9c0d",
  "withinDays": 14,
  "minScrollPct": 75
}

Contacts by whether they have agreed to marketing messages from you.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`consent`	The condition type.
`operator`	string	required	`active`, `withdrawn`	Whether marketing consent stands.

Operator	Matches
`active`	Contacts who gave marketing consent and have not unsubscribed.
`withdrawn`	Everyone else: no consent on record, consent withdrawn, or unsubscribed.

{ "field": "consent", "operator": "active" }

`cta_click`

Contacts who clicked (or never clicked) a call-to-action button on your documents.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`cta_click`	The condition type.
`operator`	string	required	`clicked`, `not_clicked`	Whether the contact clicked.
`ctaId`	string (uuid)	optional	a CTA id	One specific button. There is no public endpoint that returns CTA ids yet. Not allowed with `documentId`.
`documentId`	string (uuid)	optional	a document id	Any button on this document, from `GET /documents`. Not allowed with `ctaId`.
`withinDays`	integer	optional	1-365	Only clicks in the last this many days.

Operator	Matches
`clicked`	Contacts with at least one click in scope.
`not_clicked`	Contacts with no click in scope. Bare, that means never clicked. With `withinDays`, it means no click in that window; they may have clicked earlier.

Scope is the id you give: ctaId is that button, documentId is any button on that document, neither is any button on any of your documents.
Give ctaId or documentId, not both.

{
  "field": "cta_click",
  "operator": "clicked",
  "documentId": "3f2b8c1a-9d4e-4a7b-8c3d-5e6f7a8b9c0d",
  "withinDays": 7
}

`email_open`

Contacts who opened (or did not open) your broadcast and automation emails. Transactional email such as receipts never counts.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`email_open`	The condition type.
`operator`	string	required	`opened`, `not_opened`, `sent_not_opened`	Whether the contact opened.
`broadcastId`	string (uuid)	optional	a broadcast id	One broadcast, from `GET /email/broadcasts`. Not allowed with `stepId` or `minCount`.
`stepId`	string (uuid)	optional	an automation step id	One step of an automation. There is no public endpoint that returns step ids yet. Not allowed with `broadcastId` or `minCount`.
`minCount`	integer	optional	1-1000	Opened at least this many emails in total, across your account. Not allowed with `broadcastId` or `stepId`.
`sinceSentDays`	integer	optional	1-365	Only with `sent_not_opened`: the email was sent at least this many days ago.

Operator	Matches
`opened`	Contacts with at least one open in scope (or at least `minCount` opens in total).
`not_opened`	Contacts with no recorded open in scope. This includes contacts who were never sent that email.
`sent_not_opened`	Contacts who were sent the email and did not open it. Unlike `not_opened`, it leaves out contacts who were never sent it. Needs `broadcastId` or `stepId`.

Scope is the id you give: a broadcast, an automation step, or neither (any broadcast or automation email).
sent_not_opened requires broadcastId or stepId. sinceSentDays works only with sent_not_opened; without it, an email still waiting to go out counts as sent, and with it only emails already sent that many days ago do.
minCount cannot be combined with broadcastId or stepId.

{
  "field": "email_open",
  "operator": "sent_not_opened",
  "broadcastId": "7c1d9e24-6a3b-4f58-9e0a-2b4c6d8e0f13",
  "sinceSentDays": 3
}

`email_link_click`

Contacts who clicked (or did not click) a link in your broadcast and automation emails. Only links to your content count: the unsubscribe link does not.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`email_link_click`	The condition type.
`operator`	string	required	`clicked`, `not_clicked`, `within_days`, `inactive_for_days`	Whether, or how recently, the contact clicked.
`broadcastId`	string (uuid)	optional	a broadcast id	One broadcast, from `GET /email/broadcasts`. Not allowed with `stepId`.
`stepId`	string (uuid)	optional	an automation step id	One step of an automation. There is no public endpoint that returns step ids yet. Not allowed with `broadcastId`.
`value`	integer	optional	1-365	Days. Required with `within_days` and `inactive_for_days`; not allowed with `clicked` and `not_clicked`.

Operator	Matches
`clicked`	Contacts who clicked a link in scope, at any time.
`not_clicked`	Contacts with no click in scope, including contacts who were never sent anything in scope.
`within_days`	Contacts who clicked a link in scope within the last `value` days.
`inactive_for_days`	Contacts with no click in scope within the last `value` days. This includes contacts who never clicked and contacts who were never sent.

Scope is the id you give: a broadcast, an automation step, or neither (any broadcast or automation email).
Give broadcastId or stepId, not both.

{ "field": "email_link_click", "operator": "within_days", "value": 30 }

`has_phone`

Contacts by whether you have a phone number for them.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`has_phone`	The condition type.
`operator`	string	required	`has`, `not_has`	Whether a phone number is on record.

Operator	Matches
`has`	Contacts with a phone number on record.
`not_has`	Contacts with no phone number (missing or empty).

{ "field": "has_phone", "operator": "has" }

`form_submission`

Contacts who submitted (or never submitted) any of your forms. There is no way to pick one form.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`form_submission`	The condition type.
`operator`	string	required	`submitted`, `not_submitted`, `inactive_for_days`	Whether, or how recently, the contact submitted a form.
`value`	integer	optional	1-365	Days. Required with `inactive_for_days`; not allowed with `submitted` and `not_submitted`.

Operator	Matches
`submitted`	Contacts who submitted at least one of your forms, at any time.
`not_submitted`	Contacts who never submitted any of your forms.
`inactive_for_days`	Contacts who have not submitted a form in the last `value` days. This includes contacts who never submitted one.

{ "field": "form_submission", "operator": "inactive_for_days", "value": 60 }

`payment_status`

Contacts by the payment status recorded for them when a payment is paid, fails or is refunded.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`payment_status`	The condition type.
`operator`	string	required	`is`, `is_not`	Whether the contact has it.
`value`	string	required	`paid`, `failed`, `refunded`	The payment status.

Operator	Matches
`is`	Contacts currently marked with this status.
`is_not`	Contacts not marked with it, including contacts who never made a payment.

{ "field": "payment_status", "operator": "is", "value": "paid" }

`first_seen`

Contacts by how long ago they first appeared (their first view, visit or submission).

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`first_seen`	The condition type.
`operator`	string	required	`within_days`, `more_than_days_ago`	Newer or older than the number of days.
`value`	integer	required	1-365	Days.

Operator	Matches
`within_days`	Contacts first seen within the last `value` days (new contacts).
`more_than_days_ago`	Contacts first seen more than `value` days ago.

{ "field": "first_seen", "operator": "within_days", "value": 7 }

`last_active`

Contacts by how recently they last viewed or visited something of yours. Only document and folder visits count; opening or clicking an email does not.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`last_active`	The condition type.
`operator`	string	required	`within_days`, `inactive_for_days`	Active within, or inactive for, the days.
`value`	integer	required	1-365	Days.

Operator	Matches
`within_days`	Contacts whose last activity was within the last `value` days.
`inactive_for_days`	Contacts whose last activity was more than `value` days ago.

{ "field": "last_active", "operator": "inactive_for_days", "value": 90 }

`group_membership`

Contacts who are (or are not) in another group of yours.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`group_membership`	The condition type.
`operator`	string	required	`in`, `not_in`	Whether the contact is in that group.
`groupId`	string (uuid)	required	a group id	The other group, from `GET /segments`. It must be one of yours, or the call is refused with `GROUP_REFERENCE_NOT_FOUND`.

Operator	Matches
`in`	Contacts currently in that group.
`not_in`	Contacts not currently in it, including contacts that were never in it.

{
  "field": "group_membership",
  "operator": "not_in",
  "groupId": "5a9e4b70-2c1d-4e83-b6f9-0d7c8a1b2e34"
}

`tier_access`

Contacts who have (or lack) current access through a purchase of one of your products.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`tier_access`	The condition type.
`operator`	string	required	`enrolled`, `not_enrolled`, `expiring_within_days`	Whether the contact has access, or access that ends soon.
`productId`	string (uuid)	optional	a product id	One product, from `GET /products`.
`tierId`	string (uuid)	optional	an access tier id	One access tier. There is no public endpoint that returns tier ids yet.
`documentId`	string (uuid)	optional	a document id	Any product sold on this document’s payment form, from `GET /documents`.
`saleStatus`	string	optional	`active`, `archived`	Any product on sale (`active`) or no longer sold (`archived`). A product scheduled to go on sale later is in neither.
`expiringWithinDays`	integer	optional	1-365	Days. Required with `expiring_within_days`; not allowed with the other operators.

Operator	Matches
`enrolled`	Contacts who have access now. Access that starts later (a drip schedule) counts. Expired, refunded and revoked access does not.
`not_enrolled`	Everyone who does not match `enrolled`. This is broad: it includes contacts who never bought, and also contacts whose access expired or was refunded or revoked. With `productId` or `documentId` it is not supported yet (see “Conditions refused in some lists”).
`expiring_within_days`	Contacts whose access ends within the next `expiringWithinDays` days. Access that has already ended, and access with no end date, do not match.

Scope is the one id you give. With none of productId, tierId, documentId and saleStatus, the condition covers any product of yours.
Give at most one of productId, tierId, documentId and saleStatus.
expiringWithinDays is required with expiring_within_days and must be left out otherwise.

{
  "field": "tier_access",
  "operator": "expiring_within_days",
  "productId": "9b2e6d14-8f30-4c5a-a1e7-3d4f5a6b7c80",
  "expiringWithinDays": 14
}

`days_since_purchase`

Contacts by how long ago they paid for a product.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`days_since_purchase`	The condition type.
`operator`	string	required	`within_days`, `more_than_days_ago`	Paid recently, or longer ago than the number of days.
`value`	integer	required	1-365	Days.
`productId`	string (uuid)	optional	a product id	One product, from `GET /products`.
`tierId`	string (uuid)	optional	an access tier id	Products that grant this access tier. There is no public endpoint that returns tier ids yet.
`documentId`	string (uuid)	optional	a document id	Any product sold on this document’s payment form, from `GET /documents`.
`saleStatus`	string	optional	`active`, `archived`	Any product on sale (`active`) or no longer sold (`archived`).

Operator	Matches
`within_days`	Contacts with a paid order in scope within the last `value` days.
`more_than_days_ago`	Contacts with a paid order in scope that is more than `value` days old. A contact who also bought again recently still matches, since an older order exists.

A contact who never paid matches neither operator.
Scope is the one id you give. With none of productId, tierId, documentId and saleStatus, any product of yours counts. Give at most one of the four.
A fully refunded order does not count as paid.

{
  "field": "days_since_purchase",
  "operator": "within_days",
  "value": 30,
  "productId": "9b2e6d14-8f30-4c5a-a1e7-3d4f5a6b7c80"
}

`repeat_bounce`

Contacts whose email address keeps failing.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`repeat_bounce`	The condition type.
`operator`	string	required	`is`, `is_not`	Whether the address has a bounce problem.

Operator	Matches
`is`	Contacts whose address is blocked.
`is_not`	Everyone else,.

{ "field": "repeat_bounce", "operator": "is" }

`course_last_access`

Contacts by how recently they visited one folder or course.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`course_last_access`	The condition type.
`operator`	string	required	`within_days`, `inactive_for_days`	Visited within, or not within, the days.
`folderId`	string (uuid)	required	a folder id	The folder or course, from `GET /folders`.
`value`	integer	required	1-365	Days.

Operator	Matches
`within_days`	Contacts who visited the folder within the last `value` days.
`inactive_for_days`	Contacts who visited the folder before, but not within the last `value` days. Contacts who never visited it do not match.

{
  "field": "course_last_access",
  "operator": "inactive_for_days",
  "folderId": "e4a1c7b3-5d92-4f06-8a3b-6c7d8e9f0a12",
  "value": 14
}

`kakao_reachable`

Contacts you can send a Kakao message to.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`kakao_reachable`	The condition type.
`operator`	string	required	`reachable`, `not_reachable`	Whether the contact can be messaged.

Operator	Matches
`reachable`	Contacts with a phone number who have not opted out of Kakao messages.
`not_reachable`	Everyone else: no phone number, or opted out.

{ "field": "kakao_reachable", "operator": "reachable" }

`course_progress`

Contacts by how much of one folder or course they have completed.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`course_progress`	The condition type.
`operator`	string	required	`at_least`, `below`	Completion at or above, or below, the value.
`folderId`	string (uuid)	required	a folder id	The folder or course, from `GET /folders`.
`value`	integer	required	0-100	Completion, in percent.

Operator	Matches
`at_least`	Contacts whose recorded completion is `value` percent or more.
`below`	Contacts whose recorded completion is under `value` percent. Contacts with no recorded progress (for example, who never opened it) do not match.

{
  "field": "course_progress",
  "operator": "at_least",
  "folderId": "e4a1c7b3-5d92-4f06-8a3b-6c7d8e9f0a12",
  "value": 80
}

`location`

Contacts by the country, and optionally the city, recorded from their visits.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`location`	The condition type.
`operator`	string	required	`is`, `is_not`	Whether the contact is in that place.
`country`	string	required	2 uppercase letters	Two-letter uppercase ISO 3166-1 alpha-2 country code, for example `KR`. It is checked: a lowercase or wrong-length code is refused with `400 VALIDATION_ERROR` (the message starts with `filter.conditions.N.country`).
`city`	string	optional	1-120 characters	The city, as recorded; the comparison is exact and case-sensitive. Needs `country`, and both must match for `is`.

Operator	Matches
`is`	Contacts in that country, or in that country and city when `city` is given.
`is_not`	Everyone else, including contacts with no recorded location. With `city`, it means not in that exact country-and-city pair, so a contact in the same country but another city matches.

{ "field": "location", "operator": "is", "country": "KR", "city": "Seoul" }

`checkout_abandoned`

Contacts who started checking out for one product and did not finish. There is no opposite operator.

Key	Type	Required?	Allowed values	Meaning
`field`	string	required	`checkout_abandoned`	The condition type.
`operator`	string	required	`within_days`	The only operator.
`value`	integer	required	1-365	How many days back the checkout was started.
`productId`	string (uuid)	required	a product id	The product, from `GET /products`.

Operator	Matches
`within_days`	Contacts who started a checkout for the product within the last `value` days and have not paid for it since.

{
  "field": "checkout_abandoned",
  "operator": "within_days",
  "value": 7,
  "productId": "9b2e6d14-8f30-4c5a-a1e7-3d4f5a6b7c80"
}

Conditions refused in some lists

Some condition shapes are refused with 422 CONDITION_NOT_SUPPORTED: details.path points at the condition, details.operator names its operator, and details.invertTo, when there is one, is the operator to put in requiredConditions for the same result. Everything not listed here works in every list.

Condition	Refused	In	What to do
`repeat_bounce`	`is`	`excludeConditions`	Put `is_not` in `requiredConditions`: the same people are left out, and contacts with no bounce record are kept.
`location`	`is`, with or without `city`	`excludeConditions`	Put `is_not` with the same `country` and `city` in `requiredConditions`.
`tier_access`	`enrolled`, with `productId` or `documentId`	`excludeConditions`	No equivalent for these ids. To exclude, scope it with `tierId`, or leave the ids out. It still works in `conditions` and `requiredConditions`.
`tier_access`	`not_enrolled`, with `productId` or `documentId`	all three lists	Not supported yet with these ids. Scope it with `tierId`, or leave the ids out.
`days_since_purchase`	`within_days` and `more_than_days_ago`, with `productId`, `tierId` or `documentId`	`excludeConditions`	No equivalent for these ids. To exclude, leave the ids out. It still works in `conditions` and `requiredConditions`.

Every other condition, and these with the other operators or scopes, works in every list.

Not supported yet

The custom_field condition is not accepted. A rule that contains it is refused with 422 CONDITION_NOT_SUPPORTED, with details.field naming the condition type and details.path pointing at it.

Documents

Folders

Products

Audiences

Contacts

Email

Instagram

Account

How a rule is built

Ids in conditions

Condition types

`tag`

`document_view`

`cta_click`

`email_open`

`email_link_click`

`has_phone`

`form_submission`

`payment_status`

`first_seen`

`last_active`

`group_membership`

`tier_access`

`days_since_purchase`

`repeat_bounce`

`course_last_access`

`kakao_reachable`

`course_progress`

`location`

`checkout_abandoned`

Conditions refused in some lists

Not supported yet

​How a rule is built

​Ids in conditions

​Condition types

​tag

​document_view

​consent

​cta_click

​email_open

​email_link_click

​has_phone

​form_submission

​payment_status

​first_seen

​last_active

​group_membership

​tier_access

​days_since_purchase

​repeat_bounce

​course_last_access

​kakao_reachable

​course_progress

​location

​checkout_abandoned

​Conditions refused in some lists

​Not supported yet

How a rule is built

Ids in conditions

Condition types

`tag`

`document_view`

`consent`

`cta_click`

`email_open`

`email_link_click`

`has_phone`

`form_submission`

`payment_status`

`first_seen`

`last_active`

`group_membership`

`tier_access`

`days_since_purchase`

`repeat_bounce`

`course_last_access`

`kakao_reachable`

`course_progress`

`location`

`checkout_abandoned`

Conditions refused in some lists

Not supported yet