Segment API Methods
Table of Contents:
- 1 Methods Summary
- 1.1 GET /api/segments/<Segment ID>
- 1.1.1 Description
- 1.1.2 Response Example - List Fields Segment
- 1.1.3 Throws
- 1.2 GET /api/segments
- 1.2.1 Description
- 1.2.2 Request
- 1.2.3 Response
- 1.3 POST /api/segments
- 1.3.1 Description
- 1.3.2 Request
- 1.3.3 Request Example - Creating segment with 2 rules
- 1.3.4 Notice
- 1.3.5 Error Codes
- 1.4 PUT /api/segments/<Segment ID>
- 1.4.1 Description
- 1.4.2 Request
- 1.4.3 Notice
- 1.4.4 Error Codes
- 1.5 PUT /api/segments/<Segment ID>/populate_external
- 1.5.1 Description
- 1.6 DELETE /api/segments/<Segment ID>
- 1.6.1 Description
- 1.7 POST /api/segments/export
- 1.7.1 Description
- 1.8 GET /api/segments/<Export ID>/export_retrieve
- 1.8.1 Description
- 1.9 Additional Examples
- 1.9.1 Response Example - System Fields Segment:
- 1.9.2 Response Example - Behavioral Segment
- 1.9.3 Request Example - Creating segment with rule that includes multiple values
- 1.9.4 Request Example - Creating segment with OR Groups
- 1.9.5 Request Example - Creating behavioral segment - operand options
- 1.9.6 Request Example - Creating a Segment Based on the Ongage Import ID
- 1.9.7 Request Example - Creating Whitelist Segment - operand options
- 1.9.8 Request Example - Creating segment with date relative rules
- 1.1 GET /api/segments/<Segment ID>
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.
The maximum payload for this call is 33MB (33,554,432 bytes). You'll need to do multiple call should you need to populate an external segment with more data).
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 200browsers - 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"
}
]
}