User Groups

Overview

To perform A/B tests, you create categories called User Groups, and each user group has sub-groups. The Sub-groups are the campaign elements you want to test.

The user group feature makes A/B experiments possible by dividing the entire pool of users that BrightRoll DSP reaches into buckets that can be targeted by a line item.

To run an A/B test, create one line for each user group (or group of user groups) that you want to target. Each experiment requires at least 2 lines.

Endpoint

https://dspapi.admanagerplus.yahoo.com/traffic/usergroups

Fields

The User Group object contains the following fields:

Name Description Type Add Update
id ID of the user group. integer N/A Required
name Name of the user group. Must be unique. text Required Required
accountId Advertiser/account ID. Refer to Advertisers. integer Required Optional
entries Array containing entries objects. array Required Required

entries object

Each element in the entries object contains the following fields:

Name Description Type Add Update
id ID of the sub-group. integer N/A Required
name Name of the sub-group. text Required Required
trafficPercent % traffic that should go to this sub-group. integer Required Required
userGroupId ID of the parent user group. integer Optional Optional
lowerBound Traffic % minimum. integer N/A N/A
upperBound Traffic % maximum. integer N/A N/A

Important The sum of all trafficPercent values in an entries object must be 100.

Example Payload

{
  "entries": [
    {
      "id": 32438,
      "trafficPercent": 60,
      "name": "zz57",
      "lowerBound": 80
    },
    {
      "id": 32439,
      "trafficPercent": 40,
      "name": "zz6"
    }
  ]
}

Read User Group (Single)

To retrieve data for a specific User Group, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/{id}
Name Description Type Required?
id User Group ID integer Y

The response will be the User Group associated with the given ID.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/1

Example Response

{
  "response": {
    "id": 1,
    "name": "test3",
    "accountId": 1259072,
    "entries": [
      {
        "id": 32391,
        "name": "g2",
        "userGroupId": 1,
        "trafficPercent": 50,
        "lowerBound": 0,
        "upperBound": 49
      },
      {
        "id": 32392,
        "name": "g1",
        "userGroupId": 1,
        "trafficPercent": 50,
        "lowerBound": 50,
        "upperBound": 99
      }
    ],
    "entryCount": 2
  },
  "errors": null,
  "timeStamp": "2017-04-27T01:42:43Z"
}

Read User Groups (Filtered)

To retrieve a filtered list of User Groups, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}
Name Description Type Required?
accountId Account or Advertiser ID integer Y
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N

The response will be a list of matching User Groups.

Example Request

GET https://dspapi.admanagerplus.yahoo.com/traffic/usergroups?accountId=1&query=test

Example Response

{
  "response": [
    {
      "id": 14836,
      "name": "test user group",
      "accountId": 1,
      "entries": [
        {
          "id": 32391,
          "name": "sub1",
          "userGroupId": 14836,
          "trafficPercent": 50,
          "lowerBound": 0,
          "upperBound": 49
        },
        {
          "id": 32392,
          "name": "sub2",
          "userGroupId": 14836,
          "trafficPercent": 50,
          "lowerBound": 50,
          "upperBound": 99
        }
      ],
      "entryCount": 2
    }
  ],
  "errors": null,
  "timeStamp": "2017-04-27T20:53:09Z"
}

Update User Group

To update an existing User Group, make a PUT call with a payload body and id parameter. The response will be the updated User Group.

Partial update is supported; fields that are either not passed or passed as null will be ignored during update.

PUT https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/{id}
Name Description Type Required?
id User Group ID integer Y

Example Request

PUT https://dspapi.admanagerplus.yahoo.com/traffic/usergroups/14836

Example Payload

{
  "accountId": 1,
  "name": "test user group 2",
  "entries": [
    {
      "id": 32391,
      "trafficPercent": 60,
      "name": "sub1"
    },
    {
      "id": 32392,
      "trafficPercent": 40,
      "name": "sub2"
    }
  ]
}

Example Response

{
  "response": {
    "id": 14836,
    "name": "test user group 2",
    "accountId": 1,
    "entries": [
      {
        "id": 32391,
        "name": "sub1",
        "userGroupId": 14836,
        "trafficPercent": 60,
        "lowerBound": 40,
        "upperBound": 99
      },
      {
        "id": 32392,
        "name": "sub2",
        "userGroupId": 14836,
        "trafficPercent": 40,
        "lowerBound": 0,
        "upperBound": 39
      }
    ],
    "entryCount": 2
  },
  "errors": null,
  "timeStamp": "2017-04-27T20:59:08Z"
}

Create User Group

To create a new User Group, make a POST call with a payload body. The response will be the newly created User Group.

Example Request

POST https://dspapi.admanagerplus.yahoo.com/traffic/usergroups

Example Payload

{
  "accountId": 1,
  "name": "test ug 1",
  "entries": [
    {
      "trafficPercent": 40,
      "name": "sub-g1"
    },
    {
      "trafficPercent": 60,
      "name": "sub-g2"
    }
  ]
}

Example Response

{
  "response": {
    "id": 14853,
    "name": "test ug 1",
    "accountId": 1,
    "entries": [
      {
        "id": 32440,
        "name": "sub-g2",
        "userGroupId": 14853,
        "trafficPercent": 60,
        "lowerBound": 40,
        "upperBound": 99
      },
      {
        "id": 32441,
        "name": "sub-g1",
        "userGroupId": 14853,
        "trafficPercent": 40,
        "lowerBound": 0,
        "upperBound": 39
      }
    ],
    "entryCount": 2
  },
  "errors": null,
  "timeStamp": "2017-04-27T21:18:28Z"
}

Delete User Group

User Group deletion is not supported by the API.