Custom Aggregate 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. 

Methods Summary

And is the API controller behind the Custom Aggregate Report in the UI:

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

1. Create New Custom Aggregate Report - using "POST api/aggregate_activity" You need to set a title for this new search, and the filters used for contacts segmentation.

2. Check the report status - Check the contact search status using "GET api/aggregate_activity/{Aggregate activity report ID}" When Aggregate activity is created, its always created in status "Pending" (1), in order to know when the aggregate activity is ready, use this method and verify that the status is "Completed" (2).

3. Retrieve the report - When status is Complete, use this method "GET /api/aggregate_activity/<Aggregate Activity search ID>/export" to export the report.

GET /api/aggregate_activity/<Aggregate Activity search ID>

Description 

This method fetches a custom aggregate search (without results). This method is used for checking the custom aggregate search status.

Response (Major fields)

GET /api/aggregate_activity/<Aggregate Activity search ID>/export

Description 

This method exports a custom aggregate activity report in CSV format, just like in the UI of the platform.

GET /api/aggregate_activity

Description 

This method fetches a collection of custom aggregate activity reports (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/aggregate_activity

Description 

This method creates a new custom aggregate activity report.

Request

title

Required string - Title for this aggregate 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 - You must provide at least one aggregated field for creation of new aggregate activity report.

Available fields: sent, opens, clicks, unsubscribes, complaints

Group fields

Required array - Array of your list fields that this report will be grouped by.

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 aggregate activity for Gmail contacts

POST URL: https://api.ongage.net/<list_id>/api/aggregate_activity

{
 "title": "Active gmail contacts",
 "selected_fields": [ "sent", "opens", "clicks", "unsubscribes", "complaints" ],
 "group_fields": [ "email" ],
 "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.  
 }
}

Request Example - Getting all contacts created before 01/01/2014 GMT+2

POST URL: https://api.ongage.net/<list_id>/api/aggregate_activity/api/aggregate_activity

{
 "title": "Contacts created before 2014",
 "selected_fields": [ "sent", "opens" ],
 "group_fields": [ "product_id" ],
 "filters": {
   "criteria": [
      {
        "type": "date_absolute",
        "field_id": "ocx_created_date",
        "operator": "<",
        "operand": [ 1388527200 ],
        "case_sensitive": 0,
        "condition": "and"
      }
   ],
   "user_type":"active"
 }
}

Response (Major fields)

DELETE /api/aggregate_activity/<Aggregate Activity report ID>

Description 

This method deletes a aggregate activity report.