User Groups

This article describes resources and services you can use to view, add, and update user groups.

Overview

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

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

Use the following HTTP methods:

  • Use the GET method to view 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

The User Group object contains the following 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. array Required Optional

Entries

The entries object contains the following fields:

Field Description Data Type Create Update
id

Specifies the subgroup ID.

Required to update an existing subgroup in the entries array.

integer N/A Required
name Specifies the name of the subgroup. string Required Required
trafficPercent

Specifies the percentage of the total traffic to be directed to the 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

Parameter Parameter 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

Parameter Parameter 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. replace spaces 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"
}

Create User Group

Create a new user group.

POST /traffic/usergroups/

Parameters

All fields 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"
}

Update User Group

Update an existing user group.

PUT /traffic/usergroups/{id}

Partial updates are supported; values of supported fields that are not in the payload 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. The following example 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"
}

Delete User Group

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