Table of Contents:
Table of Contents minLevel 2
Note: Notice that in each API call you must provide the List ID that you are working on, otherwise the default List ID will be used. You can review the possible ways to provide List ID in this link.
Methods Summary
This API controller is for managing asynchronous contact searches.
...
Create instance - Create a new contact search using "POST api/contact_search" You need to set a title for this new search, and the filters used for contacts segmentation.
Check the instance status - Check the contact search status using "GET api/contact_search/<Contact search report ID>" When contact search is created, its always created in status "Pending" (1), in order to know when the contact search is ready, use this method and verify that the status is "Completed" (2).
Get the instance results - When status is Complete, get results using "GET api/contact_search/<Contact search report ID>/result" This will return an array of the contacts you searched for.
GET /api/contact_search/<Contact search report ID>
Description
This method fetches a contact search (without results) and it can also be used for checking the contact search status.
...
| Key | Description |
|---|---|
status | Contact search status, 1 = Pending, 2 = Completed |
status_desc | Contact search status description (Pending / Completed) |
GET /api/contact_search/<Contact search report ID>/result
Description
This method fetches the contact search results. This is the same report you see in the UI under the Contact Manager Search and/or Analytics -> Contact Activity Report (if you provided include_behavior=true), when you click on the "View Report" icon. This API command provides the same results as the export below, only in this case, it returns the entire result as a JSON response instead of CSV file.
...
| Code Block |
|---|
{
"metadata": {
"error": false,
"fields": {},
"total": 3
},
"payload": [
{
"email": "email1@gmail.com",
"address": "",
"country": "",
"first_name": "",
"last_name": "",
"gender": "",
"ip": "",
"language": "",
"phone": "",
"os": "",
"product_id": "0",
"id": "55a4d31c2547e5f8537b23c6",
"ocx_status": "Active",
"ocx_created_date": "1436865308",
"ocx_unsubscribe_date": "",
"ocx_import_id": ""
},
{
"email": "email2@hotmail.com",
"address": "",
"country": "",
"first_name": "",
"last_name": "",
"gender": "",
"ip": "",
"language": "",
"phone": "",
"os": "",
"product_id": "0",
"id": "55a4d3292547e52c7b7b23c7",
"ocx_status": "Unsubscribed",
"ocx_created_date": "1436865321",
"ocx_unsubscribe_date": "1438503584",
"ocx_import_id": ""
},
{
"email": "email3@yahoo.com",
"address": "",
"country": "",
"first_name": "",
"last_name": "",
"gender": "",
"ip": "",
"language": "",
"phone": "",
"os": "",
"product_id": "0",
"id": "55b9ec3b2547e5720f7b23c6",
"ocx_status": "Active",
"ocx_created_date": "1438247995",
"ocx_unsubscribe_date": "",
"ocx_import_id": ""
}
]
} |
GET /api/contact_search/<Contact search report ID>/export
Description
This method exports a contact search report already created.
GET /api/contact_search
Description
This method fetches a collection of contact searches (without the results).
...
Optional int
limit
Optional int
POST /api/contact_search
Description
This method creates a new contact search.
...
* empty : Is empty
* notempty : Is not empty
Request Example -
...
Create a Contact Search for All Members in a Given List
After you issue this request you'll be able to find that report under List → Contact Manager → Search.
| Code Block |
|---|
{ "title": "All Members: Email is not empty", "include_behavior": false, "filters": { "type": "Active", "criteria": [{ { "type": "idstring", "operator":"=", "operator": "notempty", "operand":[ "1111" "operand": [""], ], "case_sensitive": 0, "condition":"and", "fieldcondition": "ocx_contact_idand", } ], "userfield_typeid": "all123456" // This }, "combined_as_and":true } |
Request Example - For Multiple Contact IDs
| Code Block |
|---|
{ "title":"All Members: Contact ID (System field) equals \"1111\" OR Contact ID (System field) equals \"22222222\"", "include_behavior":false, "filters":{ "type":"Active"is the field id of the email field in that list. You can find that ID under List Settings -> Field Setup }], "criteria":[ { ""user_type": "idall", "operator":"=", }, "operandcombined_as_and":[ true } |
Request Example - For Single Contact Id
| Code Block |
|---|
{ "title":"All Members: Contact ID (System field) equals \"1111\"", "include_behavior":false, "filters":{ ]"type":"Active", "criteria":[ "case_sensitive":0,{ "conditiontype":"orid", "fieldoperator":"ocx_contact_id" }=", { "type":"id", "operator":"=", "operand":[ "222222221111" ], "case_sensitive":0, "condition":"orand", "field":"ocx_contact_id" } ], "user_type":"all" }, "combined_as_and":falsetrue } |
Request Example -
...
For Multiple Contact IDs
| Code Block |
|---|
{
"title":"All Members: Contact "ActiveID gmail contacts",
"selected_fields": [ "ocx_created_date", "email", "first_name", "last_name", "gender" ],
"filters": {(System field) equals \"1111\" OR Contact ID (System field) equals \"22222222\"",
"include_behavior":false,
"filters":{
"type":"Active",
"criteria": [
{ {
"type": "email", "field_name"type": "emailid",
"operator": "_LIKE=",
"operand":[
[ "gmail.com1111"
],
"case_sensitive": 0,
"condition": "andor"
,
} ], "user_typefield":"activeocx_contact_id"
}
} |
Request Example - Getting all contacts created before 01/01/2014 GMT+2
| Code Block |
|---|
{ "title": "Contacts created before 2014", "selected_fields": [ "ocx_created_date", "email", "first_name", "last_name", "gender" ], "filters": { "criteria": [ { }, { "type":"id", "typeoperator": "date_absolute=", "field_id": "ocx_created_date", "operand":[ "operator": "<", "operand22222222": [ 1388527200 ], ], "case_sensitive": 0, "condition":"or", "and "field":"ocx_contact_id" } ], "user_type":"activeall" }, "combined_as_and":false } |
Request Example - Getting all
...
For full behavioral operand usages please see "Segments" documentation
active gmail contacts
| Code Block |
|---|
{
"title": "AllActive gmail contacts from specific campaigns",
"selected_fields": [ "ocx_created_date", "email", "filters":{
"type":"Active",first_name", "last_name", "gender" ],
"filters": {
"criteria": [
{
"type"field_name": "sentemail",
"typefield_name": "behavioralemail",
"operator": "=_LIKE",
"operand": {[
"mailing_ids":["gmail.com"
],
85362, "case_sensitive": 0,
"condition": "and"
85360 }
]
},
"condition"user_type":"andactive",
}
} |
Request Example - Getting all contacts created before 01/01/2014 GMT+2
| Code Block |
|---|
{ "title": "Contacts created before 2014"left_parenthesis, "selected_fields":1, [ "ocx_created_date", "email", "first_name", "last_name", "gender" ], "right_parenthesisfilters":1 { }, "criteria": [ { "field_nametype": "clickeddate_absolute", "typefield_id": "behavioralocx_created_date", "operator": "=<", "operand": {[ 1388527200 ], "mailingcase_idssensitive":[ 0, "condition": "and" 85364, } ], "user_type":"active" 85366 } } |
Request Example - Getting all contacts that received a specific campaign
For full behavioral operand usages please see "Segments" documentation
| Code Block |
|---|
{ "title":"All contacts from specific campaigns", "filters":{ "type":"Active", "criteria":[ ], { "timefield_rangename":"sent", { "type":"behavioral", "operator": "custom=", "operand": { "frommailing_dateids": "2017-02-01 10:30:00",[ 85362, "to_date": "2017-02-23 10:30:00" 85360 }] }, "condition":"and", "left_parenthesis":1, "right_parenthesis":1 }, ], { "user_type":"all" }, "combined_as_and":true } |
Request Example - Getting all contacts that belong to a specific segment
| Code Block |
|---|
{ "titlefield_name":"Allclicked", contacts from specific segment", "filters":{ "type":"Activebehavioral", "criteriaoperator":["=", { "operand": { "type":"segment", "operandmailing_ids": [ 123456 ] // segment ID } 85364, ] } } |
Request Example - Creates contact activity report
| Code Block |
|---|
{ "title":"All Contacts: Email contains \"gmail\"", 85366 "filters":{ "type":"Active", ], "criteria":[ "time_range": { "typeoperator": "stringcustom", "operatorfrom_date":"LIKE "2017-02-01 10:30:00", "operandto_date":[ "2017-02-23 10:30:00" "gmail" } ]}, "case_sensitive"condition":0, "and", "conditionleft_parenthesis":"and"1, "fieldright_idparenthesis":"63282"1 } ], "user_type":"all", "from_date":1468738800, "to_date":1471503599 }, "combined_as_and":true } |
Request Example -
...
Getting all contacts that belong to a specific segment
| Code Block |
|---|
{
"title":"All contacts from specific "title":"Opened with Time range",
"include_behavior":true,
"filters":{
"criteria":[
{
"type":"behavioral",
"field_name":"opened",
"operator":"=segment",
"filters":{
"type":"Active",
"criteria":[
{
"type":"segment",
"operand": [ 123456 ] // segment ID
}
]
}
} |
Request Example - Creates contact activity report
| Code Block |
|---|
{
"title":"All Contacts: Email contains \"gmail\"",
"filters":{
"type":"Active",
"criteria":[
{
"type":"string",
"operator":"LIKE",
"operand":[
"gmail"
],
"case_sensitive":0,
"condition":"and",
"field_id":"63282"
}
],
"user_type":"all",
"from_date":1468738800,
"to_date":1471503599
},
"combined_as_and":true
} |
Request Example - Get all active openers within a certain range of dates
| Code Block |
|---|
{
"title":"Opened with Time range",
"include_behavior":true,
"filters":{
"criteria":[
{
"type":"behavioral",
"field_name":"opened",
"operator":"=",
"operand":{
"time_range": {
"operator":"custom",
"from_date":"1521350085",
"to_date":"1521359985"
}
},
"case_sensitive":0,
"condition":"and"
}
],
"user_type":"active"
}
} |
Request Example - How to Add a Date Filter to the Contact Search
See example 'from_date' and 'to_date' filters below:
| Code Block |
|---|
{
"title": "All Members: Email is not empty",
"include_behavior": false,
"filters": {
"type": "Active",
"criteria": [{
"type": "string",
"operator": "notempty",
"operand": [""],
"case_sensitive": 0,
"condition": "and",
"field_id": "123456" // This is the field id of the email field in that list. You can find that ID under List Settings -> Field Setup
}],
"user_type": "all"
"from_date": 1467320400,
"to_date": 1471381199
},
"combined_as_and": true
} |
Response (Major fields)
| Key | Description |
|---|---|
id | Newly created contact search ID |
status | Contact search status, will always be 1 (Pending) in this response |
Response Example - For Creating a Contact Search for All Members in a Given List
| Code Block |
|---|
{ "metadata": { "error": false }, "payload": { "list_id": 12345, "title": "All Members: Email is not empty", "include_behavior": false, "filters": { "type": "Active", "criteria": [ "operand":{ "type": "string", "time_rangeoperator": {"notempty", "operand": [ "operator":"custom", ], "fromcase_datesensitive":"1521350085" 0, "condition": "and", "tofield_dateid": "1521359985123456", "field_name": "email" } ], "user_type": "all" }, }, "combined_as_and": true, "caseaccount_sensitiveid":0 1234, "status": 1, "desc": "Pending", "conditionid":"and" 82169, } // This is ID of the ],search report that was created "user_typecreated":"active" 1470930202, "modified": 1470930202 } } |
Response (Major fields)
...
DELETE /api/contact_search/<Contact search report ID>
Description
This method deletes a contact search.
...