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 retrievig 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
    }
]

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 REST API /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 tructure 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 field 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 contact by predefined 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 REST API /v3/custom-fields

Example condition

Find all contacts with the custom field "gender" set to "Female".

{
    "conditionType": "custom",
    "scope": "pa3N6",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Female"
}
Basic structure of custom condition
{
    "conditionType": "custom",
    "scope": "{scope}",
    "operatorType": "string_operator|string_operator_list",
    "operator": "is|is_not|contains|not_contains|starts|ends|not_starts|not_ends|assigned|not_assigned",
    "value": "<string>"
}
{
    "conditionType": "custom",
    "scope": "{scope}",
    "operatorType": "date_operator",
    "operator": "date_to|date_from|specific_date|assigned|not_assigned|custom",
    "value": "{utcDateFormat}|today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month|last_2_month|{rangeUTCDateFormat}"
}

where the field "value": "<string>" is prohibited for operators assigned and not_assigned.

Table of allowed field values.

operatorType Allowed operators Allowed values
string_operator,
string_operator_list
is, is_not, contains, not_contains, starts, ends, not_starts, not_ends <string>
  assigned, not_assigned field "value" prohibited
date_operator date_to, date_from {utcDateFormat}
  custom {rangeUTCDateFormat}
  specific_date today. yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month
  assigned, not_assigned field "value" prohibited
Value Description
{scope} Custom field identifier can be fetched from REST API /v3/custom-fields
{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"

Some predefined custom fields can be collected through REST API /v3/custom-fields.

See the table below for the available operator types for predefined custom fields.

Custom field name Operator type Available operators Comment
age, country, gender string_operator_list is,
is_not,
contains,
not_contains,
starts,
ends,
not_starts,
not_ends,
assigned,
not_assigned
available values can be collected from /v3/custom-fields/?query[name]={customFieldName}
birthday date_operator date_to,
date_from,
specific_date,
custom,
assigned,
not_assigned
for "operator": "custom" field "value": "{rangeUTCDateFormat}"
for "operator": "assigned|not_assigned" field "value" is prohibited
city, comment, company, fax, home_phone, http_referer, mobile_phone, phone, postal_code, ref, state, street, url, work_phone string_operator is,
is_not,
contains,
not_contains,
starts,
ends,
not_starts,
not_ends,
assigned,
not_assigned
 

You can find detailed information about a given "operatorType" here.

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 gender condition

Find all contacts with the custom field "gender" set to "Male".

{
    "conditionType": "custom",
    "scope": "pa3N6",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Male"
}
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 conditionN
{
    "conditionType": "subscription_method",
    "method": "webform|import|landing_page|api|email|panel|mobile|forward|survey|sales|copy|leads",
    "webformType": "all|webforms|webformsv2",
    "value": "all|{webformsId}|{webformsv2Id}"
}

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

method Description
webform Sign-up via web 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

Subscription method "method" = "webform"

Search for contacts who subscribed via a web form

Example condition

Find all contacts who subscribed by any webform.

{
    "conditionType": "subscription_method",
    "method": "webform",
    "webformType": "all"
}
Basic structure of condition
{
    "conditionType": "subscription_method",
    "method": "webform",
    "webformType": "all|webforms|webformsv2",
    "value": "{webformId}|{webformv2Id}"
}

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

Value Description
{webformId} Webform identifier can be fetched from REST API /v3/webforms
{webformv2Id}  
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 REST API /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 REST API /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"
}

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 autoresponder date "last_autoresponder_date" "date_operator" To find contacts based on the date an autoresponder email was last sent to them.
Last newsletter date "last_newsletter_date" "date_operator" To find contacts based on the date a newsletter 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.
CRM "crm"    

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 opended

Find contacts who didn't open a specific email.

Example condition
{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "autoresponder",
    "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|this_week|this_month",
    "value": "{utcDateFormat}"
}

For the specific "scope", set {autoresponderId}|{newsltterId}|{splittest-id}|{automationId} otherwse the "scope" field is prohibited.

Field "value" required only for "dateOperator": "date_from", 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}
Value Description
{autoresponderId} to find {autoresponderId} go to REST API /v3/autoresponders
{newsletterId} to find {newsletterId} go to REST API /v3/newsletters
{splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /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 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"
}

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 autoresponder date

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

Example condition

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

{
    "conditionType": "last_autoresponder_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "last_7_days"
}
Basic structure of condition
{
    "conditionType": "last_autoresponder_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.

Contact actions: Last newsletter date

Find contacts based on the date they were last sent a newsletter.

Example condition

Find contacts who've been sent a newsletter this month.

{
    "conditionType": "last_newsletter_date",
    "operatorType": "date_operator",
    "operator": "specific_date",
    "value": "this_month"
}
Basic structure of condition
{
    "conditionType": "last_newsletter_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_newsletter_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-05-06"
}

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

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

Find contacts who were sent a newsletter in the last seven days.

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

Find contacts who were sent a newsletter between 2018-05-01 and 2018-05-31.

{
    "conditionType": "last_newsletter_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 REST API /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|{clickTtrackId}"
}
Value Description
{autoresponderId} to find {autoresponderId} go to REST API /v3/autoresponders
{newsletterId} to find {newsletterId} go to REST API /v3/newsletters
{splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /v3/newsletters?query[type]=automation
{clickTtrackId} to find {clickTrackId} fetch message details. i.e. REST API /v3/newsletter/{newsletterId}

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": "today|yesterday|last_7_days|last_30_days|this_week|last_week|this_month|last_month",
    "scope": "{newsletterId}|{autoresponderId}|{splittestId}|{automationId}",
    "clickTrackId": "all|{clickTrackId>"
}

For the specific "scope", set {autoresponderId}|{newsltterId}|{splittest-id}|{automationId} otherwise the "scope" field is prohibited.

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

Value Description
{newsletterId} Newsletter identifier can be fetched from REST API /v3/newsletters
{autoresponderId} Autoresponder identifier can be fetched from REST API /v3/autoresponders
{splittestId} Splittest identifier can be fetched from REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /v3/newsletters?query[type]=automation
{clickTrackId} to find {clickTrackId} fetch message details. i.e. REST API /v3/newsletter/{newsletterId}
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 30 days.

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

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} go to REST API /v3/autoresponders
{newsletterId} to find {newsletterId} go to REST API /v3/newsletters
{splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /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} go to REST API /v3/autoresponders
{newsletterId} to find {newsletterId} go to REST API /v3/newsletters
{splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /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"
}

Contact actions: CRM

Example condition
{
    "conditionType": "crm",
    "pipelineScope": "PSVq",
    "stageScope": "ZAHB"
}
Basic structure of condition
{
    "conditionType": "crm",
    "pipelineScope": "{pipelineId}",
    "stageScope": "all|{stageId}"
}
Value Description
{pipelineId} Pipeline identifier can be fetched from REST API /v3/pipelines/
{stageId} Stage identifier can be fetched from REST API /v3/pipelines/{pipelineId}/stages/

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 REST API /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.

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

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>
Value Description
{shopId} Shop identifier can be fetched from REST API /v3/shops
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": "5"
}

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

"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": "7.00",
    "currency": "USD"
}
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}"
}

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>
Value Description
{shopId} Shop identifier can be fetched from REST API /v3/shops
{currencyCode} Currency codes compatible with ISO 4217. List of currency codes listed here
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"
}

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

"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|this_week|last_week|this_month|last_month|last_2_month|custom",
    "value": "{utcDateFromat}|{rangeUTCDateFormat}"
}

Table of allowed fields and their values.

Field Allowed operators Allowed values
dateOperator date_to, date_from {utcDateFormat}
  all_time,today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, last_2_month Field "value" is prohibited.
  custom {rangeUTCDateFormat}
Value Description
{shopId} Shop identifier can be fetched from REST API /v3/shops
{categoryId} Category identifier can be fetched from REST API /v3/shops/{shopId}/categories
{productId} Product identifier can be fetched from REST API /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".
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_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 REST API /v3/shops
{vendorName} One of values from vendor field added to products REST API /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"
}

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

The response structure is compatible with REST API /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)segment 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
    }
]

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 filed identifier. To find {customFieldId} go to REST API /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"

The operator allows searching 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>"
}

Table of allowed operators.

operator field value value field value field value comments
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 fields
operator field value 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" is used only with custom field REST API /v3/custom-fields.

Example condition

Find all contacts with the custom field "gender" set to "Female".

{
    "conditionType": "custom",
    "scope": "pa3N6",
    "operatorType": "string_operator_list",
    "operator": "is",
    "value": "Female"
}
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>"
}

Table of allowed operators.

operator field value value field value field value comments
is,
is_not,
contains,
not_contains,
starts,
ends,
not_starts,
not_ends
required string  
assigned,
not_assigned
prohibited   available only for custom fields
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 a newsletter till 2018-05-06.

{
    "conditionType": "last_newsletter_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "value": "2018-05-06"
}
Basic structure of condition
{
   ...,
    "operatorType": "numeric_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}`"
}
operator field value value field value field value comments
date_to,
date_from
required {utcDateFormat} UTC date format RFC3339 e.g.
specific_date required one of following values:
today,
yesterday,
last_7_days,
last_30_days,
this_week,
last_week,
this_month,
last_month,
last_2_month,
{rangeUTCDateFormat}
{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"
assigned,
not_assigned
prohibited   available only for custom fields
Example conditions

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

{
    "conditionType": "last_autoresponder_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 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": "<integer>"
}
operator field value value field value field value comments
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 integer  
assigned,
not_assigned
required    

"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": "{newsletterId}|{autoresponderId}|{splittestId}|{workflowId}"
}
operator field value value field value field value comments
newsletter required {newsletterId} to find {newsletterId} go to REST API /v3/newsletters
autoresponder required {autoresponderId} to find {autoresponderId} go to REST API /v3/autoresponders
splittest required {splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
automation required {workflowId} to find {workflowId} go to REST API /v3/newsletters?query[type]=automation
Value Description
{autoresponderId} to find {autoresponderId} go to REST API /v3/autoresponders
{newsletterId} to find {newsletterId} go to REST API /v3/newsletters
{splittestId} to find {splittestId} go to REST API /v3/newsletters?query[type]=splittest
{automationId} to find {automationId} go to REST API /v3/newsletters?query[type]=automation
{clickTtrackId} to find {clickTrackId} fetch message details. i.e. REST API /v3/newsletter/{newsletterId}
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}"
}
operator field value value field value field value comments
exists,
not_exists
depends on the subject.
For tags required, for scoring prohibited.
{tagId} to find Tags go to REST API /v3/tags

"operatorType": "not_exists"

Find contacts who dont have a score.

{
    "conditionType": "score",
    "operator": "not_exists"
}
operator field value value field value field value comments
doesn't exists   prohibited  

"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}"
}
operator field value value field value field value comments
all,
autoresponder,
newsletter,
splittest,
automation
prohibited   required fields "dateOperator": "today | yesterday | last_7_days | last_30_days | this_week | last_week | this_month | last_month",
"scope": "{newsletterId} | {autoresponderId} | {splittestId} | {automationId}",
"clickTrackId": "all | {clickTrackId}" // required only if specific scope is definied
For specific "scope" set {autoresponderId} | {newsltterId} | {splittestId} | {automationId} in other field "scope" is prohibited.
dateOperator value field value 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} go to REST API /v3/autoresponders
{newsletterId} <hash> Newsletter identifier. To find {newsletterId} go to REST API /v3/newsletters
{splittestId} <hash> Splittest identifier. To find {splittestId} go to REST API /v3/newsletters?query[type]=splittests
{automationId} <hash> To find {automationId} go to REST API /v3/newsletters?query[type]=automation
{clickTtrackId} <hash> To find {clickTrackId} fetch message details. i.e. REST API /v3/newsletter/{newsletterId}
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
    ...
}
operator field value value field value field value comments
is,
is_not
required <string>  

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