Marketing API Version

Segments

Provides operations to create, read, update and delete Segments.

Read Segments

Permissions

A user access token with Atlas API capability is required to request segment details.

Fields

Reading this endpoint returns a single or an array of Segment objects with the same fields as the node.

Read Segment

You can get details of the segment by making an HTTP GET request.

An example of the request and response:

Request:

https://graph.facebook.com/<API_VERSION>/<SEGMENT_ID>

Response:

{
  "advertiser_id": "11002200631100", 
  "created_date": "2014-04-18T17:44:54+0000", 
  "definition": {
    "action_groups": [
      {
        "actions": [
          {
            "action_tag_id": "11002200637000", 
            "is_negative": false, 
            "lookback_begin_days_ago": "30", 
            "lookback_end_days_ago": "0", 
            "min_count": "1"
          }
        ], 
        "is_negative": false
      }
    ], 
    "constraints": [
      [
        {
          "action_tag_id": "11002200637000", 
          "is_negative": false, 
          "lookback_begin_days_ago": "30", 
          "lookback_end_days_ago": "0", 
          "min_count": "1"
        }
      ]
    ], 
    "schema_version": "2"
  }, 
  "description": "Test desc", 
  "id": "11002200636000", 
  "is_favorite": false, 
  "last_modified_date": "2014-07-14T18:16:00+0000", 
  "name": "Test Segment", 
  "version": "2"
}

Curl Example:

A curl example to get segment details:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<SEGMENT_ID>

Read Advertiser Segment

You can get details of the segments for an advertiser by making an HTTP GET request.

An example of the request and response:

Request:

https://graph.facebook.com/<API_VERSION>/<ADVERTISER_ID>/atlassegments

Response:

{
  "data": [
        {
      "advertiser_id": "11002200631100", 
      "created_date": "2014-04-18T17:44:54+0000", 
      "definition": {
        "action_groups": [
          {
            "actions": [
              {
                "action_tag_id": "11002200637000", 
                "is_negative": false, 
                "lookback_begin_days_ago": "30", 
                "lookback_end_days_ago": "0", 
                "min_count": "1"
              }
            ], 
            "is_negative": false
          }
        ], 
        "constraints": [
          [
            {
              "action_tag_id": "11002200637000", 
              "is_negative": false, 
              "lookback_begin_days_ago": "30", 
              "lookback_end_days_ago": "0", 
              "min_count": "1"
            }
          ]
        ], 
        "schema_version": "2"
      }, 
      "description": "Test desc", 
      "id": "11002200636000", 
      "is_favorite": false, 
      "last_modified_date": "2014-07-14T18:16:00+0000", 
      "name": "Test Segment", 
      "version": "2"
    }
 ]
}

Curl Example

A curl example to get segment details for an advertiser details:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<ADVERTISER_ID>/segments

Create Segments

Permissions

A user access token with Atlas API capability is required to create or update segment details.

Fields

Publishing this endpoint returns a single or an array of Segment objects.

Create Segment

You can create segment for an advertiser by making an HTTP POST request. It will update the segment if it already exists.

An example of the request and response:

Request:

https://graph.facebook.com/<API_VERSION>/<ADVERTISER_ID>/segments?segments=[{  "version": "1", "name": "Test Segment",  "description": "",   "definition": {         
"schema_version": "2", "constraints": [ [{"action_tag_id": "11002200637000",               
 "lookback_begin_days_ago": "30", "lookback_end_days_ago": "0",                
"min_count": "1", "is_negative": false,"action_tag": { "id": "11002200637000",                  
"is_deleted": false, "version": "1", "advertiser_id": "11002200631100",                 
 "classic_action_id": "600000", "location_url": "",  "click_window_days": "90", "view_window_days": "14", "repeat_conversion_window_seconds": "60",                 
 "type": "0", "multi_action_tag_id": "0" } } ], ], "action_groups": [           
{ "actions": [ { "action_tag_id": "11002200637000",                  
"lookback_begin_days_ago": "30", "lookback_end_days_ago": "0",                 
 "min_count": "1", "is_negative": false, "action_tag": {                  "id": "11002200637000",  "is_deleted": false, "version": "1",                    
"advertiser_id": "11002200631100", "classic_action_id": "600000",                                     
"location_url": "", "click_window_days": "90", "view_window_days": "14", "repeat_conversion_window_seconds": "60",  "type": "0",  "multi_action_tag_id": "0"  }  }  ],  "is_negative": false   } ]  },  "is_favorite": false }]

Response:

{
  "data": [
    {
      "id": "11002200636000", 
      "success": true
    }
  ]
}

Curl Example

A curl example to create segment for an advertiser:


curl \ -F 'segments=[{ "version": "1", "name": "Test Segment", "description": "", "definition": { "schema_version": "2", "constraints": [ [{"action_tag_id": "11002200637000", "lookback_begin_days_ago": "30", "lookback_end_days_ago": "0", "min_count": "1", "is_negative": false,"action_tag": { "id": "11002200637000", "is_deleted": false, "version": "1", "advertiser_id": "11002200631100", "classic_action_id": "600000", "location_url": "", "click_window_days": "90", "view_window_days": "14", "repeat_conversion_window_seconds": "60", "type": "0", "multi_action_tag_id": "0" } } ], ], "action_groups": [ { "actions": [ { "action_tag_id": "11002200637000", "lookback_begin_days_ago": "30", "lookback_end_days_ago": "0", "min_count": "1", "is_negative": false, "action_tag": { "id": "11002200637000", "is_deleted": false, "version": "1", "advertiser_id": "11002200631100", "classic_action_id": "600000", "location_url": "", "click_window_days": "90", "view_window_days": "14", "repeat_conversion_window_seconds": "60", "type": "0", "multi_action_tag_id": "0" } } ], "is_negative": false } ] }, "is_favorite": false }]' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/<ADVERTISER_ID>/segments