Segment API Methods
- Pratik Upadhyay
- Noam Rotem
- Ongage OngageConnect
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
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
- HTTP_Exception_403
HTTP_Exception_404
GET /api/segments
Description
- This method fetches a collection of segments.
- The number of Segments it will retrieve is based on the number indicated in the limit parameter. By default this value is 50. Setting it to 100 will retrieve 100, and so on and so forth.
- The offset parameter, enable you to first retrieve a set of 50 (or more), and then ask for the next 50 using the offset parameter. You'll especially want to use that if you have a lot of segments to retrieve.
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:
- field_id / field_name / conversion_point_id (field_name or conversion_point_id is required for behavioral criteria)
- type ("email" / "string" / "numeric" / "date_absolute" / "date_relative" / "behavioral" / "segment")
- operator ("LIKE" / "NOT LIKE" / "_LIKE" / "LIKE_" / "empty" / "notempty" / "=" / "!=" / "><" / ">" / "<" / ">=" / "<=" )
- operand (array of values)
- condition (and / or)
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
- Email contains "gmail"
- Birth Date before 10/01/1988
{
"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
- 400 - Invalid call
- 403 - Permission error
- 404 - Not found
- 412 - Invalid data
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:
- field_id / field_name / conversion_point_id (field_name or conversion_point_id is required for behavioral criteria)
- type ("email" / "string" / "numeric" / "date_absolute" / "date_relative" / "behavioral" / "segment")
- operator ("LIKE" / "NOT LIKE" / "_LIKE" / "LIKE_" / "empty" / "notempty" / "=" / "!=" / "><" / ">" / "<" / ">=" / "<=" )
- operand (array of values)
- condition (and / or)
Important: In case segment is a Whitelist Segment - the only allowed criteria type is "email" and the only allowed operator is "=".
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
- 400 - Invalid call
- 403 - Permission error
- 404 - Not found
- 412 - Invalid data
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
- First Name contains "James" / "Peter" / "David"
{
"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
- The first rule inside a group, should have have "and" condition
- All the rest of the rules should have "or" condition
- The first rule inside a group should have left_parenthesis = 1
- The last rule inside a group should have right_parenthesis = 1
- All rules inside a group must have a "group" string parameter, which will be used as the group title.
- All the rules inside a specific group should have the same "group" parameter value
- Rules outside a group should not have a "group" parameter
{
"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
- mailing_ids - array - optional - Mailing ids
- esp_connection_ids - array - optional - Esp connection ids
- time_range - object - Mandatory for all behavioral criteria's except when field_name is "sent".
available options:
- operator - string - Mandatory for "time range" - must have one of the following options only: "in_the_last" / "between" / "before" / "custom"
- in_last - number - Mandatory for "in_the_last" and "between" operators - cant be higher than "to"
- in_last_unit - string - Mandatory for "in_the_last" and "between" operators must have one of the following options only "day" / "week" / "month"
- to - number - Mandatory for "custom" and "between" operators - cant be lower than "in_last_unit"
- to_unit - string - Mandatory for "to" and "between" operators must have one of the following options only "day" / "week" / "month"
- from_date - string - Mandatory for "custom" operator - must be valid time stamp or a valid date format - cant be higher than "to_date"
- to_date - string - Mandatory for "custom" operator - must be valid time stamp or a valid date format - cant be lower than "from_date" - repeat - object - optional
must have the following:
- operator - string - Must have one of the following values: '<', '>', '='
- counter - number - Cant be higher than 200 - browsers - array - optional - Browser names
- countries - array - optional - Country codes
- platforms - array - optional - Platform (OS) names
- email_tag_ids - array - optional - ids of the your emails tags
{
"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
- You must defined in your operand the type of relative date operand been used: hours/days
- Hours and days cannot be used in the same rule
{
"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"
}
]
}