Contact Activity API Methods

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 issuing and retrieving asynchronous contact activity reports.

In order to use this asynchronous flow, these methods should be used in the following order:

Create a new contact activity report: using POST api/contact_activity.
Check the report 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).
Retrieve the report in one of the following options:
1. The Export Combined Detailed Report CSV: GET /api/contact_activity/<Contact Activity search ID>/export_detailed
2. CSV of Aggregated Contact Activity Report: GET /api/contact_activity/<Contact Activity search ID>/export

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>/export

Description

This method retrieves the CSV of the aggregated contact activity report, just like the export CSV in the UI does:

GET /api/contact_activity/<Contact Activity search ID>/export_detailed

Description

This method retrieves the CSV of the Export Combined Detailed Report.

Just like this button in the UI does:

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", 
   "from_date":1593118800, // This can be timestamp of the date that you want the report range to start from.  
   "to_date":1595883599   // This can be timestamp of the date that you want the report range to end.   
 }
}

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.

Additional Examples

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"
   ]
}