Table of Contents:
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.
In order to use the asynchronous flow, the following methods should be used in the following order:
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.
Response (Major fields)
| 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.
Request
sort
Optional string - Sort by column name
order
Optional string - "ASC" or "DESC"
offset
Optional int
limit
Optional int
Response
The response includes Array of contacts similar to example shared below.
{
"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).
Request
list_id
Optional string - List ID (see "Indicating List ID in Ongage API Calls" in APIDocs homepage for more info)
sort
Optional string - Sort by column name
order
Optional string - "ASC" or "DESC"
offset
Optional int
limit
Optional int
POST /api/contact_search
Description
This method creates a new contact search.
Request
title
Required string - Title for this contact search
filters
Required array - Filters array can include: criteria, type, user_type, from_date, to_date
favorite
Optional boolean - Default is false, Favorite on/off
selected_fields
Optional array - Use this array parameters if you want to indicate only some of your list fields, which is faster & more efficient. If you don't use this parameter, the query will return all the list fields for all contacts returned in this search.
Currently, the selected_fields parameter, is only available when using "include_behavior = false".
Available system fields: ocx_created_date, ocx_contact_id, ocx_status, ocx_unsubscribe_date, ocx_resubscribe_date, ocx_import_id
criteria
Mandatory array of arrays - Criteria's to filter by results
*field_name : String - The field_name for this criteria
*type : String - The type of field (string/numeric/email/date/id)
*operator : String - Operator for criteria condition
*operand : Array - Array of operand values, will be filter with OR condition
*case_sensitive : 1 or 0 - Case sensitivity
*condition : String - Condition for whole criteria (and/or)
Operator options
For strings / emails
* = : Equals
* != : Not equals
* LIKE : Contains
* NOT LIKE : Doesn't contain
* LIKE_ : Begins with
* _LIKE : Ends with
* empty : Is empty
* notempty : Is not empty
For numeric / id
* < : Is lower than
* <= : Is lower than or equals
* > : Is greater than
* >= : Is greater than or equals
* = : Equals
* != : Is different from
* empty : Is empty
* notempty : Is not empty
* >< : Range
For dates
* < : Before
* <= : Before or on
* > : After
* >= : On or after
* = : On
* != : Not on
* 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.
{
"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"
},
"combined_as_and": true
}
Request Example - For Single Contact Id
{
"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
{
"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
{
"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
{
"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
{
"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
{
"title":"All contacts from specific segment",
"filters":{
"type":"Active",
"criteria":[
{
"type":"segment",
"operand": [ 123456 ] // segment ID
}
]
}
}
Request Example - Creates contact activity report
{
"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
{
"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:
{
"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
{
"metadata": {
"error": false
},
"payload": {
"list_id": 12345,
"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",
"field_name": "email"
}
],
"user_type": "all"
},
"combined_as_and": true,
"account_id": 1234,
"status": 1,
"desc": "Pending",
"id": 82169, // This is ID of the search report that was created
"created": 1470930202,
"modified": 1470930202
}
}
DELETE /api/contact_search/<Contact search report ID>
Description
This method deletes a contact search.