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
id User Group ID (Required) integer

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={search query}
Name Description Type
accountId Account or Advertiser ID (Required) integer
page Page number integer
limit Total number of items to return. Maximum allowed value is 100. integer
sort Column to sort by text
dir Sort direction. Valid values: asc, desc text
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text

The response will be the list of User Groups matching the given filter(s).

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 User Group object payload 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
id User Group ID (Required) integer

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 the User Group object payload. 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.