Selecting and retrieving contacts is simple yet powerful. You don't have to create complex conditions from scratch every time you want to use the advanced search criteria. Instead, you can use saved custom filters.

There are two ways to build a custom filter: - creating a JSON payload using the filter syntax, - creating a filter in the panel and retrieving the search criteria or contact list.

The second method is a good starting point for working with filters.

For information on how to start using the API and the API prerequisites go to the case study "Adding contacts" .

Using custom filters from web panel

The easiest way to search for contacts is to create and save a custom filter in the web panel. Then, you can retrieve it using the API. You can use a predefined filter to retrieve a contact list or retrieve the filter's content as a template for further editing.

  1. Log into the panel and create a custom filter as described in "Managing contacts / How do I create a custom filter?" Enter a descriptive name for your filter.

  2. Retrieve the saved filter and get its identifier. Make the request GET /search-contacts without parameters, to get a list of the saved custom filters.

Example response:

[
    {
        "searchContactId": "n3FLc",
        "name": "My_test_customers_list",
        "createdOn": "2018-04-06T13:05:15+0000",
        "href": "https://api.getresponse.com/v3/search-contacts/n3FLc"
    },
    {
        "searchContactId": "n3FLa",
        "name": "My_other_test_customers_list",
        "createdOn": "2018-04-06T13:05:15+0000",
        "href": "https://api.getresponse.com/v3/search-contacts/n3FLa"
    }    
]

You will use the value of searchContactId to retrieve the contact lists. This is the custom filter identifier.

To find a specific saved custom filter, use the query: GET /search-contacts/?query[name]=mytestcustomers_list.

With searchContactId make the following request GET /search-contacts/{searchContactId}/contacts to retrieve the list of contacts matching the specified conditions.

Example response:

[
       {
           "contactId": "V",
           "href": "https://api.getresponse.com/v3/contacts/V",
           "name": "John Smith",
           "email": "jsmith@example.com",
           "origin": "iphone",
           "dayOfCycle": "175",
           "createdOn": "2018-01-01T10:00:00+0000",
           "campaign": {
               "campaignId": "V",
               "name": "TestCampaign",
               "href": "https://api.getresponse.com/v3/campaigns/V"
           },
           "score": "10",
           "reason": "unsubscribe"
       },
       {
           "contactId": "B",
           "href": "https://api.getresponse.com/v3/contacts/B",
           "name": "John Harit",
           "email": "jsmith@example.com",
           "origin": "iphone",
           "dayOfCycle": "175",
           "createdOn": "2018-01-01T10:00:00+0000",
           "campaign": {
               "campaignId": "V",
               "name": "TestCampaign",
               "href": "https://api.getresponse.com/v3/campaigns/V"
           },
           "score": "10",
           "reason": "unsubscribe"
       }
]

Please remember that the results are paginated. By default, you will get the first 100 results. To get more results, you have to request data sequentially using GET /search-contacts/{searchContactId}/contacts?page=2&perPage=100, where page is the page number and perPage is the maximum number of results per page. The default perPage value is 100, maximum: 1000.

Structure of custom filter

If you want to know the criteria used to create a custom filter, or to use it as an example to prepare your custom filter, retrieve the custom filter by its searchContactId: GET /search-contacts/{searchContactId}. Example response:

{
    "searchContactId": "p",
    "href": "http://api.getresponse.new/v3/search-contacts/p",
    "name": "test_conditions",
    "createdOn": "2018-01-01T10:00:00+0000",
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "V"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "email",
                    "operatorType": "string_operator",
                    "operator": "is",
                    "value": "someEmail"
                },
                {
                    "conditionType": "name",
                    "operatorType": "string_operator",
                    "operator": "not_contains",
                    "value": "someName"
                },
                {
                    "conditionType": "geo",
                    "operatorType": "string_operator",
                    "operator": "is_not",
                    "value": "dsaDa",
                    "scope": "country"
                },
                {
                    "conditionType": "custom",
                    "operatorType": "string_operator",
                    "operator": "assigned",
                    "scope": "T"
                },
                {
                    "conditionType": "subscription_date",
                    "operatorType": "date_operator",
                    "operator": "date_to",
                    "value": "2015-01-01"
                },
                {
                    "conditionType": "subscription_method",
                    "method": "webform",
                    "value": "all"
                },
                {
                    "conditionType": "subscription_method",
                    "method": "import",
                    "value": "all"
                },
                {
                    "conditionType": "last_open_date",
                    "operatorType": "date_operator",
                    "operator": "specific_date",
                    "value": "last_30_days"
                }
            ]
        },
        {
            "campaignIdsList": [
                "V"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "last_newsletter_date",
                    "operatorType": "date_operator",
                    "operator": "custom",
                    "value": "2015-01-01/2015-01-24"
                },
                {
                    "conditionType": "sent",
                    "operatorType": "message_operator",
                    "operator": "autoresponder",
                    "value": "K"
                },
                {
                    "conditionType": "not_sent",
                    "operatorType": "message_operator",
                    "operator": "splittest",
                    "value": "J"
                },
                {
                    "conditionType": "phase",
                    "operatorType": "numeric_operator",
                    "operator": "numeric_lt",
                    "value": "15"
                }
            ]
        }
    ]
}

For sectionLogicOperator, the allowed operators are: - or for results where any of the sections matches the conditions, - and for results where all sections have to match the conditions.

Section is the equivalent of Filter group in the panel. Within every section you can build a condition for this group. You can use or or and operator as logicOperator. This operator works within the appropriate section (filter group).

In documentation you will find a complete list of fields and operators.

Adding custom filters

You can create a custom filter by posting POST /search-contacts/.

Example payload:

{
    "name": "test_conditions",
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "V"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "email",
                    "operatorType": "string_operator",
                    "operator": "is",
                    "value": "someEmail"
                },
                {
                    "conditionType": "name",
                    "operatorType": "string_operator",
                    "operator": "not_contains",
                    "value": "someName"
                },
                {
                    "conditionType": "geo",
                    "operatorType": "string_operator",
                    "operator": "is_not",
                    "value": "dsaDa",
                    "scope": "country"
                }
            ]
        }
    ]
}

The response will contain the custom filter created:

{
    "searchContactId": "p",
    "href": "http://api.getresponse.new/v3/search-contacts/p",
    "name": "test_conditions",
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "V"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "email",
                    "operatorType": "string_operator",
                    "operator": "is",
                    "value": "someEmail"
                },
                {
                    "conditionType": "name",
                    "operatorType": "string_operator",
                    "operator": "not_contains",
                    "value": "someName"
                },
                {
                    "conditionType": "geo",
                    "operatorType": "string_operator",
                    "operator": "is_not",
                    "value": "dsaDa",
                    "scope": "country"
                }
            ]
        }
    ]
}

Executing search without saving custom filter

You can get a contact list by posting a contact filter payload using POST /search-contacts/contacts. You will not create a new saved filter - the API will return just the contact list.

Example payload:

{
    "subscribersType": [
        "subscribed"
    ],
    "sectionLogicOperator": "or",
    "section": [
        {
            "campaignIdsList": [
                "V"
            ],
            "logicOperator": "or",
            "subscriberCycle": [
                "receiving_autoresponder",
                "not_receiving_autoresponder"
            ],
            "subscriptionDate": "all_time",
            "conditions": [
                {
                    "conditionType": "email",
                    "operatorType": "string_operator",
                    "operator": "is",
                    "value": "someEmail"
                },
                {
                    "conditionType": "name",
                    "operatorType": "string_operator",
                    "operator": "not_contains",
                    "value": "someName"
                },
                {
                    "conditionType": "geo",
                    "operatorType": "string_operator",
                    "operator": "is_not",
                    "value": "dsaDa",
                    "scope": "country"
                }
            ]
        }
    ]
}

Other operations

In documentation you will find a complete list of operations, including delete and assigning custom fields to contacts that match the filter conditions.