Segments (search contacts) reference manual

TIP

Our API v3 uses terminology from the previous version of GetResponse. Search-contacts and segments are the same resource. The phrase search-contacts included in endpoints corresponds to segments in the GetResponse application.

The 'searchContacts' method returns complex responses from our resources. It lets you create and run precise search queries. In this document, we explain how it works and how to use it.

Table of contents

1. A short description of the available resources

2. POST /v3/search-contacts/contacts using segment queries
   • Basics
   • Contact details
     • Name searching for contacts by name.
     • Email searching for contacts by email.
     • Custom fields searching for contacts by predefined custom fields.
     • Subscription date searching for contacts by subscription date.
     • Subscription method searching for contacts by subscription method.
   • Contact actions
     • Message opened finding contacts who opened a specific message.
     • Message not opened finding contacts who didn't open a specific message.
     • Autoresponder day finding contacts who are on a specific day in an autoresponder cycle.
     • Last send date finding contacts based on when an email was last sent.
     • Last click date finding contacts based on when they last clicked a message.
     • Last open date finding contacts based on when they last opened a message.
     • Webinars finding webinar participants.
     • Link clicked finding contacts who clicked a link in a message.
     • Link not clicked finding contacts who didn't click a link.
     • Message sent finding contacts who were sent a specific message.
     • Message not sent finding contacts were never sent a specific message.
   • Geolocation
   • GDPR
   • Scoring
   • Engagement Score
   • Tags
   • Ecommerce
     • ecommerce_number_of_purchases searching for contacts by the number of purchases they've made.
     • ecommerce_total_spent searching for contacts by total spent.
     • ecommerce_product_purchased searching for contacts by products purchased.
     • ecommerce_brand_purchased searching for contacts by brand purchased.
     • ecommerce_abandoned_cart searching for contacts by abandoned cart.
   • SMS (Text messaging)
     • sms_sent finding contacts who were sent a specific SMS.
     • sms_link_clicked finding contacts who clicked a specific link.
     • sms_link_not_clicked finding contacts who didn't click a specific link.
   • Custom Events
   • Search-contact response
3. POST /v3/search-contacts creating search criteria for later re-use.
4. GET /v3/search-contacts retrieving existing segments.
5. GET [/v3/search-contacts/{searchContactId} retrieving search criteria used in a specific segment.(#get-search-contacts-by-id)
6. POST /v3/search-contacts/{searchContactId} updating a segment.
7. DELETE /v3/search-contacts/{searchContactId} deleting a segment.
8. GET /v3/search-contacts/{searchContactId}/contacts retrieving the list of contacts matching the search criteria.
9. POST /v3/search-contacts/{searchContactId}/custom-fields adding or updating custom field values for all contacts who meet specific search criteria.

Appendices

1. Full list of operator types
2. Full list of currencies
3. API requests query parameters

Short description of resources.

List of available resources

/v3/search-contacts

Available HTTP methods (endpoints): GET POST

We suggest you first explore the Advanced search options in your GetResponse account.

Advanced search lets you add up to 8 conditions and 8 condition groups. You can make your search as broad or narrow as you'd like using different combinations of conditions, condition groups, and the available condition and group connectives.

You can store the search criteria for future use, and you can save them as a segment. Contacts who match the criteria are dynamically added to the search results.

Once you've created a segment in your account, you can analyze the response fetched from GET /v3/search-contacts/{searchContactId}.

---

/v3/search-contacts/{searchContactId}

Use the resource with an identifier to get, update, or delete the conditions used to create the specific segment.

Available HTTP methods (endpoints): GET POST DELETE

---

/v3/search-contacts/{searchContactId}/contacts

Use the search contacts resource to get all the contacts matching the search criteria used in a given segment.

Available HTTP methods (endpoints): GET

---

/v3/search-contacts/contacts

Use the resource to search for contacts by direct query.

Available HTTP methods (endpoints): POST

---

/v3/search-contacts/{searchContactId}/custom-fields

Use the resource to add or update custom field values for all contacts who meet the search criteria

Available HTTP methods (endpoints): POST

---

Table of available endpoints

Method	Endpoint	Usage
GET	/v3/search-contacts	retrieving created segments
POST	/v3/search-contacts	creating a new segment
POST	/v3/search-contacts/contacts	search for contacts without saving the search
GET	/v3/search-contacts/{searchContactId}	retrieving the search criteria used in a specific segment
POST	/v3/search-contacts/{searchContactId}	updating a segment
DELETE	/v3/search-contacts/{searchContactId}	deleting a segment
GET	/v3/search-contacts/{searchContactId}/contacts	retrieving the list of contacts filtered by specific segment
POST	/v3/search-contacts/{searchContactId}/custom-fields	adding and updating custom field values for all contacts who meet the specific search criteria

Get the contacts matching specific conditions.

This endpoint lets you get the contacts matching specific conditions. This section explains how to create search conditions.

Example request

POST v3/search-contacts/contacts

{
   "subscribersType": [
      "subscribed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "tamqY"
         ],
         "subscriberCycle": [
            "receiving_autoresponder",
            "not_receiving_autoresponder"
         ],
         "subscriptionDate": "all_time",
         "logicOperator": "and",
         "conditions": [
            {
               "conditionType": "name",
               "operatorType": "string_operator",
               "operator": "contains",
               "value": "John"
            }
         ]
      }
   ]
}

Example response

[
   {
      "contactId": "jtLF5i",
      "href": "https://default_server/v3/contacts/jtLF5i",
      "name": "JohnSmith",
      "email": "johnsmith@example.com",
      "origin": "landing_page",
      "dayOfCycle": "108",
      "createdOn": "2018-01-15T13:30:42+0000",
      "campaign": {
         "campaignId": "tamqY",
         "name": "TestCampaign",
         "href": "https://api.getresponse.com/v3/campaigns/tamqY"
      },
      "score": null,
      "reason": null,
      "deletedOn": null
   }
]

You can limit the fetched set of fields by adding query parameters described here.

Basics

Example request

POST v3/search-contacts/contacts

{
  "subscribersType": [
    "subscribed"
  ],
  "sectionLogicOperator": "or",
  "section": [
    {
      "campaignIdsList": [
        "tamqY"
      ],
      "subscriberCycle": [
        "receiving_autoresponder",
        "not_receiving_autoresponder"
      ],
      "subscriptionDate": "all_time",
      "logicOperator": "and",
      "conditions": []
    }
  ]
}

The main search-contact request (segment) is built of 3 fields.

Basic structure of request

{
   "subscribersType": <subscribersType>,
   "sectionLogicOperator": "{sectionLogicOperator}",
   "section": <section-items>
}

Value	Description
<subscribersType>	An array with the following values: "subscribed" - subscribed contacts, "undelivered", "removed" - unsubscribed contacts, "unconfirmed"
{sectionLogicOperator}	Enum(or, and), match 'any' or 'all' of the conditions specified.
<section-items>	A collection of section-item describing the search conditions. Maximum 8 sections are allowed. At least one section is required.

Basic structure of <section-item>

{
   "campaignIdsList": <campaign-ids>,
   "subscriberCycle": <subscriber-cycles>,
   "subscriptionDate": "{subscriptionDate}",
   "customDate": {
      "from": "{utcDateFormat}",
      "to": "{utcDateFormat}"
   },
   "logicOperator": "{conditionLogicOperator}",
   "conditions": <condition-items>
}

The field "customDate" is required only for "subscriptionDate": "custom". You can use up to 8 sections per request.

Fields description

Field	Value	Description
<campaign-ids>	array of strings	An array of campaign identifiers from GET /v3/campaigns.
<subscriber-cycles>	array of strings	An array of following values: receiving_autoresponder, not_receiving_autoresponder determining whether or not a contact has been added to an autoresponder cycle.
{subscriptionDate}	all_time, today, yesterday, last_7_days, last_30_days, this_week, last_week,this_month, last_month, last_2_months, custom	Matches the corresponding period. For custom field "customDate" is required.
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10".	Field "customDate" is required only for "subscriptionDate": "custom".
{conditionLogicOperator}	or, and	Match 'any' or 'all' of the following conditions
<condition-items>	collection of <condition-item>	A collection defining the condition. Up to 8 conditions are allowed.

Conditions used in segments help you narrow down your search results to a specific group of contacts. In the following sections we explain how you can create conditions to quickly identify the contacts you're looking for.

Examples

Find all contacts who were removed from a specific list.

{
   "subscribersType": [
      "removed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "o5lx"
         ],
         "logicOperator": "or",
         "subscriberCycle": [
            "receiving_autoresponder",
            "not_receiving_autoresponder"
         ],
         "subscriptionDate": "all_time"
      }
   ]
}

Contact details

Searching for contacts based on their contact details

Condition	Description
Name	searching for contacts by name
Email	searching for contacts by email
Custom fields	searching for contacts by predefined custom fields
Subscription date	searching for contacts by subscription date
Subscription method	searching for contacts by subscription method

---

Name - searching by name of contact

To find contacts by name, use

"conditionType": "name"

with

"operatorType": "string_operator"

Example condition:

{
    "conditionType": "name",
    "operatorType": "string_operator",
    "operator": "contains",
    "value": "John"
}

Basic structure of name condition:

{
    "conditionType": "name",
    "operatorType": "string_operator",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends",
    "value": "<string>"
}

Table of allowed values and operators:

operatorType	Allowed operators	Allowed values
string_operator	is, is_not, contains, not_contains, starts, ends, not_starts, not_ends	<string>

You can find detailed information about "operatorType": "string_operator" here.

---

Email - search by email of contact

To find contacts by email, use

"conditionType": "email"

with

"operatorType": "string_operator"

Example condition:

Find all contacts whose email address includes "john".

{
    "conditionType": "email",
    "operatorType": "string_operator",
    "operator": "contains",
    "value": "john"
}

Basic structure of email condition:

{
    "conditionType": "email",
    "operatorType": "string_operator",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends",
    "value": "<string>"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
string_operator	is, is_not, contains, not_contains, starts, ends, not_starts, not_ends	<string>

You can find detailed information about "operatorType": "string_operator" here.

---

Custom fields - searching contacts by custom fields

To find contact by custom field, use

"conditionType": "custom"

To use custom fields in your search, you need to fetch their identifiers and possible values from GET /v3/custom-fields.

If field accepts string values, check whether custom field accepts single value or multiple values. For single value use "operatorType": "string_operator". For multiple values use "operatorType": "string_operator_list"

Example condition:

Find all contacts with the custom field "country" set to "Canada".

{
    "conditionType": "custom",
    "scope": "pa3Ih",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Canada"
}

This custom field has multiple string values, so "operatorType": "string_operator_list" have to be used.

"scope": "pa3N6" specifies the ID of the custom field

Possible structures of custom condition:

All custom fields with "operator": "assigned" or "operator": "not_assigned":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "string_operator|string_operator_list|date_operator|numeric_operator",
    "operator": "assigned|not_assigned"
}

String based custom fields with all operators except "operator": "assigned" and "operator": "not_assigned":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "string_operator|string_operator_list",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends",
    "value": "{stringValue}"
}

Date based custom fields with "operator": "specific_date":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "today|yesterday|last_n_days|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month"
}

For the specific "value": "last_n_days" structure of condition is extended by two parameters.

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_n_days",
    "numberOfDays": "<integer>",
    "includeCurrentPeriod": "<boolean>"
}

Field "numberOfDays" required only for "value": "last_n_days". Field "includeCurrentPeriod" is optional and used only with "value": "last_n_days".

Table of allowed fields and their values:

value	allowed values
today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month	field "numberOfDays" prohibited
last_n_days	<integer>

Table of relation between value and includeCurrentPeriod:

value	is includeCurrentPeriod allowed
today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month	field "includeCurrentPeriod" prohibited
last_n_days	<boolean>

Date based custom fields with "operator": "date_to" or "operator": "date_from":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "date_operator",
    "operator": "date_to|date_from",
    "value": "{utcDateFormat}"
}

{utcDateFormat} is a UTC date format, read more in RFC3339, e.g. "2018-04-10"

Date based custom fields with "operator": "custom":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "{rangeUTCDateFormat}"
}

{rangeUTCDateFormat} is a ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format, read more in RFC3339. e.g. "2018-04-02/2018-04-23"

Number based custom fields with all operators except "operator": "assigned" and "operator": "not_assigned":

{
    "conditionType": "custom",
    "scope": "{customFieldId}",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
    "value": "{numericValue}"
}

Some predefined custom fields can be fetched using GET /v3/custom-fields. See the table below for the available operator types for predefined custom fields.

Custom field name	Operator type
age country gender	string_operator_list
birthday	date_operator
city comment company fax home_phone http_referer mobile_phone phone postal_code ref state street url work_phone	string_operator

Find more information about possible values of **`"operatorType"`** in Appendix A.

Example age condition:

Find all contacts with the custom field "age" set to "18-29".

{
    "conditionType": "custom",
    "scope": "pa37y",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "18-29"
}

Example country condition:

Find all contacts with the custom field "country" set to "Canada".

{
    "conditionType": "custom",
    "scope": "pa3Ih",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Canada"
}

Example birthday condition:

Find all contacts with the custom field "birthday" set to between 1970-01-01 and 1979-12-31.

{
    "conditionType": "custom",
    "scope": "pa3Lo",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "1970-01-01/1979-12-31"
}

Example condition with string_operator:

{
    "conditionType": "custom",
    "scope": "pa3Ui",
    "operatorType": "string_operator",
    "operator": "starts",
    "value": "new"
}

---

Subscription date - searching contact by date of subscription

To search contacts by subscription date, use

"conditionType": "subscription_date"

with

"operatorType": "date_operator"

Example condition:

Find all contacts who subscribed between 2018-04-01 and 2018-04-30.

{
    "conditionType": "subscription_date",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "2018-04-01/2018-04-30"
}

Basic structure of subscription date condition:

{
    "conditionType": "subscription_date",
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
date_operator	date_to, date_from	{utcDateFormat}
	specific_date	today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
	custom	{rangeUTCDateFormat}
	assigned, not_assigned	field "value" prohibited

Value	Description
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "operator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "operator": "custom".

You can find detailed information about "operatorType": "date_operator" here.

---

Subscription method - searching contact by method of subscription

Find contacts by subscription methods

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "webform|import|landing_page|api|email|panel|mobile|survey|sales|copy|leads|webinar|chat|website_builder_elegant|course|premium_newsletter",
    "webformType": "all|webforms|webformsv2|popups",
    "value": "all|{webformsId}|{webformsv2Id}|{popupsUuid}|{importId}|{landingPageId}|{webinarId}|{websiteUuid}"
}

The field "value" is prohibited with "webformType": "all".

method	Description
webform	Sign-up via legacy form
import	Added via import
landing_page	Added via landing page
api	Added via api
email	Sign-up via list email address
panel	Added manually
mobile	Sign-up via mobile app
survey	Sing-up via survey
copy	Copied from other list
leads	Added via GetSubscribers.com
webinar	Added via webinar
chat	Added via GR Chat App
website_builder_elegant	Added via website
course	Added via course
premium_newsletter	Added via paid newsletter

webform

Search for contacts who subscribed via a legacy form

Example condition:

Find all contacts who subscribed by any legacy form.

{
  "conditionType": "subscription_method",
  "method": "webform",
  "webformType": "all"
}

Basic structure of condition:

{
  "conditionType": "subscription_method",
  "method": "webform",
  "webformType": "all|webforms|webformsv2|popups",
  "value": "{webformId}|{webformv2Id}|{popupUuid}"
}

The field "value" is prohibited for "webformType": "all".

Value	Description
{webformId}	Legacy form identifier can be fetched from GET /v3/webforms
{webformv2Id}
{popupUuid}	Popup identifier can be fetched from GET /v3/popups

Example conditions:

Find all contacts who subscribed via a specific webform.

{
    "conditionType": "subscription_method",
    "method": "webform",
    "webformType": "webformsv2",
    "value": "PSO39"
}

import

Find imported contacts

Example condition:

Find all imported contacts

{
    "conditionType": "subscription_method",
    "method": "import",
    "value": "all"
}

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "import",
    "value": "all|{importId}"
}

Value	Description
{importId}	Import identifier can be fetched from GET /v3/imports

landing page

Find contact who subscribed via landing page.

Example condition:

Find all contacts who signed up through a specific landing page.

{
    "conditionType": "subscription_method",
    "method": "landing_page",
    "value": "XXqi"
}

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "landing_page",
    "value": "all|{landingPageId}"
}

Value	Description
{landingPageId}	Landing page identifier can be fetched from GET /v3/landing-pages

api

Find contact subscribed via API.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "api"
}

email

Find contacts who signed up through list email address.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "email"
}

panel

Find contacts added manually.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "panel"
}

mobile

Find contacts who signed up via mobile app.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "mobile"
}

survey

Find contacts who subscribed via survey.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "survey"
}

sales

Find contacts who subscribed through sales.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "sales"
}

copy

Find contacts copied from other list.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "copy"
}

leads

To find contact subscribed through leads.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "leads"
}

webinar

To find contacts subscribed through webinar.

Example condition:

Find all contacts who subscribed by any webinar.

{
    "conditionType": "subscription_method",
    "method": "webinar",
    "value": "all"
}

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "webinar",
    "value": "all|{webinarId}"
}

Value	Description
{webinarId}	Webinar identifier can be fetched from GET /v3/webinars

chat

Find contacts who subscribed through the GR Chat application.

Example condition:

Find all contacts subscribed via GR Chat.

{
    "conditionType": "subscription_method",
    "method": "chat"
}

website

Find contacts subscribed using a form embedded on website created with the GR website builder.

Example condition:

Find all contacts subscribed via websites.

{
    "conditionType": "subscription_method",
    "method": "website_builder_elegant",
    "value": "all"
}

Find contacts subscribed via specific website.

{
    "conditionType": "subscription_method",
    "method": "website_builder_elegant",
    "value": "123e4567-e89b-12d3-a456-426614174000"
}

Basic structure of condition:

{
    "conditionType": "website_builder_elegant",
    "method": "webinar",
    "value": "all|{websiteUUID}"
}

Value	Description
{websiteUUID}	Website identifier. It can be found using method: GET /v3/websites

course

Find contact subscribed via a course.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "course"
}

premium_newsletter

Find contacts who signed up via a paid newsletter.

Basic structure of condition:

{
    "conditionType": "subscription_method",
    "method": "premium_newsletter"
}

Contact actions

Action	conditionType	operatorType	Description
Message opened	"opened"	"message_operator"	To find contacts who opened a specific message.
Message not opened	"not_opened"	"complex_message_operator"	To find contacts who didn't open a message.
Autoresponder day	"phase"	"numeric_operator"	To find contacts on a specific day in an autoresponder cycle.
Last send date	"last_send_date"	"date_operator"	To find contacts based on the date an email was last sent to them.
Last click date	"last_click_date"	"date_operator"	To find contacts based on the date they last clicked a link in an email.
Last open date	"last_open_date"	"date_operator"	To find contacts based on the date they last opened an email.
Webinars	"webinar"
Link clicked	"clicked"	"message_operator"	To find contacts who clicked a link.
Link not clicked	"not_clicked"	"complex_message_operator"	To find contacts who didn't click a link.
Message sent	"sent"	"message_operator"	To find contacts who were sent a specific email.
Message not sent	"not_sent"	"message_operator"	To find contacts who were not sent a specific email.

---

Message opened

Example condition:

Find contacts who opened a specific email.

{
    "conditionType": "opened",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "value": "SGNLr"
}

Basic structure of condition:

{
    "conditionType": "opened",
    "operatorType": "message_operator",
    "operator": "newsletter|autoresponder|splittest|automation",
    "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}"
}

You can find detailed information about "operatorType": "message_operator" here.

---

Message not opened

Find contacts who didn't open a specific email.

Example condition:

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "autoresponder",
    "scope": "xyz",
    "dateOperator": "never"
}

Basic structure of condition:

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "all|autoresponder|newsletter|splittest|automation",
    "scope": "{autoresponderId}|{newsletterId}|{splittestId}|{automationId}",
    "dateOperator": "never|date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|this_month",
    "value": "{utcDateFormat}|<integer>",
    "includeCurrentPeriod": "<boolean>"
}

For the specific "scope", set {autoresponderId}|{newsletterId}|{splittestId}|{automationId} otherwise the "scope" field is prohibited.

Field "value" required only for "dateOperator": "date_from|last_n_days", for others "dateOperator" it is prohibited.

Table of allowed fields and their values:

dateOperator	allowed values
never, today, yesterday, last_7_days, last_30_days, this_week, this_month	field "value" prohibited
date_from	{utcDateFormat}
last_n_days	<integer>

Table of relation between dateOperator and includeCurrentPeriod

dateOperator	is includeCurrentPeriod allowed
never, today, yesterday, this_week, this_month	field "includeCurrentPeriod" prohibited
last_7_days, last_30_days, last_n_days	<boolean>

Value	Description
{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	To find {newsletterId} use GET /v3/newsletters
{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "operator": "date_from"

Example conditions:

Find contacts who have never opened any messages.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "all",
    "dateOperator": "never"
}

Find contacts who haven't opened any message for the last 10 days including today.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "all",
    "dateOperator": "last_n_days",
    "value": "10",
    "includeCurrentPeriod": true
}

Find contacts who haven't opened a specific newsletter today.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "dateOperator": "today",
    "scope": "z4Zje"
}

You can find detailed information about "operatorType": "complex_message_operator" here.

---

Autoresponder day

Find contacts by autoresponder day

Example condition:

Find contacts who are on a specific day of the autoresponder cycle.

{
    "conditionType": "phase",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "6"
}

Basic structure of condition:

{
    "conditionType": "phase",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq|assigned|not_assigned",
    "value": "<integer>"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
numeric_operator	numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq	<integer>
	assigned, not_assigned	field "value" prohibited

You can find detailed information about "operatorType": "numeric_operator" here.

---

Last send date

Find contacts based on the date they were last sent an email.

Example condition:

Find contacts who've been sent an email within the last seven days.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_7_days"
}

Basic structure of condition:

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
date_operator	specific_date	today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
	date_to, date_from	{utcDateFormat}
	custom	{rangeUTCDateFormat}

Value	Description
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "operator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "operator": "custom".

You can find detailed information about "operatorType": "date_operator" here.

Example conditions:

Find contacts who were sent a newsletter before 2018-05-06.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-05-06"
}

Find contacts who were sent an email message after 2018-05-06.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "date_from",
    "value": "2018-05-15"
}

Find contacts who were sent an email message in the last seven days.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_7_days"
}

Find contacts who were sent an email message between 2018-05-01 and 2018-05-31.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "2018-05-01/2018-05-31"
}

---

Last click date

Find contacts based on the last time they clicked a message.

Example condition:

Find contacts who clicked a message before 2018-04-30.

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-04-30"
}

Basic structure of condition:

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
date_operator	specific_date	today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
	date_to, date_from	{utcDateFormat}
	custom	{rangeUTCDateFormat}

Value	Description
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "operator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "operator": "custom".

You can find detailed information about "operatorType": "date_operator" here.

Example conditions:

Find contacts who clicked a message after 2018-05-15.

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "date_from",
    "value": "2018-05-15"
}

Find contacts who have clicked a message in the last week.

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_week"
}

Find contacts who clicked a message between 2018-05-01 and 2018-05-31".

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "2018-05-01/2018-05-31"
}

---

Last open date

Find contacts based on when they last opened an email.

Example condition:

Find contacts who opened a message this week.

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "this_week"
}

Basic structure of condition:

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

Table of allowed fields and their values:

operatorType	Allowed operators	Allowed values
date_operator	specific_date	today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
	date_to, date_from	{utcDateFormat}
	custom	{rangeUTCDateFormat}

Value	Description
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "operator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "operator": "custom".

You can find detailed information about "operatorType": "date_operator" here.

Example conditions:

Find contacts who opened a message before 2018-05-01.

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-05-01"
}

Find contacts who opened a message after 2018-05-01.

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "date_from",
    "value": "2018-05-01"
}

Find contacts who opened a message between 2018-05-07 and 2018-05-29.

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "2018-05-07/2018-05-29"
}

---

Webinars

Find contacts cased on participation in a specific webinar as a host, listener, presenter, registrant, or any user.

Example condition:

Find contacts who participated as a presenter during a specific webinar.

{
    "conditionType": "webinar",
    "scope": "MNAR",
    "webinarCondition": "participated",
    "contactType": "presenter",
}

Basic structure of condition:

{
    "conditionType": "webinar",
    "scope": "{webinarId}",
    "webinarCondition": "participated|not_participated",
    "contactType": "host|listener|presenter|registrant|all"
}

Value	Description
{webinarId}	Webinar identifier can be fetched from GET /v3/webinars

---

Link clicked

To find contacts that clicked on the link.

Example condition:

Find contacts who clicked any link in a specific autoresponder email.

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "scope": "SGNLr",
    "clickTrackId": "all"
}

Basic structure of condition:

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "autoresponder|newsletter|splittest|automation",
    "scope": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}",
    "clickTrackId": "all|{clickTrackId}"
}

Value	Description
{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	To find {newsletterId} use GET /v3/newsletters
{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation
{clickTrackId}	To find {clickTrackId} fetch message details. i.e. GET /v3/newsletter/{newsletterId} or use GET /v3/click-tracks

You can find detailed information about "operatorType": "message_operator" here.

Example conditions:

Find contacts who clicked a specific link in a specific autoresponder email.

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "scope": "SGNLr",
    "clickTrackId": "PPxJw9"
}

Find contacts who clicked any link in a specific newsletter.

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "scope": "zlrzy",
    "clickTrackId": "all"
}

Find contacts who clicked a specific link in a specific newsletter.

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "scope": "zlrzy",
    "clickTrackId": "P1Ssv5"
}

---

Link not clicked

Find contacts who didn't click a link.

Example condition:

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "all",
    "dateOperator": "never"
}

Basic structure of condition:

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "all|autoresponder|newsletter|splittest|automation",
    "dateOperator": "date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|last_week|this_month",
    "scope": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}",
    "clickTrackId": "all|{clickTrackId}",
    "value": "{utcDateFormat}|<integer>",
    "includeCurrentPeriod": "<boolean>"
}

For the specific "scope", set {autoresponderId}|{newsletterId}|{splittest-id}|{automationId} otherwise the "scope" field is prohibited. Field "value" required only for "dateOperator": "date_from|last_n_days", for others "dateOperator" it is prohibited.

Table of allowed fields and their values:

dateOperator	allowed values
never, today, yesterday, last_7_days, last_30_days, this_week, this_month	field "value" prohibited
date_from	{utcDateFormat}
last_n_days	<integer>

Table of relation between dateOperator and includeCurrentPeriod:

dateOperator	is includeCurrentPeriod allowed
never, today, yesterday, this_week, this_month	field "includeCurrentPeriod" prohibited
last_7_days, last_30_days, last_n_days	<boolean>

Field "clickTrackId" required only if specific scope is defined.

Value	Description
{newsletterId}	Newsletter identifier can be fetched from GET /v3/newsletters
{autoresponderId}	Autoresponder identifier can be fetched from GET /v3/autoresponders
{splittestId}	Splittest identifier can be fetched from GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation
{clickTrackId}	To find {clickTrackId} fetch message details. i.e. GET /v3/newsletter/{newsletterId} or use GET /v3/click-tracks

Example conditions:

Find contacts who have never clicked any links.

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "all",
    "dateOperator": "never"
}

Find contacts who haven't clicked any link in an autoresponder email since 05/06/2018.

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "autoresponder",
    "dateOperator": "date_from",
    "value": "2018-05-06"
}

Find contacts who haven't clicked any link in a specific newsletter today.

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "dateOperator": "today",
    "scope": "zhgnQ",
    "clickTrackId": "all"
}

Find contacts who haven't clicked a specific link in a specific splittest in the last 20 days including today.

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "splittest",
    "dateOperator": "last_n_days",
    "scope": "zSp9V",
    "value": "20",
    "clickTrackId": "PPxiOW",
    "includeCurrentPeriod": true
}

---

Message sent

Find contacts who were sent a specific message.

Example condition:

Find contacts who were sent a specific splittest.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "splittest",
    "value": "zSp9V"
}

Basic structure of condition:

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "newsletter|autoresponder|splittest|automation",
    "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}"
}

Value	Description
{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	To find {newsletterId} use GET /v3/newsletters
{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation

You can find detailed information about "operatorType": "message_operator" here.

Example conditions:

Find contacts who were sent a specific autoresponder email.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "value": "SY6kx"
}

Find contacts who were sent a specific newsletter.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "value": "z4Zje"
}

Find contacts who were sent a specific splittest.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "splittest",
    "value": "zSp9V"
}

To find contacts who were sent a specific automation message.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "automation",
    "value": "zSFIB"
}

---

Message not sent

Find contacts who weren't sent a specific message.

Example condition:

Find contacts who weren't sent a specific newsletter.

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "value": "z4Zje"
}

Basic structure of condition:

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "newsletter|autoresponder|splittest|automation",
    "value": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}"
}

Value	Description
{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	To find {newsletterId} use GET /v3/newsletters
{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation

You can find detailed information about "operatorType": "message_operator" here.

Example conditions:

Find contacts who weren't sent a specific autoresponder email.

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "value": "SY6kx"
}

Find contacts who weren't sent a specific newsletter.

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "value": "zhCwy"
}

Find contacts who weren't sent a specific splittest.

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "splittest",
    "value": "zSp9V"
}

Find contacts who weren't sent a specific automation message.

{
    "conditionType": "not_sent",
    "operatorType": "message_operator",
    "operator": "automation",
    "value": "zSFIB"
}

Geolocation

Search for contacts by geolocation.

Example condition

Find contacts whose city name start with "new".

{
    "conditionType": "geo",
    "operatorType": "string_operator",
    "operator": "starts",
    "value": "New",
    "scope": "city"
}

Basic structure of condition

{
    "conditionType": "geo",
    "operatorType": "string_operator",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends",
    "value": "<string>",
    "scope": "country|country_code|region|city|longitude|latitude|postal_code|dma_code"
}

Table of allowed fields and their values

operatorType	Allowed operators	Allowed values
string_operator	is, is_not, contains, not_contains, starts, ends, not_starts, not_ends	<string>

You can find detailed information about "operatorType": "string_operator" here.

GDPR

Search for contacts based on given or not given consents.

Basic structure of condition

{
  "conditionType": "gdpr",
  "consentStatus": "given|not_given",
  "gdprFieldId": "{gdprFieldId}",
  "consentDate": {
    "operator": "anytime|dateFrom|dateTo",
    "date": "{utcDateFormat}"
  }
}

Dependencies between operator field and date field:

operator	date
anytime	field date is prohibited
date_from, date_to	Field date is required and have to be provided in format: {utcDateFormat}

Values description:

Value	Description
{gdprFieldId}	To find {gdprFieldId} use GET /v3/getGDPRFieldList
{utcDateFormat}	UTC date format RFC3339, e.g. "2024-11-08". Only for "operator": "date_from|date_to"

Examples:

Find contacts who give a consent abc.

{
  "conditionType": "gdpr",
  "consentStatus": "given",
  "gdprFieldId": "abc",
  "consentDate": {
    "operator": "anytime"
  }
}

Find contacts who haven't given consent abc by 2023-12-31.

{
  "conditionType": "gdpr",
  "consentStatus": "not_given",
  "gdprFieldId": "abc",
  "consentDate": {
    "operator": "date_to",
    "date": "2023-12-31"
  }
}

Scoring

Searching for contacts by score.

Example condition

Find contacts whose score is lower than 5.

{
    "conditionType": "score",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt",
    "value": "5"
}

Basic structure of condition

{
    "conditionType": "score",
    "operatorType": "numeric_operator|not_exists",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
    "value": "<integer>"
}

If "operatorType": "not_exists" is defined, fields "operator" and "value" are prohibited.

Table of allowed fields and their values

operatorType	Allowed operators	Allowed values
numeric_operator	numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq	<integer>
not_exists		fields "operator" and "value" prohibited

You can find detailed information for "operatorType" equal to "numeric_operator" and "not_exists" here.

Example conditions

Find contacts whose score is greater than or equal to 44.

{
    "conditionType": "score",
    "operatorType": "numeric_operator",
    "operator": "numeric_gt_eq",
    "value": "44"
}

Find contacts who have no score.

{
    "conditionType": "score",
    "operatorType": "not_exists"
}

Engagement Score

Searching for contacts by engagement score.

Example condition

Find contacts whose engagement score is lower than 5.

{
    "conditionType": "engagement_score",
    "operator": "numeric_lt",
    "value": "5"
}

Basic structure of condition

{
    "conditionType": "engagement_score",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
    "value": "<integer>"
}

Table of allowed fields and their values

Allowed operators	Allowed values
numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq	<integer>

Example conditions

Find contacts whose engagement score is greater than or equal to 3.

{
    "conditionType": "engagement_score",
    "operator": "numeric_gt_eq",
    "value": "3"
}

Tags

Search for contacts by tags.

Example condition

{
    "conditionType": "tag",
    "value": "BB",
    "operatorType": "exists",
    "operator": "exists"
}

Basic structure of condition

{
    "conditionType": "tag",
    "value": "{tagId}",
    "operatorType": "exists",
    "operator": "exists|not_exists"
}

Value	Description
{tagId}	Tag identifier can be fetched from GET /v3/tags

You can find detailed information about "operatorType": "exists" here.

Ecommerce

Searching for contacts by ecommerce parameters.

{conditionType}	Description
ecommerce_number_of_purchases	Searching for contacts by the number of purchases made.
ecommerce_total_spent	Searching for contacts by total spent.
ecommerce_product_purchased	Searching for contacts by product purchased.
ecommerce_brand_purchased	Searching for contacts by brand purchased.
ecommerce_abandoned_cart	Searching for contacts by abandoned cart.

---

ecommerce_number_of_purchases

Searching for contacts by the number of purchases made.

Example condition:

Find contacts who bought 7 products in a specific store.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "7",
    "date": {
        "operator": "anytime"
    }
}

Basic structure of condition:

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all|{shopId}",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
    "value": "<integer>",
    "date": {
        "operator": "anytime|today|yesterday|last_n_days|this_week|last_week|this_month|last_month|last_2_months|custom",
        "range": "{rangeUTCDateFormat}",
        "numberOfDays": "<integer>",
        "includeCurrentPeriod": "<boolean>"
    }
}

Table of allowed fields and their values:

Field	Allowed operators	Allowed values
operatorType	numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq	Field value <integer> is required.
date.operator	anytime, today, yesterday, this_week, last_week, this_month, last_month, last_2_months	No values required. Fields date.numberOfDays, date.includeCurrentPeriod, date.range are prohibited.
	last_n_days	Fields date.numberOfDays <integer>, date.includeCurrentPeriod <boolean> are required. Field date.range is prohibited.
	custom	Field date.range {rangeUTCDateFormat} is required. Fields date.numberOfDays, date.includeCurrentPeriod are prohibited.

Value	Description
{shopId}	Shop identifier can be fetched from GET /v3/shops
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "date": {"operator": "custom"}.

Example conditions:

Search all stores to find contacts who bought 7 products.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "7",
    "date": {
        "operator": "anytime"
    }
}

Find contacts who bought fewer than 5 products from a specific store.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "ZTo",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt",
    "value": "5",
    "date": {
        "operator": "anytime"
    }
}

Search all stores to find contacts who bought 7 products on last 17 days excluding today.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "7",
    "date": {
        "operator": "last_n_days",
        "numberOfDays": "17",
        "includeCurrentPeriod": "false"
    }
}

Search all stores to find contacts who bought 7 products on last week.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "7",
    "date": {
        "operator": "last_week"
    }
}

Search all stores to find contacts who bought 7 products on custom date range.

{
    "conditionType": "ecommerce_number_of_purchases",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "7",
    "date": {
        "operator": "custom",
        "range": "2018-04-02/2018-04-23"
    }
}

---

ecommerce_total_spent

Search for contacts by total spent.

Example condition:

Search all stores to find contacts who spent a total of 5.00 USD.

{
    "conditionType": "ecommerce_total_spent",
    "scope": "all",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "5.00",
    "currency": "USD",
    "date": {
        "operator": "anytime"
    }
}

Basic structure of condition:

{
    "conditionType": "ecommerce_total_spent",
    "scope": "all|{shopId}",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
    "value": "<integer>",
    "currency": "{currencyCode}",
    "date": {
        "operator": "anytime|today|yesterday|last_n_days|this_week|last_week|this_month|last_month|last_2_months|custom",
        "range": "{rangeUTCDateFormat}",
        "numberOfDays": "<integer>",
        "includeCurrentPeriod": "<boolean>"
    }
}

Table of allowed fields and their values:

Field	Allowed operators	Allowed values
operatorType	numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq	Field value <integer> is required.
date.operator	anytime, today, yesterday, this_week, last_week, this_month, last_month, last_2_months	No values required. Fields date.numberOfDays, date.includeCurrentPeriod <boolean>, date.range are prohibited.
	last_n_days	Fields date.numberOfDays <integer>, date.includeCurrentPeriod <boolean> are required. Field date.range is prohibited.
	custom	Field date.range {rangeUTCDateFormat} is required. Fields date.numberOfDays, date.includeCurrentPeriod are prohibited.

Value	Description
{shopId}	Shop identifier can be fetched from GET /v3/shops
{currencyCode}	Currency codes compatible with ISO 4217. List of currency codes listed here
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "date": {"operator": "custom"}.

Example conditions:

Search all stores to find contacts who spent a total of 5.00 USD.

{
    "conditionType": "ecommerce_total_spent",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "5.00",
    "scope": "all",
    "currency": "USD",
    "date": {
        "operator": "anytime"
    }
}

Find contacts that spent a total of 8.00 EUR from a specific store.

{
    "conditionType": "ecommerce_total_spent",
    "operatorType": "numeric_operator",
    "operator": "numeric_not_eq",
    "value": "8.00",
    "scope": "ZTo",
    "currency": "EUR",
    "date": {
        "operator": "anytime"
    }
}

Search all stores to find contacts who spent a total of 5.00 USD on last 25 days including today.

{
    "conditionType": "ecommerce_total_spent",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "5.00",
    "scope": "all",
    "currency": "USD",
    "date": {
        "operator": "last_n_days",
        "numberOfDays": "25",
        "includeCurrentPeriod": "true"
    }
}

Search all stores to find contacts who spent a total of 5.00 USD on custom date range.

{
    "conditionType": "ecommerce_total_spent",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "5.00",
    "scope": "all",
    "currency": "USD",
    "date": {
        "operator": "custom",
        "range": "2018-04-02/2018-04-23"
    }
}

Search all stores to find contacts who spent a total of 5.00 USD on last month.

{
    "conditionType": "ecommerce_total_spent",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "5.00",
    "scope": "all",
    "currency": "USD",
    "date": {
        "operator": "last_month"
    }
}

---

ecommerce_product_purchased

This condition type allows to search product purchased from (all shops)/(specified shop) for (any category)/(specified category) where (any product)/(specified product) (is)/(isn't) purchased (in time period)/(to specified date)/(from specified date).

Example condition:

Find contacts who have purchased products in any category starting 2018-04-02.

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all",
    "categoryScope": "all",
    "operatorType": "equal_operator",
    "operator": "is",
    "productScope": "all",
    "dateOperator": "date_from",
    "value": "2018-04-02"
}

Basic structure of condition:

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all|{shopId}",
    "categoryScope": "all|{categoryId}",
    "operatorType": "equal_operator",
    "operator": "is|is_not",
    "productScope": "all|{productId}",
    "dateOperator": "all_time|date_to|date_from|today|yesterday|last_7_days|last_30_days|last_n_days|this_week|last_week|this_month|last_month|last_2_month|custom",
    "value": "{utcDateFormat}|{rangeUTCDateFormat}"
}

Table of allowed fields and their values:

Field	Allowed operators	Allowed values
dateOperator	date_to, date_from	Field value {utcDateFormat} is required. Fields numberOfDays, includeCurrentPeriod are prohibited.
	all_time, today, yesterday, this_week, last_week, this_month, last_month, last_2_month	No values required. Fields value, numberOfDays, includeCurrentPeriod are prohibited.
	last_n_days	Fields numberOfDays <integer>, includeCurrentPeriod <boolean> are required. Field value is prohibited.
	last_7_days, last_30_days	No values required. Fields value, numberOfDays are prohibited. Field includeCurrentPeriod <boolean> is optional.
	custom	Field value {rangeUTCDateFormat} is required. Fields numberOfDays, includeCurrentPeriod are prohibited.

Value	Description
{shopId}	Shop identifier can be fetched from GET /v3/shops
{categoryId}	Category identifier can be fetched from GET /v3/shops/{shopId}/categories
{productId}	Product identifier can be fetched from GET /v3/shops/{shopId}/products
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "dateOperator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "dateOperator": "custom".

For the specific "dateOperator": "last_n_days" structure of condition is extended by two parameters.

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all|{shopId}",
    "categoryScope": "all|{categoryId}",
    "operatorType": "equal_operator",
    "operator": "is|is_not",
    "productScope": "all|{productId}",
    "dateOperator": "last_n_days",
    "numberOfDays": "<integer>",
    "includeCurrentPeriod": "<boolean>"
}

For the specific "dateOperator": "last_7_days|last_30_days" structure of condition is extended by one parameter.

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all|{shopId}",
    "categoryScope": "all|{categoryId}",
    "operatorType": "equal_operator",
    "operator": "is|is_not",
    "productScope": "all|{productId}",
    "dateOperator": "last_7_days|last_30_days",
    "includeCurrentPeriod": "<boolean>"
}

Field "numberOfDays" required only for "dateOperator": "last_n_days". Field "includeCurrentPeriod" required only for "dateOperator": "last_n_days". Optional for "dateOperator": "last_7_days|last_30_days"

Table of allowed fields and their values:

dateOperator	allowed values
all_time, today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month, custom	Field "numberOfDays" is prohibited.
last_n_days	<integer>

Table of relation between value and includeCurrentPeriod:

dateOperator	is includeCurrentPeriod allowed
all_time, today, yesterday, this_week, last_week, this_month, last_month, last_2_month	Field "includeCurrentPeriod" is prohibited.
last_7_days, last_30_days, last_n_days	<boolean>

Example conditions:

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all",
    "categoryScope": "all",
    "operatorType": "equal_operator",
    "operator": "is",
    "productScope": "all",
    "dateOperator": "all_time"
}

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all",
    "categoryScope": "all",
    "operatorType": "equal_operator",
    "operator": "is_not",
    "productScope": "P",
    "dateOperator": "all_time"
}

{
    "conditionType": "ecommerce_product_purchased",
    "categoryScope": "all",
    "productScope": "all",
    "operatorType": "equal_operator",
    "operator": "is",
    "shopScope": "ZTo",
    "dateOperator": "date_to",
    "value": "2018-05-07"
}

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "ZTo",
    "categoryScope": "P",
    "operatorType": "equal_operator",
    "operator": "is_not",
    "productScope": "all",
    "dateOperator": "custom",
    "value": "2018-05-01/2018-05-31"
}

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "ZTo",
    "categoryScope": "P",
    "operatorType": "equal_operator",
    "operator": "is_not",
    "productScope": "all",
    "dateOperator": "all_time"
}

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "ZTo",
    "categoryScope": "P",
    "operatorType": "equal_operator",
    "operator": "is_not",
    "productScope": "all",
    "dateOperator": "last_n_days",
    "numberOfDays": "30",
    "includeCurrentPeriod": "false"
}

---

ecommerce_brand_purchased

Search for contacts by brand purchased.

Example condition:

{
    "conditionType": "ecommerce_brand_purchased",
    "scope": "ZTo",
    "operatorType": "equal_operator",
    "operator": "is",
    "value": "Vendor1"
}

Basic structure of condition:

{
    "conditionType": "ecommerce_brand_purchased",
    "scope": "{shopId}",
    "operatorType": "equal_operator",
    "operator": "is|is_not",
    "value": "{vendorName}",

}

Value	Description
{shopId}	Shop identifier can be fetched from GET /v3/shops
{vendorName}	One of values from vendor field added to products GET /v3/shops/{shopId}/products

Example conditions:

{
    "conditionType": "ecommerce_brand_purchased",
    "scope": "ZTo",
    "operatorType": "equal_operator",
    "operator": "is",
    "value": "Vendor1"
}

{
    "conditionType": "ecommerce_brand_purchased",
    "scope": "ZTo",
    "operatorType": "equal_operator",
    "operator": "is_not",
    "value": "Vendor2"
}

---

ecommerce_abandoned_cart

Find contacts who abandoned their cart.

Example condition:

{
    "conditionType": "ecommerce_abandoned_cart",
    "shopScope": "all",
    "dateOperator": "date_from",
    "value": "2022-04-02",
    "cartValue": {
        "operator": "numeric_gt_eq",
        "value": "1",
        "currency": "USD",
    }
}

Basic structure of condition:

{
    "conditionType": "ecommerce_abandoned_cart",
    "shopScope": "all|{shopId}",
    "dateOperator": "anytime|never||date_from|today|yesterday|this_week|last_week|this_month|last_month|last_n_days|custom",
    "value": "{utcDateFormat}|<integer>",
    "includeCurrentPeriod": "<boolean>",
    "range": "{rangeUTCDateFormat}",
    "cartValue": {
        "operator": "numeric_lt|numeric_gt|numeric_eq|numeric_not_eq|numeric_lt_eq|numeric_gt_eq",
        "value": "<integer>",
        "currency": "{currencyCode}"
    }
}

Field "value" required only for "dateOperator": "date_from|last_n_days", for others "dateOperator" it is prohibited. Field "includeCurrentPeriod" is optional and used only with "value": "last_n_days", for others "dateOperator" it is prohibited. Field "range" required only for "value": "custom", for others "dateOperator" it is prohibited.

Table of allowed fields and their values:

Field	Allowed operators	Allowed values
dateOperator	date_from	{utcDateFormat}
	anytime, never, today, yesterday, this_week, last_week, this_month, last_month, custom	Field "value" is prohibited.
	last_n_days	<integer>
	custom	{rangeUTCDateFormat}

Value	Description
{shopId}	Shop identifier can be fetched from GET /v3/shops
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for "dateOperator": "date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e."date_from/date_to" where date_from and date_to are in the UTC formatRFC3339. e.g. "2018-04-02/2018-04-23". Only for "dateOperator": "custom".
{currencyCode}	Currency codes compatible with ISO 4217. List of currency codes listed here

Example conditions:

{
    "conditionType": "ecommerce_abandoned_cart",
    "shopScope": "all",
    "dateOperator": "anytime",
    "cartValue": {
        "operator": "numeric_gt_eq",
        "value": "1",
        "currency": "USD",
    }
}

{
    "conditionType": "ecommerce_abandoned_cart",
    "shopScope": "all",
    "dateOperator": "date_from",
    "value": "2018-05-07",
    "cartValue": {
        "operator": "numeric_gt_eq",
        "value": "1",
        "currency": "USD"
    }
}

{
    "conditionType": "ecommerce_abandoned_cart",
    "shopScope": "ZTo",
    "dateOperator": "last_n_days",
    "value": 18,
    "includeCurrentPeriod": true,
    "cartValue": {
        "operator": "numeric_gt_eq",
        "value": "1",
        "currency": "USD",
    }
}

SMS (Text messaging)

Searching for contacts using SMS parameters.

{conditionType}	Description
sms_sent	Find contacts who were sent a specific SMS.
sms_delivered	Find contacts who received a specific SMS.
sms_link_clicked	Find contacts who clicked a specific link.
sms_link_not_clicked	Find contacts who didn't click a specific link.

---

sms_sent

Find contacts who were sent a specific SMS.

Example condition:

Find contacts who were sent an SMS with an identifier ABc.

{
    "conditionType": "sms_sent",
    "smsId": "ABc",
    "deliveryStatus": "any"
}

Find contacts who received an SMS with an identifier ABc.

{
    "conditionType": "sms_sent",
    "smsId": "ABc",
    "deliveryStatus": "delivered"
}

Basic structure of condition:

{
    "conditionType": "sms_sent",
    "smsId": "{smsId}",
    "deliveryStatus": "delivered|undelivered|any"
}

Value	Description
{smsId}	Sms identifier can be fetched from GET /v3/sms
deliveryStatus	Specifies the current status of delivery for a given SMS. This field allows you to filter contacts based on their delivery progress. You may omit this field or set any if the delivery status is not relevant to your search.

---

sms_link_clicked

Find contacts who clicked a specific link from a specific SMS.

Example condition:

Find contacts who clicked a link with an identifier L from an SMS with an identifier ABc.

{
    "conditionType": "sms_link_clicked",
    "smsId": "ABc",
    "clickTrackId": "L"
}

Basic structure of condition:

{
    "conditionType": "sms_link_clicked",
    "smsId": "{smsId}",
    "clickTrackId": "{clickTrackId}"
}

Value	Description
{smsId}	SMS identifier can be fetched from GET /v3/sms
{clickTrackId}	To get {clickTrackId}, fetch the message details from GET /v3/sms/{smsId} or use GET /v3/click-tracks

---

sms_link_not_clicked

Find contacts who didn't click a specific link from a specific SMS.

Example condition:

Find contacts who didn't click a link with an identifier L from an SMS with an identifier ABc.

{
    "conditionType": "sms_link_not_clicked",
    "smsId": "ABc",
    "clickTrackId": "L"
}

Basic structure of condition:

{
    "conditionType": "sms_link_not_clicked",
    "smsId": "{smsId}",
    "clickTrackId": "{clickTrackId}"
}

Value	Description
{smsId}	SMS identifier can be fetched from GET /v3/sms
{clickTrackId}	To get {clickTrackId}, fetch the message details from GET /v3/sms/{smsId} or use GET /v3/click-tracks

Custom Events

Search for contacts by custom events.

Example conditions

Find contacts for which the custom event with identifier BB not occurred anytime:

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "not_occurred",
    "dateOperator": "anytime"
}

Find contacts for which the custom event with identifier BB occurred yesterday:

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "occurred",
    "dateOperator": "yesterday"
}

Find contacts for which the custom event with identifier BB not occurred in last 2 months:

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "not_occurred",
    "dateOperator": "last_2_months"
}

Find contacts for which the custom event with identifier BB occurred after 2000-01-01

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "occurred",
    "dateOperator": "date_from",
    "date": "2000-01-01"
}

Find contacts for which the custom event with identifier BB occurred before 2000-01-01

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "occurred",
    "dateOperator": "date_to",
    "date": "2000-01-01"
}

Find contacts for which the custom event with identifier BB occurred between 2000-01-01 and 2000-01-31

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "occurred",
    "dateOperator": "custom",
    "date": "2000-01-01/2000-01-31"
}

Basic structure of condition

{
    "conditionType": "custom_event",
    "customEventId": "{customEventId}",
    "occurrence": "occurred|not_occurred",
    "dateOperator": "anytime|date_to|date_from|custom|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_months",
    "date": "{utcDateFormat}|{rangeUTCDateFormat}"
}

Table of allowed dateOperator values:

Field	Allowed operators	Allowed values
dateOperator	date_to, date_from	{utcDateFormat}
	anytime, today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month	Field date is prohibited.
	custom	{rangeUTCDateFormat}

Table of allowed data types:

Value	Description
{customEventId}	Custom Event identifier can be fetched from GET /v3/custom-events
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10". Only for"dateOperator": "date_to|date_from".
{rangeUTCDateFormat}	ISO8601 format date interval, i.e."date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23". Only for "dateOperator": "custom".

Segment response

Basic structure of response:

{
   "contactId": "{contactId}",
   "href": "https://api.getresponse.com/v3/contacts/{contactId}",
   "name": "{nameOfContact}",
   "email": "{emailOfContact}",
   "origin": "{origin}",
   "dayOfCycle": "{dayOfCycle}",
   "createdOn": "{createdOn}",
   "campaign": {
      "campaignId": "{campaignId}",
      "name": "{campaignName}",
      "href": "https://api.getresponse.com/v3/campaigns/{campaignId}"
   },
   "score": "{score}",
   "reason": "{reason}",
   "deletedOn": "{deletedOn}"
}

The response structure is compatible with GET /v3/contacts.

Create a new segment

This endpoint allows you to create a new segment. You first need to familiarize yourself with the basic concepts from POST /v3/search-contacts/contacts.

Example request

POST /v3/search-contacts

{
   "name": "custom test filter",
   "subscribersType": [
      "subscribed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "tamqY"
         ],
         "logicOperator": "and",
         "subscriberCycle": [
            "receiving_autoresponder",
            "not_receiving_autoresponder"
         ],
         "subscriptionDate": "all_time",
         "conditions": [
            {
               "conditionType": "name",
               "operatorType": "string_operator",
               "operator": "contains",
               "value": "John"
            }
         ]
      }
   ]
}

Example of response

{
   "searchContactId": "b3EkT",
   "name": "custom test filter",
   "createdOn": "2018-05-04T15:59:44+0000",
   "subscribersType": [
      "subscribed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "tamqY"
         ],
         "logicOperator": "and",
         "subscriberCycle": [
            "receiving_autoresponder",
            "not_receiving_autoresponder"
         ],
         "subscriptionDate": "all_time",
         "conditions": [
            {
               "conditionType": "name",
               "operatorType": "string_operator",
               "operator": "contains",
               "value": "John"
            }
         ]
      }
   ],
   "href": "https://api.getresponse.com.agierszewski.u.c/v3/search-contacts/b3EkT"
}

Basic structure of request

{
   "name": "{searchContactName}",
   "subscribersType": <subscribersType>,
   "sectionLogicOperator": "{sectionLogicOperator}",
   "section": <section-items>
}

The structure of the request is almost the same as in POST /v3/search-contacts/contacts. This is different with the addition of a new "name" field that specifies the unique segment name.

Value	Description	Limitations
{searchContactName}	Unique name of segment	Expected string length between: 1 and 128
<subscribersType>	An array with the following values: "subscribed", "undelivered", "removed", "unconfirmed"	An array should contain only one element. Although validation allows for many elements (due to BC), only the first one will be taken into account
{sectionLogicOperator}	Enum(or, and), match 'any' or 'all' of the following sections of described conditions
<section-items>	A collection of section-item describing the search conditions	Up to 8 sections are allowed.

Basic structure of response

{
    "searchContactId": "{searchContactId}",
    "name": "{searchContactName}",
    "createdOn": "{createdOn}",
    "subscribersType": <subscribersType>,
    "sectionLogicOperator": "{sectionLogicOperator}",
    "section": <section-items>,
    "href": "https://api.getresponse.com/v3/search-contacts/{searchContactId}"
}

Value	Description
{searchContactId}	Unique segment identifier
{createdOn}	UTC date format RFC3339 i.e. "2018-04-19T14:37:02+0000"
<subscribersType>	An array with the following values: "subscribed", "undelivered", "removed", "unconfirmed"
{searchContactName}	Unique name of segment
{sectionLogicOperator}	Enum(or, and), match 'any' or 'all' of the following sections of described conditions
<section-items>	A collection of section-item describing the search conditions.

Retrieve a collection of a short representation of a segment

This endpoint allows you to retrieve a collection of a short representation of a segment. Every item represents a basic filter object. To learn more about the CONDITIONS used in the segment, go to section /v3/search-contact/{searchContactId}

Return

If the request is successful, returns HTTP 200 code with collection of segment items.

Example request

GET /v3/search-contacts

Example response

[
    {
        "searchContactId": "b3EGI",
        "name": "custom search contact filter 1",
        "createdOn": "2018-04-19T14:37:02+0000",
        "href": "https://api.getresponse.com/v3/search-contacts/b3EGI"
    },
    {
        "searchContactId": "t8AO6",
        "name": "custom search contact filter 2",
        "createdOn": "2018-04-19T14:37:02+0000",
        "href": "https://api.getresponse.com/v3/search-contacts/t8AO6"
    }
]

Basic structure of response

{
    "searchContactId": "{searchContactId}",
    "name": "{searchContactName}",
    "createdOn": "{createdOn}",
    "href": "https://api.getresponse.com/v3/search-contacts/{searchContactId}"
}

Value	Description
{searchContactId}	Unique segment (search-contact) identifier
{searchContactName}	Unique name of search-contact
{createdOn}	UTC date time format RFC3339, e.g. 2018-04-10T10:02:57+0000

You can limit the set of fields fetched by adding query parameters described here.

Retrieve detailed information about a specific segment

This endpoint retrieves more detailed information about a specific segment. It describes all conditions used for the segment specified.

Return

Returns the detailed description of segment with all defined conditions.

Request

GET /v3/search-contacts/{searchContactId}

Example response

{
   "searchContactId": "b3Eta",
   "name": "custom test filter",
   "createdOn": "2018-04-23T12:07:15+0000",
   "subscribersType": [
      "subscribed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "tamqY"
         ],
         "logicOperator": "and",
         "subscriberCycle": [
            "receiving_autoresponder",
            "not_receiving_autoresponder"
         ],
         "subscriptionDate": "all_time",
         "conditions": [
            {
               "conditionType": "name",
               "operatorType": "string_operator",
               "operator": "is",
               "value": "John"
            }
         ]
      }
   ],
   "href": "https://api.getresponse.com/v3/search-contacts/b3Eta"
}

A detailed description of the results can be found at POST /v3/search-contacts.

Update the existing search

This endpoint allow to update the existing search.
Resource payload is the same as a segment without saving the search

POST /v3/search-contacts/contacts.

Sample request

POST /v3/search-contacts/b3Eta/

{
    "name": "updated custom filter",
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "tamqY"
            ],
            "logicOperator": "and",
            "subscriberCycle": [
                "receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "custom",
                    "scope": "pa3Ih",
                    "operatorType": "string_operator_list",
                    "operator": "is",
                    "value": "Ireland"
                }
            ]
        }
    ]
}

Sample response

{
   "searchContactId": "b3Eta",
   "name": "updated custom filter",
   "createdOn": "2018-04-27T12:55:05+0000",
   "subscribersType": [
      "subscribed"
   ],
   "sectionLogicOperator": "or",
   "section": [
      {
         "campaignIdsList": [
            "tamqY"
         ],
         "logicOperator": "and",
         "subscriberCycle": [
            "receiving_autoresponder"
         ],
         "subscriptionDate": "all_time",
         "conditions": [
            {
               "conditionType": "custom",
               "scope": "pa3Ih",
               "operatorType": "string_operator_list",
               "operator": "is",
               "value": "Ireland"
            }
         ]
      }
   ],
   "href": "https://api.getresponse.com/v3/search-contacts/b3Eta"
}

You can limit the set of fields fetched by adding query parameters described here.

Delete a specified segment

This endpoint allow to delete a specified segment.

Example request

DELETE /v3/search-contacts/b3Eta

Example response

HTTP 204 resource deleted successfully

Fetch all contacts that match the specified segment

This endpoint allow to fetch all contact that match the specified segment.

Example request

GET /v3/search-contacts/{searchContactId}/contacts

Example response

[
   {
      "contactId": "jtLF5i",
      "href": "https://default_server/v3/contacts/jtLF5i",
      "name": "JohnSmith",
      "email": "johnsmith@example.com",
      "origin": "landing_page",
      "dayOfCycle": "108",
      "createdOn": "2018-01-15T13:30:42+0000",
      "campaign": {
         "campaignId": "tamqY",
         "name": "TestCampaign",
         "href": "https://api.getresponse.com/v3/campaigns/tamqY"
      },
      "score": null,
      "reason": null,
      "deletedOn": null
   }
]

Add and update custom field values for all contacts that meet the search criteria

The method allows adding and updating custom field values for all contacts that meet the search criteria. This method does not remove or overwrite custom fields with values from the request.

Returns status code HTTP 202

Example request

POST /v3/search-contacts/b3Eta/custom-fields

{
   "customFieldValues": [
      {
         "customFieldId": "jHwRjh",
         "value": [
            "white"
         ]
      }
   ]
}

Basic structure of request

{
   "customFieldValues": [
      {
         "customFieldId": "{customFieldId}",
         "value": [
            "<string>"
         ]
      }
   ]
}

Value	Description
{customFieldId}	Custom field identifier. To find {customFieldId} use GET /v3/custom-fields.

Appendix A - full list of operator types

Not every "operator" value can be used for a given condition. A full list of available operators for the condition is given in the description of the condition.

• string_operator
• string_operator_list
• date_operator
• numeric_operator
• message_operator
• exists
• not_exists
• complex_message_operator
• equal_operator

"string_operator"

This "operatorType" allows to search for a string or a substring.

Example condition

{
    "conditionType": "name",
    "operatorType": "string_operator",
    "operator": "contains",
    "value": "John"
}

Basic structure of condition

{
    ...,
    "operatorType": "string_operator",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends|assigned|not_assigned",
    "value": "<string>"
}

Where <string> is any string

Table of relation between operator and value field

Value of field operator	Is field value required?	Value of field value	Additional information
is is_not contains not_contains starts ends not_starts not_ends	Required	<string>	This operator allows you to search for a string, substring
assigned not_assigned	Prohibited		Available only for custom field condition ("conditionType": "custom")

Descriptions of possible values of field "operator"

Value of field operator	Description
is	Is the same as "value"
is_not	Is not the same as "value"
contains	Contains "value" as substring,
not_contains	Not contains "value" as substring
starts	"value" is the beginning of the string
ends	"value" is the end of the string
not_starts	"value" is not the beginning of the string
not_ends	"value" is not the end of the string
assigned
not_assigned

Example conditions

{
    "conditionType": "custom",
    "scope": "pa3Ui",
    "operatorType": "string_operator",
    "operator": "starts",
    "value": "new"
}

{
    "conditionType": "custom",
    "scope": "pa37y",
    "operatorType": "string_operator_list",
    "operator": "assigned"
}

"string_operator_list"

The operator allows searching for a defined collection. "string_operator_list" can be used only in custom field condition ("conditionType": "custom")

Example condition

Find all contacts with the custom field "country" set to "Canada".

{
    "conditionType": "custom",
    "scope": "pa3Ih",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Canada"
}

Basic structure of condition

{
    "operatorType": "string_operator_list",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends|assigned|not_assigned",
    "value": "<string>"
}

Where <string> is any string

Table of relation between operator and value field

Value of field operator	Is field value required?	Value of field value	Additional information
is is_not contains not_contains starts ends not_starts not_ends	Required	<string>	This operator allows you to search for a string, substring
assigned, not_assigned	Prohibited		Available only for custom field condition ("conditionType": "custom")

Example conditions

Find all contacts with the custom field "age" set to "18-29".

{
    "conditionType": "custom",
    "scope": "pa37y",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "18-29"
}

Find all contacts with the custom field "country" set to "Canada".

{
    "conditionType": "custom",
    "scope": "pa3Ih",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Canada"
}

"date_operator"

The operator allows searching by date.

Example condition

Find contacts who were sent an email message till 2018-05-06.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-05-06"
}

Basic structure of condition

{
   ...,
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

Table of relation between operator and value field

Value of field operator	Is field value required?	Value of field value	Additional information
date_to, date_from	Required	{utcDateFormat}	UTC date format RFC3339 e.g.
specific_date	Required	one of the following values: today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month	{rangeUTCDateFormat} is string in form of "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23"
custom	Required	{rangeUTCDateFormat}	{rangeUTCDateFormat} is string ISO8601 format date interval, i.e. "date_from/date_to" where date_from and date_to are in the UTC format RFC3339. e.g. "2018-04-02/2018-04-23"

Example conditions

Find contacts who have been sent an email within the last seven days.

{
    "conditionType": "last_send_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_7_days"
}

Find all contacts with custom field "birthday" set to "between 1970-01-01 and 1979-12-31".

{
    "conditionType": "custom",
    "scope": "pa3Lo",
    "operatorType": "date_operator",
    "operator": "custom",
    "value": "1970-01-01/1979-12-31"
}

"numeric_operator"

The operator allows searching by numeric fields.

Example condition

Find contacts which are on a specific day in an autoresponder cycle.

{
    "conditionType": "phase",
    "operatorType": "numeric_operator",
    "operator": "numeric_eq",
    "value": "6"
}

Basic structure of condition

{
    ...,
    "operatorType": "numeric_operator",
    "operator": "numeric_lt|numeric_gr|numeric_eq|numeric_not_eq|numeric_not_eq|numeric_lt_eq|numeric_gr_eq|assigned|not_assigned",
    "value": "<number>"
}

Table of relation between operator and value field

Value of field operator	Is field value required?	Value of field value
numeric_lt is less than numeric_gt is greater than numeric_eq is equal to numeric_not_eq is not equal to numeric_lt_eq is less than or equal to numeric_gt_eq is greater than or equal to	Required	<number>
assigned not_assigned	Prohibited

"message_operator"

The operator allows searching by type of a message.

Example condition

Find contacts who opened a specific message.

{
    "conditionType": "opened",
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "value": "SGNLr"
}

Basic structure of condition

{
    ...,
    "operatorType": "message_operator",
    "operator": "autoresponder",
    "value": "{autoresponderId}",
    "clickTrackId": "all|{clickTrackId}"
}

Table of relation between operator and value field

Value of field operator	Value of field value	Additional information
newsletter	{newsletterId}	To find {newsletterId} use GET /v3/newsletters
autoresponder	{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
splittest	{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
automation	{workflowId}	To find {workflowId} use GET /v3/newsletters?query[type]=automation

Information about placeholders

Placeholder	Description
{autoresponderId}	To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	To find {newsletterId} use GET /v3/newsletters
{splittestId}	To find {splittestId} use GET /v3/newsletters?query[type]=splittest
{automationId}	To find {automationId} use GET /v3/newsletters?query[type]=automation
{clickTrackId}	To find {clickTrackId} fetch message details. i.e. GET /v3/newsletter/{newsletterId} or use GET /v3/click-tracks

Example conditions

Find contacts who clicked any link in a specific newsletter.

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "scope": "zlrzy",
    "clickTrackId": "all"
}

Find contacts who were sent a specific splittest.

{
    "conditionType": "sent",
    "operatorType": "message_operator",
    "operator": "splittest",
    "value": "zSp9V"
}

"exists"

The operator allows verifying whether or not the property you are looking for exists.

Example condition

{
    "conditionType": "tag",
    "value": "BB",
    "operatorType": "exists",
    "operator": "exists"
}

Basic structure of condition

{
    ...,
    "operatorType": "exists",
    "operator": "exists| not_exists",
    "value": "{tagId}"
}

Value of field operator	Is field value required?	Value of field value	Additional information
exists not_exists	For tags required. For scoring prohibited.	{tagId}	To find {tagId} use GET /v3/tags

"not_exists"

Find contacts who dont have a score.

{
    "conditionType": "score",
    "operatorType": "not_exists"
}

"complex_message_operator"

Example condition

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "autoresponder",
    "dateOperator": "never"
}

Basic structure of condition

{
    ...,
    "operatorType": "complex_message_operator",
    "operator": "all|autoresponder|newsletter|splittest|automation",
    "scope": "{autoresponderId}|{newsletterId}|{splittestId}|{automationId}",
    "dateOperator": "date_from|never|today|yesterday|last_7_days|last_30_days|this_week|this_month",
    "value": "{utcDateFormat}",
    "clickTrackId": "all|{clickTrackId}"
}

Required fields:

• operator
• scope
• dateOperator
• value - required only if dateOperator is date_from, please see table below
• clickTrackId - required only if scope is not all

Value of field dateOperator	Is field value required?	Value of field value
date_from	Required	"{utcDateFormat}"
never, today, yesterday, last_7_days, last_30_days, this_week, this_month, last_month	Prohibited

Fields description

Field	Value	Description
{utcDateFormat}	UTC date format RFC3339, e.g. "2018-04-10".	Field "customDate" is required only for "subscriptionDate": "custom".
{autoresponderId}	<hash>	Autoresponder identifier. To find {autoresponderId} use GET /v3/autoresponders
{newsletterId}	<hash>	Newsletter identifier. To find {newsletterId} use GET /v3/newsletters
{splittestId}	<hash>	Splittest identifier. To find {splittestId} use GET /v3/newsletters?query[type]=splittests
{automationId}	<hash>	To find {automationId} use GET /v3/newsletters?query[type]=automation
{clickTrackId}	<hash>	To find {clickTrackId} fetch message details. i.e. GET /v3/newsletter/{newsletterId} or use GET /v3/click-tracks

Example conditions

Find contacts who haven't opened any newsletters for the last 7 days.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "dateOperator": "last_7_days",
    "scope": "all"
}

Find contacts who haven't opened a specific newsletter today.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "dateOperator": "today",
    "scope": "z4Zje"
}

Find contacts who haven't opened a specific newsletter today.

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "dateOperator": "today",
    "scope": "z4Zje"
}

Find contacts who haven't clicked a specific link in a specific splittest in the last 30 days .

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "splittest",
    "dateOperator": "last_30_days",
    "scope": "zSp9V",
    "clickTrackId": "PPxiOW"
}

"equal_operator"

Example condition

Find contacts who have purchased products of any category from 2018-04-02.

{
    "conditionType": "ecommerce_product_purchased",
    "shopScope": "all",
    "categoryScope": "all",
    "operatorType": "equal_operator",
    "operator": "is",
    "productScope": "all",
    "dateOperator": "date_from",
    "value": "2018-04-02"
}

Basic structure of condition

{
    ...,
    "operatorType": "equal_operator",
    "operator": "is|is_not",
    "value": "<string>",5
    ...
}

Appendix B - list of currencies

More information can be found at ISO 4217.

Currency	ISO 4217	Currency	ISO 4217	Currency	ISO 4217
ADB Unit of Account	XUA	Guinean Franc	GNF	Pula	BWP
Afghani	AFN	Guyana Dollar	GYD	Qatari Rial	QAR
Algerian Dinar	DZD	Hong Kong Dollar	HKD	Quetzal	GTQ
Argentine Peso	ARS	Hryvnia	UAH	Rand	ZAR
Armenian Dram	AMD	Iceland Krona	ISK	Rial Omani	OMR
Aruban Florin	AWG	Indian Rupee	INR	Riel	KHR
Australian Dollar	AUD	Iranian Rial	IRR	Romanian Leu	RON
Azerbaijan Manat	AZN	Iraqi Dinar	IQD	Rufiyaa	MVR
Bahamian Dollar	BSD	Jamaican Dollar	JMD	Rupiah	IDR
Bahraini Dinar	BHD	Jordanian Dinar	JOD	Russian Ruble	RUB
Baht	THB	Kenyan Shilling	KES	Rwanda Franc	RWF
Balboa	PAB	Kina	PGK	Saint Helena Pound	SHP
Barbados Dollar	BBD	Kuna	HRK	Saudi Riyal	SAR
Belarusian Ruble	BYN	Kuwaiti Dinar	KWD	SDR (Special Drawing Right)	XDR
Belize Dollar	BZD	Kwanza	AOA	Serbian Dinar	RSD
Bermudian Dollar	BMD	Kyat	MMK	Seychelles Rupee	SCR
Bolívar	VEF	Lao Kip	LAK	Silver	XAG
Boliviano	BOB	Lari	GEL	Singapore Dollar	SGD
Brazilian Real	BRL	Lebanese Pound	LBP	Sol	PEN
Brunei Dollar	BND	Lek	ALL	Solomon Islands Dollar	SBD
Bulgarian Lev	BGN	Lempira	HNL	Som	KGS
Burundi Franc	BIF	Leone	SLL	Somali Shilling	SOS
Cabo Verde Escudo	CVE	Liberian Dollar	LRD	Somoni	TJS
Canadian Dollar	CAD	Libyan Dinar	LYD	South Sudanese Pound	SSP
Cayman Islands Dollar	KYD	Lilangeni	SZL	Sri Lanka Rupee	LKR
CFA Franc BCEAO	XOF	Loti	LSL	Sucre	XSU
CFA Franc BEAC	XAF	Malagasy Ariary	MGA	Sudanese Pound	SDG
CFP Franc	XPF	Malawi Kwacha	MWK	Surinam Dollar	SRD
Chilean Peso	CLP	Malaysian Ringgit	MYR	Swedish Krona	SEK
Colombian Peso	COP	Mauritius Rupee	MUR	Swiss Franc	CHF
Comorian Franc	KMF	Mexican Peso	MXN	Syrian Pound	SYP
Congolese Franc	CDF	Mexican Unidad de Inversion (UDI)	MXV	Taka	BDT
Convertible Mark	BAM	Moldovan Leu	MDL	Tala	WST
Cordoba Oro	NIO	Moroccan Dirham	MAD	Tanzanian Shilling	TZS
Costa Rican Colon	CRC	Mozambique Metical	MZN	Tenge	KZT
Cuban Peso	CUP	Mvdol	BOV	Trinidad and Tobago Dollar	TTD
Czech Koruna	CZK	Naira	NGN	Tugrik	MNT
Dalasi	GMD	Nakfa	ERN	Tunisian Dinar	TND
Danish Krone	DKK	Namibia Dollar	NAD	Turkish Lira	TRY
Denar	MKD	Nepalese Rupee	NPR	Turkmenistan New Manat	TMT
Djibouti Franc	DJF	Netherlands Antillean Guilder	ANG	UAE Dirham	AED
Dobra	STN	New Israeli Sheqel	ILS	Uganda Shilling	UGX
Dominican Peso	DOP	New Taiwan Dollar	TWD	Unidad de Fomento	CLF
Dong	VND	New Zealand Dollar	NZD	Unidad de Valor Real	COU
East Caribbean Dollar	XCD	Ngultrum	BTN	Uruguay Peso en Unidades Indexadas (URUIURUI)	UYI
Egyptian Pound	EGP	North Korean Won	KPW	US Dollar	USD
El Salvador Colon	SVC	Norwegian Krone	NOK	Uzbekistan Sum	UZS
Ethiopian Birr	ETB	Ouguiya	MRU	Vatu	VUV
Euro	EUR	Pa’anga	TOP	WIR Euro	CHE
Falkland Islands Pound	FKP	Pakistan Rupee	PKR	WIR Franc	CHW
Fiji Dollar	FJD	Palladium	XPD	Won	KRW
Forint	HUF	Pataca	MOP	Yemeni Rial	YER
Ghana Cedi	GHS	Peso Convertible	CUC	Yen	JPY
Gibraltar Pound	GIP	Peso Uruguayo	UYU	Yuan Renminbi	CNY
Gold	XAU	Philippine Piso	PHP	Zambian Kwacha	ZMW
Gourde	HTG	Platinum	XPT	Zimbabwe Dollar	ZWL
Guarani	PYG	Pound Sterling	GBP	Zloty	PLN

Appendix C - API requests query parameters

There are optional parameters to control which data appears in the response.

Field name	Field type	Field description
query	hash	Used to search only resources that meet the criteria. You can specify multiple parameters. Then, the AND logic is applied. Available search parameters: name=*, createdOn[from]=Y-m-d, createdOn[to]=Y-m-d, i.e. ?query[name]=my+custom+filer&query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11
fields	string	List of fields that should be returned. Id is always returned. Fields should be separated by comma. Available field names depends on request: name, createdOn, href. i.e.: ?fields=name,createdOn
sort	hash	Enable sorting using specified field (set as a key) and order (set as a value). You can specify multiple fields to sort by. Available keys name=asc|desc and createdOn=asc|desc. i.e: ?sort[name]=desc&createdOn=asc
page	integer	Specify which page of results should return.
perPage	integer	Specify how many results per page should be returned. The maximum allowed number of results is 1000. Up to 8 conditions are allowed.

Examples of using query parameters

• GET /v3/search-contacts/?query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11&perPage=100&page=1&sort[name]=desc
• GET /v3/search-contacts/?query[name]=my+custom+filer&sort[name]=desc
• GET /v3/search-contacts/?query[createdOn][from]=2018-04-01&perPage=100&page=1&sort[name]=desc
• GET /v3/search-contacts/?query[name]=my+custom+filer&query[createdOn][from]=2018-04-01&query[createdOn][to]=2018-04-11&fields=name,createdOn&perPage=100&page=1&sort[name]=desc
• GET /v3/search-contacts/?fields=name,createdOn&perPage=100&page=1
• GET /v3/search-contacts/b3Eta/contacts/?fields=name,email