GR API Docs

Segments (search contacts) ​

TIP

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

Creating targeted search results is an indispensable part of any successful marketing strategy. Using advanced search criteria can help you narrow down your search results so you can reach just the right audience with your emails.

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

There are two ways to build a segment:

  • Creating a JSON payload using the filter syntax
  • Creating a filter in the panel and retrieving the search criteria or contact list.

Retrieving an existing segment 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 segments from web panel ​

The easiest way to search for contacts is to create and save a segment in your account. Then, you can retrieve it using the API. You can use a predefined filter to retrieve a contact list or retrieve the content of the filter as a template for further editing.

Log into your account and create a segment as described in “Managing contacts / How do I create a custom filter?” Enter a descriptive name for your filter.

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

Example response:

json
[
    {
        "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 segment (search contact) identifier.

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

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

Example response:

json
[
    {
        "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",
        "deletedOn": "2024-02-12T11:00:00+0000"
    },
    {
        "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",
        "deletedOn": "2024-02-12T11:00:00+0000"
    }
]

Please remember that the results are paginated. By default, you’ll see 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.

The structure of segment ​

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

Example response:

json
{
    "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 an or or and operator as logicOperator. This operator works within the appropriate section (filter group).

In our reference manual you will find a complete list of fields and operators.

Adding segments ​

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

Example payload:

json
{
    "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 segment created:

json
{
    "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 a segment ​

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

Example payload:

json
{
    "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 ​

See our reference manual for a complete list of operations, including deleting and assigning custom fields to contacts that match the filter conditions.