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 activity reports.
In order to use the asynchronous flow, the following methods should be used in the following order:
Create instance - Create a new contact activity report using "POST api/contact_activity" 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_activity/{Contact activity report ID}" When contact activity is created, its always created in status "Pending" (1), in order to know when the contact activity 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_activity/{Contact activity report ID}/result" This will return an array of the contacts you searched for.
GET /api/contact_activity/<Contact Activity search ID>
Description
This method fetches a contact activity search (without results). This method can be used for checking the contact activity status.
Response (Major fields)
| Key | Description |
|---|---|
status | Contact activity status, 1 = Pending, 2 = Completed |
status_desc | Contact activity report status description (Pending / Completed) |
GET /api/contact_activity/<Contact Activity search ID>/result
Description
This method fetches the contact activity results. This is the same report you see in the UI under Analytics -> Contact Activity Report, 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
GET URL: https://api.ongage.net/<list_id>/api/contact_activity/<contact_activity_search_id>/result
The response includes Array of contacts similar to example shared below.
{
"metadata": {
"error": false,
"fields": {},
"total": 3
},
"payload": [
{
"email": "email1@gmail.com",
"last_name": "some-name",
"opens": 4,
"clicks": 2,
"unsubscribe":0,
"complains":0
},
{
"email": "email2@gmail.com",
"last_name": "some-name2",
"opens": 3,
"clicks": 1,
"unsubscribe":0,
"complains":1
},
{
"email": "email3@gmail.com",
"last_name": "some-name3",
"opens": 1,
"clicks": 0,
"unsubscribe":1,
"complains":1
}
]
}
GET /api/contact_activity/<Contact Activity search ID>/export
Description
This method exports an contact activity.
GET /api/contact_activity/<Contact Activity search ID>/export_detailed
Description
This method exports the combined detailed contact activity report.
GET /api/contact_activity
Description
This method fetches a collection of contact activity (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_activity
Description
This method creates a new contact activity report.
Request
title
Required string - Title for this contact activity
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
Required array - Indicate which of your list fields will be used in the report.
Available system fields: ocx_created_date, id, ocx_status, ocx_unsubscribe_date, ocx_resubscribe_date, ocx_import_id,
Available activity aggregation fields: sent, opens, clicks, last_sent_date, last_open_date, last_click_date, avg_open_time, avg_click_time
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 - Getting all active gmail contacts
POST URL: https://api.ongage.net/<list_id>/api/contact_activity
{
"title": "Active gmail contacts",
"selected_fields": [ "email", "ocx_status", "opens", "clicks" ],
"filters": {
"criteria": [
{
"type": "email",
"field_name": "email",
"operator": "_LIKE",
"operand": [
"gmail.com"
],
"case_sensitive": 0,
"condition": "and"
}
],
"user_type":"active"
}
}
Request Example - Getting Contact Activity for a Segment for 1 month
POST URL: https://api.ongage.net/<list_id>/api/contact_activity
{
"title":"Belongs to Segment Id: 1234567890", // Use Segment ID for which you want to generate report
"include_behavior":true,
"filters":{
"criteria":[
{
"field_name":"segment",
"type":"segment",
"operator":"=",
"operand":[
"1234567890" // Use Segment ID for which you want to generate report
],
"case_sensitive":0,
"condition":"and"
}
],
"user_type":"all",
"from_date":1593118800, // Use Date/Timestamp i.e. 1 month prior to current date. Date has to be in MM/DD/YYYY format included as "MM/DD/YYYY".
"to_date":1595883599 // Use today's Date/timestamp
},
"combined_as_and":true,
"selected_fields":[
"email",
"ocx_created_date",
"ocx_status",
"sent",
"opens",
"clicks",
"ocx_unsubscribe_date",
"ocx_resubscribe_date",
"ocx_bounce_date",
"ocx_complaint_date",
"last_sent_date",
"last_open_date"
]
}
Request Example - Getting Contact Activity for a Campaign for 2 weeks
POST URL: https://api.ongage.net/<list_id>/api/contact_activity
{
"title":"Belongs to Segment Id: 1234567890", // Use Campaign ID for which you want to generate report
"include_behavior":true,
"filters":{
"criteria":[
{
"field_name":"sent",
"type":"behavioral",
"operator":"=",
"operand":{
"mailing_ids":[
"1234567890" // Use Campaign ID for which you want to generate report
],
}
"case_sensitive":0,
"condition":"and"
}
],
"user_type":"all",
"from_date":1593118800, // Use Date/Timestamp i.e. 2 weeks prior to current date. Date has to be in MM/DD/YYYY format included as "MM/DD/YYYY".
"to_date":1595883599 // Use Today's Date/timestamp
},
"combined_as_and":true,
"selected_fields":[
"email",
"ocx_created_date",
"ocx_status",
"sent",
"opens",
"clicks",
"ocx_unsubscribe_date",
"ocx_resubscribe_date",
"ocx_bounce_date",
"ocx_complaint_date",
"last_sent_date",
"last_open_date"
]
}
Response (Major fields)
| Key | Description |
|---|---|
id | Newly created contact activity report ID |
status | Contact activity report status, will always be 1 (Pending) in this response |
DELETE /api/contact_activity/<Contact Activity report ID>
Description
This method deletes a aggregate activity report.