Search Contacts Reference Manual

Search contacts have the most complex response from our resources. This is because this is very powerfull tool that enables you to create and run very complicated and precise search querries. On this page we will explain how this search contacts works and how to use it to your advantage.

Basic JSON structure

If you fetch collection of search-contacts you will receive array of objects that looks like that:

{
    "searchContactId": "Tm9q",
    "name": "all",
    "createdOn": "2014-04-11 12:38:35",
    "href": "https://api.getresponse.com/v3/search-contacts/Tm9q"
}

This is a short representation of search-contact resource. If you want to know what conditions are used in that search-contact, you need to call for full representation:

GET /search-contacts/Tm9q

Example of full :

{
    "searchContactId": "8Z7y",
    "href": "https://api.getresponse.com/v3/search-contacts/8Z7y",
    "name": "try_one54fee6624bb18",
    "createdOn": "2015-03-10T12:41:07+0000",
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "Vp"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "last_newsletter_date",
                    "operatorType": "date_operator",
                    "operator": "date_from",
                    "conditionValue": "2015-03-03"
                },
                {
                    "conditionType": "last_open_date",
                    "operatorType": "date_operator",
                    "operator": "specific_date",
                    "conditionDateType": "last_month"
                },
                {
                    "conditionType": "last_click_date",
                    "operatorType": "date_operator",
                    "operator": "date_from",
                    "conditionValue": "2015-03-24"
                }
            ]
        }
    ]
}

General description of this structure is available on main documentation page. Here we try to focus more on section called “conditions”.

Conditions are an essence of search-contacts. In that section you put all your requirements that will be checked against your contacts. Below you will find all necessary information on how to create conditions.

Simple Condition Structure

All conditions that are "simple", share common JSON structure.

{
    "conditionType": "",
    "operatorType": "",
    "operator": "",
    "value": ""
}

JSON structure

  • conditionType - this tells us what you are looking for
    • name - name of a contact
    • email - email of a contact
    • subscription_date - date of subscription
    • subscription_method - origin of a subscription
    • last_autoresponder_date - last time when autoresponder was sent to contact
    • last_newsletter_date - last time when newsletter was sent to contact
    • last_open_date - last time when contact opened a message
    • last_click_date - last time when contact clicked a message
    • phase - autoresponder day of cycle of a contact
    • open - contact that opened certain message
    • sent - contact who received certain message
    • not_sent - contact who not received cetain message
  • operatorType - this indicates what type of comparison is possible for that conditionType
    • string_operator - string comparision
    • numeric_operator - this is numeric comparision
    • date_operator - this is date/time related comparision
    • message_operator - this is special type of message type comparision
  • operator - what exact comparator should be used. List of possible choices are listed below.
  • value - value that will be compared against.

operators

  1. exists
    • exists
    • not_exists
  2. string_operator
    • is
    • is_not
    • starts
    • ends
    • not_starts
    • not_ends
    • contains
    • not_contains
  3. numeric_operator
    • numeric_lt
    • numeric_gt
    • numeric_eq
    • numeric_not_eq
    • numeric_lt_eq
    • numeric_gt_eq
  4. date_operator
    • date_from (UTC format date)
    • date_to (UTC format date)
    • specific_date (string or ISO8601 format date interval)
  5. date_operator - specific_date constants
    • today
    • yesterday
    • this_week
    • last_week
    • last_7_days
    • last_30_days
    • this_month
    • last_month
    • last_2_months
    • [UTC format Date Interval (ISO8601) eg: 2007-03-01/2008-05-11]
  6. message_operator
    • newsletter
    • autoresponder
    • split

Semi-Complex Condition Structure

Those structures are similar to above ones. There is only one additional field called scope. This field contain usual an resourceId of some sort (depending on conditionType). There is also new type of operator called message_operator. Possible values are: newsletter, autoresponder, split. For "clicked" condition there is also field called link where clickTrackId is stored.

{
    "conditionType": "",
    "operatorType": "",
    "operator": "",
    "value": "",
    "scope": ""
}

geo

  • operatorType = string_operator
  • scope = one of the following: country, country_code, region, city, longitude, latitude

custom

  • operatorType = string_operator + assigned
  • scope = customFieldId

goal

  • operatorType = numeric_operator
  • scope = goalId

clicked

  • operatorType = message_operator
  • scope = messageId
  • clickTrackId = clickTrackId

tags

  • operatorType = exists
  • value = tagId
  • scope = tagId

Complex Condition Type

Those conditions are the most complex we offer. They have different structure and field name as those condition above. operatorType is always equal to complex_message_operator with have one additional element from which you can choose: "all".

not_clicked

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "newsletter|autoresponder|split|all",
    "scope": "all|newsletterId|autoresponderId",
    "link": "clickTrackId",
    "dateOperator": "custom",
    "value": "2007-03-01/2008-05-11"
}

dateOperator can be one of the following: never, today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_30_days, custom

not_opened

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter|autoresponder|split|all",
    "scope": "all|newsletterId|autoresponderId",
    "dateOperator": "custom",
    "value": "2007-03-01/2008-05-11"
}

webinar

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

Examples

Simple

name

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

email

{
    "conditionType": "email",
    "operatorType": "string_operator",
    "operator": "contains",
    "value": "@example.com"
}

subscription_date

{
    "conditionType": "subscription_date",
    "operatorType": "date",
    "operator": "date_to",
    "value": "2014-12-12"
}

subscription_method

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

Available method field values: import, landing_page, api, email, panel, mobile, forward, survey, sales, copy, leads, webform (requires webformType field set to one of: webforms, webformsv2, all)

last_autoresponder_date

{
    "conditionType": "last_autoresponder_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "conditionValue": "2015-03-05"
}

last_newsletter_date

{
    "conditionType": "last_newsletter_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "conditionValue": "2015-03-05"
}

last_open_date

{
    "conditionType": "last_open_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "conditionValue": "2015-03-05"
}

last_click_date

{
    "conditionType": "last_click_date",
    "operatorType": "date_operator",
    "operator": "date_to",
    "conditionValue": "2015-03-05"
}

scoring

{
    "conditionType": "score",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt",
    "conditionValue": "10"
}

tag

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

Semi-Complex

geo

{
    "conditionType": "geo",
    "operatorType": "string_operator",
    "operator": "contains",
    "value": "pol",
    "scope": "country"
}

scope can be one of the following: country, country_code, region, city, longitude, latitude

custom

{
    "conditionType": "custom",
    "operatorType": "string_operator",
    "operator": "ends",
    "value": "k",
    "scope": "ZOMK"
}

goal

{
    "conditionType": "goal",
    "operatorType": "numeric_operator",
    "operator": "numeric_lt",
    "value": "100",
    "scope": "nPZ"
}

opened

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

sent

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

not_sent

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

clicked

{
    "conditionType": "clicked",
    "operatorType": "message_operator",
    "operator": "newsletter",
    "clickTrackId": "QQWd0",
    "scope": "yoz9F"
}

Complex Conditions

not_clicked

{
    "conditionType": "not_clicked",
    "operatorType": "complex_message_operator",
    "operator": "autoresponder",
    "scope": "yoQnP",
    "clickTrackId": "QQjVw",
    "dateOperator": "custom",
    "value": "2015-02-28/2015-03-30"
}

dateOperator can be one of the following: never, today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_30_days, custom

not_opened

{
    "conditionType": "not_opened",
    "operatorType": "complex_message_operator",
    "operator": "newsletter",
    "scope": "ydllO",
    "dateOperator": "date_from",
    "value": "2015-03-10"
}

webinar

{
    "conditionType": "webinar",
    "webinarCondition": "participated",
    "scope": "tOPr5",
    "contactType": "all"
}

crm

{
    "conditionType": "crm",
    "pipelineScope": "pV6",
    "stageScope": "byS8"
}

stageScope can be a stage ID or all