Table of Contents:


(info) 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

GET /api/segments/<Segment ID>

Description 

This method fetches a single segment including rules and associated mailings.

Response Example - List Fields Segment

GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334

{
   "metadata": {
       "error": false
   },
   "payload": {
        "id": "12345",
        "list_id": "12345",
        "name": "list fields segment",
        "type": "Active",
        "description": "",
        "favorite": "0",
        "last_count": "345",
        "last_count_date": "1502005048",
        "last_count_request_date": null,
        "isp_breakdown": "",
        "last_sent": "0",
        "segment_quota": "0",
        "is_quota_percent": "0",
        "created_by": "1234",
        "created": "1502005048",
        "modified_by": "1234",
        "modified": "1502005048",
        "user_modified": "1502005048",
        "deleted": "0",
        "included_segment_cache": null,
        "excluded_segment_cache": null,
        "default_include_segment": "0",
        "default_exclude_segment": "0",
        "is_external": "0",
        "external_url": null,
        "external_insert_missing": "0",
        "external_include_unsubscribes": "0",
        "rules": [
        {
            "id": "1234",
            "segment_id": "12345",
            "position": "0",
            "left_parenthesis": "0",
            "field_id": "63337",
            "field_name": "email",
            "operator": "=",
            "operand": "[\"test@test.test\"]",
            "is_external_operand": "0",
            "right_parenthesis": "0",
            "condition": "and",
            "case_sensitive": "0",
            "type": "email",
            "group": ""
        },
        {
            "id": "5678",
            "segment_id": "12345",
            "position": "1",
            "left_parenthesis": "0",
            "field_id": "63347",
            "field_name": "product_id",
            "operator": ">",
            "operand": "[\"12345\"]",
            "is_external_operand": "0",
            "right_parenthesis": "0",
            "condition": "and",
            "case_sensitive": "0",
            "type": "numeric",
            "group": ""
        },
        {
            "id": "2696",
            "segment_id": "64548",
            "position": "2",
            "left_parenthesis": "0",
            "field_id": "63555",
            "field_name": "date",
            "operator": "=",
            "operand": "[1502966280]",
            "is_external_operand": "0",
            "right_parenthesis": "0",
            "condition": "and",
            "case_sensitive": "1",
            "type": "date_absolute",
            "group": ""
        }
        ],
        "mailings": [],
        "can_delete": true
      }
   }

Throws

GET /api/segments

Description 

Request

list_id

Optional integer - List ID

sort

Optional string - Segment column name

order

Optional string - "ASC" or "DESC"

offset

Optional integer

limit

Optional integer  (The default value is 50).

Response

GET URL: https://api.ongage.net/<list_id>/api/segments

{
 "metadata":{
  "error":false,
  "total":"2"
 },
 "payload":[
  {
   "id":"35114",
   "list_id":"23939",
   "list_name":"My List",
   "name":"My segment 1",
   "type":"Active",
   "description":"Description for segment",
   "favorite":"0",
   "last_sent":"1403796208",
   "last_count":"214",
   "last_count_date":"1403796208",
   "created_by":"868",
   "created":"1403796208",
   "modified":"1403796208",
   "deleted":"0",
   "modifier":"John Doe"
  },
  {
   "id":"34939",
   "list_id":"23939",
   "list_name":"My List",
   "name":"My segment 2",
   "type":"Active",
   "description":"",
   "favorite":"0",
   "last_sent":"1403016334",
   "last_count":"99",
   "last_count_date":"1403016334",
   "created_by":"868",
   "created":"1403016334",
   "modified":"1403016334",
   "deleted":"0",
   "modifier":"John Doe"
  }
 ]
}

POST /api/segments

Description 

This method is used to create a segment.

Request

list_id

Optional number - The list id to which the segment should be saved under. Default - Default list ID

name

Required string - Segment name

type

Required string - Segment type (Active / Deleted)

is_whitelist

Optional boolean - Flag the segment as Whitelist Segment -this segment stakeholders will receive the campaign message under all circumstances

description

Optional string - Segment description

favorite

Optional boolean - Flag the segment as favorite

is_external

Optional boolean - External segment

external_url

Optional string - The URL from which to retrieve the external segment The 'criteria' parameter needs to be provided as empty with such segments. Once the segment is created, it can only be used as a campaign segment.

external_insert_missing

Optional boolean - Flag that equals TRUE tells the system that if contacts in the external Segment, that don't exist in your List database, should be added to the List (default FALSE), so that all opens, clicks, unsubscribes, bounces, etc. can be attributed to all the contacts in the external segment.

external_include_unsubscribes

Optional boolean - Flag that equals TRUE if unsubscribed contacts should be included in the segment (default FALSE)

criteria

Optional array - Segment rules criteria should include an array of segment rules, having:

(warning) Important: In case segment is a Whitelist Segment - the only allowed criteria type is "email" and the only allowed operator is "=".

Request Example - Creating segment with 2 rules

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

{
   "name":"My segment",
   "type":"Active",
   "description":"This is my segment",
   "criteria":[
      {
         "field_id":1234, // Email
         "type":"email",
         "position":0,
         "operator":"LIKE",
         "operand":[
            "gmail"
         ],
         "condition":"and"
      },
      {
         "field_id":1235, // Birthdate
         "position":1,
         "operator":"<",
         "type":"date_absolute",
         "operand":[
            884404800
         ],
         "condition":"and"
      }
   ]
}

Notice

Any configuration that does not follow the above requirements, will not be supported by GUI.

Error Codes

PUT /api/segments/<Segment ID>

Description 

This method updates segments based on id from request and also saves in segment_rules table values in criteria. It returns single row with updated details.

Request

list_id

Optional number - The list id to which the segment should be saved under. Default - Default list ID

name

Required string - Segment name

type

Required string - Segment type (Active / Deleted)

is_whitelist

Optional boolean - Flag the segment as Whitelist Segment -this segment stakeholders will receive the campaign message under all circumstances

description

Optional string - Segment description

favorite

Optional boolean - Flag the segment as favorite

criteria

Optional array - Segment rules criteria should include an array of segment rules, having:

(warning) Important: In case segment is a Whitelist Segment - the only allowed criteria type is "email" and the only allowed operator is "=".

(warning) For code examples see POST /api/segments method additional examples on this page.

Notice

Any configuration that does not follow the above requirements, will not be supported by GUI.

Error Codes

PUT /api/segments/<Segment ID>/populate_external

Description 

This feature is designed to serve customers, that do email marketing from within their own CRM and don't need the Ongage segmentation management feature, as they do their own segmentation directly from within their CRM. After creating a segment, as an external segment (using the POST api/segments with the external flag set to true) use this method to then populate the external segment with email addresses and their accompanying dynamic list field data. For more about external segments see "What are External Segments" in our Segments documentation.

PUT URL: https://api.ongage.net/<list_id>/api/segments/1112223334/populate_external

{
   "recipients":[
      {
         "email":"jane.doe1@somedomain.com",
         "first_name":"Jane",
         "last_name":"Doe-1"
      },
      {
         "email":" jane.doe2@somedomain.com ",
         "first_name":"Jane",
         "last_name":"Doe-2"
      },
      {
         "email":" jane.doe3@somedomain.com",
         "first_name":"Jane",
         "last_name":"Doe-3"
      },
      {
         "email":" jane.doe4@somedomain.com ",
         "first_name":"Jane",
         "last_name":"Doe-4"
      }
   ]
}

DELETE /api/segments/<Segment ID>

Description 

This method deletes a segment. By deleting segment, this method will also unschedule any scheduled campaign using this segment.

POST /api/segments/export

Description 

This endpoint is deprecated, please use POST /api/export instead.

GET /api/segments/<Export ID>/export_retrieve

Description 

This endpoint is deprecated, please use GET /api/export/<Export ID>/retrieve instead.

Additional Examples

Response Example - System Fields Segment:

GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334

{
   "metadata": {
       "error": false
   },
   "payload": {
        "id": "12345",
        "list_id": "12345",
        "name": "list fields segment",
        "type": "Active",
        "description": "",
        "favorite": "0",
        "last_count": "345",
        "last_count_date": "1502005048",
        "last_count_request_date": null,
        "isp_breakdown": "",
        "last_sent": "0",
        "segment_quota": "0",
        "is_quota_percent": "0",
        "created_by": "1234",
        "created": "1502005048",
        "modified_by": "1234",
        "modified": "1502005048",
        "user_modified": "1502005048",
        "deleted": "0",
        "included_segment_cache": null,
        "excluded_segment_cache": null,
        "default_include_segment": "0",
        "default_exclude_segment": "0",
        "is_external": "0",
        "external_url": null,
        "external_insert_missing": "0",
        "external_include_unsubscribes": "0",
        "rules": [
           {
                "id": "2697",
                "segment_id": "64549",
                "position": "0",
                "left_parenthesis": "0",
                "field_id": "0",
                "field_name": "ocx_created_date",
                "operator": "<=",
                "operand": "[\"13\"]",
                "is_external_operand": "0",
                "right_parenthesis": "0",
                "condition": "and",
                "case_sensitive": "0",
                "type": "date_relative",
                "group": ""
            },
            {
                "id": "2698",
                "segment_id": "64549",
                "position": "1",
                "left_parenthesis": "0",
                "field_id": "0",
                "field_name": "ocx_unsubscribe_date",
                "operator": "=",
                "operand": "[1503705600]",
                "is_external_operand": "0",
                "right_parenthesis": "0",
                "condition": "and",
                "case_sensitive": "0",
                "type": "date_absolute",
                "group": ""
            },
            {
                "id": "2699",
                "segment_id": "64549",
                "position": "2",
                "left_parenthesis": "0",
                "field_id": "0",
                "field_name": "ocx_resubscribe_date",
                "operator": ">=",
                "operand": "[1503705600]",
                "is_external_operand": "0",
                "right_parenthesis": "0",
                "condition": "and",
                "case_sensitive": "0",
                "type": "date_absolute",
                "group": ""
            },
            {
               "id": "2700",
               "segment_id": "64549",
               "position": "3",
               "left_parenthesis": "0",
               "field_id": "0",
               "field_name": "ocx_import_id",
               "operator": "=",
               "operand": "[\"13\",\"23456\"]",
               "is_external_operand": "0",
               "right_parenthesis": "0",
               "condition": "and",
               "case_sensitive": "0",
               "type": "numeric",
               "group": ""
            }
        ],
        "mailings": [],
        "can_delete": true
      }
   }

Response Example - Behavioral Segment

GET URL: https://api.ongage.net/<list_id>/api/segments/1112223334

{
   "metadata": {
       "error": false
   },
   "payload": {
        "id": "12345",
        "list_id": "12345",
        "name": "list fields segment",
        "type": "Active",
        "description": "",
        "favorite": "0",
        "last_count": "345",
        "last_count_date": "1502005048",
        "last_count_request_date": null,
        "isp_breakdown": "",
        "last_sent": "0",
        "segment_quota": "0",
        "is_quota_percent": "0",
        "created_by": "1234",
        "created": "1502005048",
        "modified_by": "1234",
        "modified": "1502005048",
        "user_modified": "1502005048",
        "deleted": "0",
        "included_segment_cache": null,
        "excluded_segment_cache": null,
        "default_include_segment": "0",
        "default_exclude_segment": "0",
        "is_external": "0",
        "external_url": null,
        "external_insert_missing": "0",
        "external_include_unsubscribes": "0",
        "rules": [
          {
             "id": "2701",
             "segment_id": "64550",
             "position": "0",
             "left_parenthesis": "0",
             "field_id": "0",
             "field_name": "sent",
             "operator": "=",
             "operand": {
                 "mailing_ids": [
                     "84715",
                     "84668",
                     "84666"
                 ],
                 "esp_connection_ids": [],
                 "time_range": [],
                 "repeat": {
                     "operator": "<",
                     "counter": "5"
                 },
                 "browsers": [],
                 "countries": [],
                 "platforms": []
              },
              "is_external_operand": "0",
              "right_parenthesis": "0",
              "condition": "and",
              "case_sensitive": "0",
              "type": "behavioral",
              "group": ""
          },
          {
             "id": "2702",
             "segment_id": "64550",
             "position": "1",
             "left_parenthesis": "0",
             "field_id": "0",
             "field_name": "opened",
             "operator": "!=",
             "operand": {
                  "mailing_ids": [
                      "84715",
                      "84668",
                      "84666"
                  ],
                  "esp_connection_ids": [
                      "60129",
                      "60128",
                      "60367"
                  ],
                  "time_range": {
                     "operator": "between",
                     "in_last": "10",
                     "in_last_unit": "day",
                     "to": "1",
                     "to_unit": "month"
                  },
                  "repeat": {
                     "operator": "<",
                     "counter": "5"
                  },
                  "browsers": [
                     "Chrome"
                  ],
                  "countries": [
                     "AF",
                     "BD",
                     "IO"
                  ],
                  "platforms": [
                     "Linux"
                  ]
             },
             "is_external_operand": "0",
             "right_parenthesis": "0",
             "condition": "and",
             "case_sensitive": "0",
             "type": "behavioral",
             "group": ""
           },
          {
            "id": "2703",
            "segment_id": "64550",
            "position": "2",
            "left_parenthesis": "0",
            "field_id": "0",
            "field_name": "clicked",
            "operator": "=",
            "operand": {
               "mailing_ids": [],
               "esp_connection_ids": [
                 "60129"
               ],
               "time_range": {
                   "operator": "custom",
                   "from_date": 1501545600,
                   "to_date": 1504137600
               },
               "repeat": [],
               "browsers": [],
               "countries": [],
               "platforms": []
            },
            "is_external_operand": "0",
            "right_parenthesis": "0",
            "condition": "and",
            "case_sensitive": "0",
            "type": "behavioral",
            "group": ""
          }
        ],
        "mailings": [],
        "can_delete": true
      }
   }

Request Example - Creating segment with rule that includes multiple values

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

{
   "name":"My segment",
   "type":"Active",
      "description":"This is my segment",
   "criteria":[
      {
         "field_id":1234, // First name
         "type":"string",
         "position":0,
         "operator":"LIKE",
         "case_sensitive":"1",
         "operand":[
            "James",
            "Peter",
            "David"
         ],
         "condition":"and"
      }
   ]
}

Request Example - Creating segment with OR Groups

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

{
   "name":"My Group segment",
   "type":"Active",
      "description":"This is my segment",
   "criteria":[
      {
         "field_id":1233, // Email
         "type":"string",
         "position":0,
         "operator":"LIKE",
         "operand":[
            "@gmail"
         ],
         "condition":"and"
      },
      {
         "field_id":1234, // First name
         "type":"string",
         "group":"First name or last name or address",
         "position":1,
         "left_parenthesis":1,
         "operator":"notempty",
         "condition":"and"
      },
      {
         "field_id":1235, // Last name
         "type":"string",
         "group":"First name or last name or address",
         "position":1,
         "operator":"notempty",
         "condition":"or"
      },
      {
         "field_id":1236, // Address
         "type":"string",
         "group":"First name or last name or address",
         "position":2,
         "right_parenthesis":1,
         "operator":"notempty",
         "condition":"or"
      }
   ]
}

Request Example - Creating behavioral segment - operand options

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

{
   "name":"Behavioral Segment",
   "type":"Active",
   "criteria":[
      {
         "type":"behavioral",
         "position":1,
         "field_name":"opened",
         "operator":"=",
         "operand":{
            "mailing_ids":[
               85362,
               85360
            ],
            "esp_connection_ids":[
               60133,
               60387
            ],
            "time_range":{
               "operator":"between",
               "in_last":30,
               "in_last_unit":"day",
               "to":2,
               "to_unit":"month"
            },
            "browsers":[
               "Chrome"
            ],
            "countries":[
               "AZ",
               "BH"
            ],
            "platforms":[
               "Linux",
               "Win8.1"
            ]
         },
         "condition":"and"
      },
      {
         "type":"behavioral",
         "position":1,
         "field_name":"clicked",
         "operator":"=",
         "operand":{
            "time_range":{
               "operator":  "custom",
               "from_date": 2017-02-01 10:30:00,
               "to_date":   2017-02-23 10:30:00
            }
         },
         "condition":"and"
      }
   ]
}

Request Example - Creating a Segment Based on the Ongage Import ID

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

{
   "name":"Segment Based on Import ID",
   "type":"Active",
   "description":"Segment based on Import ID",
   "criteria":[
      {
         "condition":"and",
         "field_name":"ocx_import_id_all",
         "type":"numeric",
         "position":0,
         "operator":"=",
         "operand":[
            "11111111"
         ]
      }
   ]
}

Request Example - Creating Whitelist Segment - operand options

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

{
   "name":"Whitelist Segment",
   "type":"Active",
   "description":"This is a Whitelist Segment",
   "is_whitelist": true,
   "criteria":[
      {
         "field_id":1234, // Email
         "type":"email",
         "position":0,
         "operator":"=",
         "operand":[
            "james@test.com",
            "peter@test.com",
            "david@test.com"
         ],
         "condition":"and"
      }
   ]
}

Request Example - Creating segment with date relative rules

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

{
   "name":"Segment with date relative rules",
   "type":"Active",
   "description":"This segment has relative rules",
   "criteria":[
      {
         "field_id":1234, // Some date field
         "type":"date_relative",
         "position":0,
         "operator":"<=",
         "operand":{
            "days": 6
         },
         "condition":"and"
      },
      {
         "field_id":5678, // Another date field
         "type":"date_relative",
         "position":0,
         "operator":">",
         "operand":{
            "hours": 16
         },
         "condition":"and"
      }
   ]
}