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, refer to 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, refer to 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}

All of the accepted parameters are query parameters.

Parameters

Parameter

Description

Data Type

Required

accountId

Specifies the advertiser ID.

integer

Y

query

Specifies the search term.

Use URL encoding conventions (i.e. replace spaces with a + or %20).

string

N

page

Specifies the page number.

integer

N

limit

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

sort

Specifies the column to sort by.

string

N

dir

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.

  • DESC: data is sorted in descending 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.