User Groups

This article describes resources and services for reading, adding, and updating user groups.

Overview

A user group is a category of consumers that enable you to perform A/B testing. Each user group consists of two or more subgroups (entries objects) that represent the campaign elements you want to test.

During A/B testing these subgroups may be targeted by a line. To run an A/B test, create one line for each subgroup that you want to target. Each experiment requires at least two lines. To learn more, see A/B Testing Targeting.

Hierarchy

A User Group is an advertiser-level object.

Endpoint

/traffic/usergroups

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read an existing user group.
  • Use the POST method to create a new user group.
  • Use the PUT method to update an existing user group.

Resources

User Group Object

The User Group object contains the following fields:

Table 150 User Group Fields
Field Description Data Type Create Update
id Specifies the user group ID. integer N/A Required
name Specifies the name of the user group. string Required Optional
accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer Required Optional
entries Specifies an array of entries objects. array Required Optional

Entries Object

The entries object contains the following fields:

Table 151 Entries Fields
Field Description Data Type Create Update
id

Specifies the subgroup ID.

[1]Required when updating an existing subgroup in the entries array.
integer N/A Required [1]
name Specifies the name of the user subgroup. string Required Required
trafficPercent

Specifies the percentage of the total traffic to be directed to the user subgroup.

The sum of all trafficPercent values in an entries array must equal 100.

integer Required Required
userGroupId Specifies the ID number of the parent user group. integer N/A Optional
lowerBound Read-only field that reports the minimum percentage of traffic directed to the subgroup. integer N/A N/A
upperBound Read-only field that reports the maximum percentage of traffic directed to the subgroup. integer N/A N/A

Read User Group

Get data for a specific user group.

GET /traffic/usergroups/{id}

Parameters

Table 152 Read User Group Parameters
Parameter Paramerer Type Description Data Type Required
id path Specifies the user group ID. integer Y

Example Request URL

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

Example Response

{
  "response": {
    "id": 16890,
    "name": "test3ug",
    "accountId": 1356341,
    "entries": [
      {
        "id": 36517,
        "name": "g1",
        "userGroupId": 16890,
        "trafficPercent": 30,
        "lowerBound": 0,
        "upperBound": 29
      },
      {
        "id": 36518,
        "name": "g2",
        "userGroupId": 16890,
        "trafficPercent": 70,
        "lowerBound": 30,
        "upperBound": 99
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T05:56:03Z"
}

Read User Groups

Get a filtered list of user groups.

GET /traffic/usergroups?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Table 153 Read User Groups Parameters
Parameter Paramerer Type Description Data Type Required
accountId query Specifies the advertiser ID. integer Y
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. Maximum allowed value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

Example Request URL

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

Example Response

{
  "response": [
    {
      "id": 16890,
      "name": "test3ug",
      "accountId": 1356341,
      "entries": [
        {
          "id": 36517,
          "name": "g1",
          "userGroupId": 16890,
          "trafficPercent": 30,
          "lowerBound": 0,
          "upperBound": 29
        },
        {
          "id": 36518,
          "name": "g2",
          "userGroupId": 16890,
          "trafficPercent": 70,
          "lowerBound": 30,
          "upperBound": 99
        }
      ]
    }
  ],
  "errors": null,
  "timeStamp": "2017-09-22T06:01:59Z"
}

Update User Group

Update an existing user group.

PUT /traffic/usergroups/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Parameters

The User Group id is specified in the url path. All other fields are specified in the body of the application/json payload.

Example Request URL

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

Example Request Body

The sum of the subgroups specified in the entries array must equal 100.

You do not need to specify an ID for new subgroups added to the entries array. Example below shows a payload that updates two existing subgroups (32438 and 32439) and adds a third named zz99.

{
  "accountId": 1356341,
  "name": "xyz889",
  "entries": [
    {
      "id": 32438,
      "trafficPercent": 60,
      "name": "zz57",
      "userGroupId": 14828
    },
    {
     "id": 32439,
     "trafficPercent": 30,
     "name": "zz6"
    },
    {
     "trafficPercent": 10,
     "name": "zz99"
    }
  ]
}

Example Response

{
  "response": {
    "id": 16890,
    "name": "xyz889",
    "accountId": 1356341,
    "entries": [
      {
        "id": 32455,
        "name": "zz99",
        "userGroupId": 16890,
        "trafficPercent": 10,
        "lowerBound": 90,
        "upperBound": 99
      },
      {
        "id": 32439,
        "name": "zz6",
        "userGroupId": 16890,
        "trafficPercent": 30,
        "lowerBound": 60,
        "upperBound": 89
      },
      {
        "id": 32438,
        "name": "zz57",
        "userGroupId": 16890,
        "trafficPercent": 60,
        "lowerBound": 0,
        "upperBound": 59
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T06:04:26Z"
}

Create User Group

Create a new user group.

POST /traffic/usergroups/

Parameters

All parameters are specified in the body of the application/json payload.

Example Request URL

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

Example Request Body

{
  "accountId": 1356341,
  "name": "test3ug",
  "entries": [
    {
      "trafficPercent": 30,
      "name": "g1"
    },
    {
      "trafficPercent": 70,
      "name": "g2"
    }
  ]
}

Example Response

{
  "response": {
    "id": 16890,
    "name": "test3ug",
    "accountId": 1356341,
    "entries": [
      {
        "id": 36517,
        "name": "g1",
        "userGroupId": 16890,
        "trafficPercent": 30,
        "lowerBound": 0,
        "upperBound": 29
      },
      {
        "id": 36518,
        "name": "g2",
        "userGroupId": 16890,
        "trafficPercent": 70,
        "lowerBound": 30,
        "upperBound": 99
      }
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T05:56:03Z"
}

Delete User Group

The DSP Traffic API does not support deletion of user groups.