Search Contacts
GET /search-contacts
Returns status code
200
Request url
/search-contacts?query[name]=testName&fields=name&sort[createdOn]=desc&page=4&perPage=30
Request params
Field name | Field type | Field description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
query | hash | Used to search only resources that meets criteria. You can specify multiple parameters, then it uses AND logic.
| ||||||||||||
fields | string | List of fields that should be returned. Id is always returned. Fields should be separated by comma | ||||||||||||
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.
| ||||||||||||
page | integer | Specify which page of results return. | ||||||||||||
perPage | integer | Specify how many results per page should be returned |
Example Response
[
{
"searchContactId": "V",
"name": "test_name",
"createdOn": "2014-09-29 12:25:55",
"href": "https://api.getresponse.com/v3/search-contacts/V"
},
{
"searchContactId": "Zc",
"name": "second_test_name",
"createdOn": "2014-02-09 02:21:11",
"href": "https://api.getresponse.com/v3/search-contacts/Zc"
}
]
GET /search-contacts/{searchContactId}
Returns status code
200
Example Response
{
"searchContactId": "p",
"href": "http://api.getresponse.new/v3/search-contacts/p",
"name": "test_conditions",
"createdOn": "2015-03-06 12:32:58",
"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"
}
]
}
]
}
POST /search-contacts/
Returns status code
201
Example Request Body
{
"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"
}
]
}
]
}
Example Response
{
"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"
}
]
}
]
}
Possible Errors
DELETE /search-contacts/{id}
Returns status code
204
POST /search-contacts/{searchContactsId}
Returns status code
201
Example Request Body
{
"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"
}
]
}
]
}
Example Response
{
"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"
}
]
}
]
}
GET /search-contacts/{searchContactId}/contacts
Returns status code
200
Example Response
[
{
"contactId": "V",
"href": "https://api.getresponse.com/v3/contacts/V",
"name": "John Smith",
"email": "jsmith@example.com",
"origin": "iphone",
"dayOfCycle": "175",
"createdOn": "2014-09-29 12:25:55",
"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": "2014-09-29 12:25:55",
"campaign": {
"campaignId": "V",
"name": "TestCampaign",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"score": "10",
"reason": "unsubscribe"
}
]
POST /search-contacts/{searchContactId}/custom-fields
The method allows adding and updating custom field values for all contacts that meet search criteria. This method does not remove or overwrite custom fields with values from request.
Returns status code
202
Example Request Body
{
"customFieldValues": [
{
"customFieldId": "n",
"value": [
"white"
]
}
]
}
Body params
Field name | Field type | Field description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
customFieldValues (required) | collection | Collection of customFieldValues that should be upserted to contact
|
Possible Errors
POST /search-contacts/contacts
This method allows to search contacts without saving the search. Request body contains a query, structured according to our reference and response is a collection of contacts meeting the criteria.
Returns status code
200
Request url
/search-contacts/contacts?sort[name]=asc&page=3&perPage=100
Request params
Field name | Field type | Field description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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.
| ||||||||||||
page | integer | Specify which page of results return. | ||||||||||||
perPage | integer | Specify how many results per page should be returned |
Example Request Body
{
"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"
}
]
}
]
}
Example Response
[
{
"contactId": "V",
"href": "https://api.getresponse.com/v3/contacts/V",
"name": "John Smith",
"email": "jsmith@example.com",
"note": "best contact ever",
"dayOfCycle": null,
"origin": "iphone",
"createdOn": "2014-09-29 12:25:55",
"changedOn": "2014-10-29 12:25:55",
"campaign": {
"campaignId": "V",
"name": "Test campaign",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"timeZone": "America/St_Johns",
"ipAddress": "127.0.0.1",
"activities": "https://api.getresponse.com/v3/contacts/V/activities",
"scoring": 10
},
{
"contactId": "p",
"href": "https://api.getresponse.com/v3/contacts/p",
"name": "Jane Smith",
"email": "janesmith@exampl.com",
"note": null,
"origin": "sale",
"createdOn": "2014-06-29 0:55:11",
"changedOn": null,
"campaign": {
"campaignId": "V",
"name": "Test campaign",
"href": "https://api.getresponse.com/v3/campaigns/V"
},
"timeZone": "America/Juneau",
"ipAddress": "127.0.0.1",
"activities": "https://api.getresponse.com/v3/contacts/p/activities",
"scoring": null
}
]