Segments (search contacts) reference manual (beta)

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
  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.
  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
  10. Full list of operator types
  11. Full list of currencies
  12. API requests query parameters

Short description of resources.

List of available resources

/v3/search-contacts

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}.

Available HTTP methods (endpoints): GET POST

/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|forward|survey|sales|copy|leads|webinar",
    "webformType": "all|webforms|webformsv2|popups",
    "value": "all|{webformsId}|{webformsv2Id}|{popupsUuid}|{importId}|{landingPageId}|{webinarId}"
}

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
forward Sign-up from email forward
survey Sing-up via survey
copy Copied from other list
leads Added via GetSubscribers.com
webinar Added via webinar

Subscription method "method" = "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"
}

Subscription method "method" = "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

Subscription method "method" = "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

Subscription method "method" = "api"

Find contact subscribed via API.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "api"
}

Subscription method "method" = "email"

Find contacts who signed up through list email address.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "email"
}

Subscription method "method" = "panel"

Find contacts added manually.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "panel"
}

Subscription method "method" = "mobile"

Find contacts who signed up via mobile app.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "mobile"
}

Subscription method "method" = "forward"

Find contacts who signed up from email forward.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "forward"
}

Subscription method "method" = "survey"

Find contacts who subscribed via survey.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "survey"
}

Subscription method "method" = "sales"

Find contacts who subscribed through sales.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "sales"
}

Subscription method "method" = "copy"

Find contacts copied from other list.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "copy"
}

Subscription method "method" = "leads"

To find contact subscribed through leads.

Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "leads"
}

Subscription method "method" = "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

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.

Contact actions: 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.

Contact actions: 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}|{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>
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_to|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.

Contact actions: 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.

Contact actions: 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"
}

Contact actions: 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"
}

Contact actions: 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"
}

Contact actions: 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

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"
}

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|last_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
}

Contact actions: 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"
}

Contact actions: 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.

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",
    "operator": "not_exists"
}

Engagement Score

Searching for contacts by engagement score.

Example condition

Find contacts whose engagement score is lower than 5.

{
    "conditionType": "engagement_score",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt",
    "value": "5"
}
Basic structure of condition
{
    "conditionType": "engagement_score",
    "operatorType": "numeric_operator",
    "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
operatorType Allowed operators Allowed values
numeric_operator numeric_lt, numeric_gt, numeric_eq, numeric_not_eq, numeric_lt_eq, numeric_gt_eq <integer>

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

Example conditions

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

{
    "conditionType": "engagement_score",
    "operatorType": "numeric_operator",
    "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.

"conditionType" = "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"
    }
}

"conditionType" = "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"
    }
}

"conditionType" = "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"
}

"conditionType" = "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"
}

"conditionType" = "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.

"conditionType" = "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"
}
Basic structure of condition
{
    "conditionType": "sms_sent",
    "smsId": "{smsId}"
}
Value Description
{smsId} Sms identifier can be fetched from GET /v3/sms

"conditionType" = "sms_delivered"

Find contacts who received a specific SMS.

Example condition

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

{
    "conditionType": "sms_delivered",
    "smsId": "ABc"
}
Basic structure of condition
{
    "conditionType": "sms_delivered",
    "smsId": "{smsId}"
}
Value Description
{smsId} SMS identifier can be fetched from GET /v3/sms

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

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-01T00:00:00+0000

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

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"
}

Find contacts for which the custom event with identifier BB occurred between 2000-01-01T00:00:00+0000 and 2000-01-01T12:00:00+0000

{
    "conditionType": "custom_event",
    "customEventId": "BB",
    "occurrence": "occurred",
    "dateOperator": "custom",
    "date": "2000-01-01T00:00:00+0000/2000-01-01T12:00:00+0000"
}
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 formatRFC3339. 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"		  
{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

"operatorType": "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"
}

"operatorType": "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"
}

"operatorType": "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"
}

"operatorType": "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  

"operatorType": "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"
}

"operatorType": "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

"operatorType": "not_exists"

Find contacts who dont have a score.

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

"operatorType": "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"
}

"operatorType": "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