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 - For Single Contact Id
Code Block |
---|
{
"title":"All Members: Contact ID (System field) equals \"1111\"",
"include_behavior":false,
"filters":{
"type":"Active",
"criteria":[
{
"type":"id",
"operator":"=",
"operand":[
"1111"
],
"case_sensitive":0,
"condition":"and",
"field":"ocx_contact_id"
}
],
"user_type":"all"
},
"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",
"criteria":[
{
"type":"id",
"operator":"=",
"operand":[
"1111"
],
"case_sensitive":0,
"condition":"or",
"field":"ocx_contact_id"
},
{
"type":"id",
"operator":"=",
"operand":[
"22222222"
],
"case_sensitive":0,
"condition":"or",
"field":"ocx_contact_id"
}
],
"user_type":"all"
},
"combined_as_and":false
} |
Request Example - Getting all active gmail contacts
Code Block |
---|
{ "title": "Active gmail contacts", "selected_fields": [ "ocx_created_date", "email", "first_name", "last_name", "gender" ], "filters": { "criteria": [ { "type": "email", "field_name": "email", "operator": "_LIKE", "operand": [ "gmail.com" ], "case_sensitive": 0, "condition": "and" } ], "user_type":"active" } } |
...
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": "date_absolute", "field_id": "ocx_created_date", "operator": "<", "operand": [ 1388527200 ], "case_sensitive": 0, "condition": "and" } ], "user_type":"active" } } |
...
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":[ { "field_name":"sent", "type":"behavioral", "operator":"=", "operand": { "mailing_ids":[ 85362, 85360 ] }, "condition":"and", "left_parenthesis":1, "right_parenthesis":1 }, { "field_name":"clicked", "type":"behavioral", "operator":"=", "operand": { "mailing_ids":[ 85364, 85366 ], "time_range": { "operator": "custom", "from_date": "2017-02-01 10:30:00", "to_date": "2017-02-23 10:30:00" } }, "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 |
---|
{ "title":"All contacts from specific 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" } } |
...
Key | Description |
---|---|
id | Newly created contact search ID |
status | Contact search status, will always be 1 (Pending) in this response |
DELETE /api/contact_search/<Contact search report ID>
Description
This method deletes a contact search.
...