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.

Endpoint

Use the following endpoint to read, create, and update user groups.

/traffic/usergroups

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

  • Use the GET method to retrieve user groups.
  • Use the POST method to add new user groups.
  • Use the PUT method to update individual user groups.

Resources

User Group Object

The User Group object contains the following fields:

Field Description Data Type Add 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’s account 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:

Field Description Data Type Add Update
id

Specifies the subgroup ID.

The id is required to update an existing subgroup entries object. It is not required if you are adding a new entries object.

integer N/A Optional
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

Example Payload

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

Read User Groups by ID

Retrieves data for the user group associated with the specified user group id.

GET /traffic/usergroups/{id}

Parameters

The API takes a single parameter specified in endpoint path.

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

Example Request

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

Example Response

The response returns the user group associated with the specified ID.

{
  "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 by Query

Retrieves a filtered list of user groups.

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

Parameters

All parameters are specified as a query appended to the endpoint.

Table 158 Read User Group by Query Parameters
Parameter Paramerer Type Description Data Type Required
accountId query Specifies the advertiser’s account ID. integer Y
page query Specifies the page number. integer N
limit query Specifies the page number. integer N
sort query Specifies the column to sort by. string N
dir query Specifies the sort direction. Options include ASC or DESC. string N
query query Specifies the search terms. Use URL encoding conventions (i.e. a space should be replaced with a + or a %20). string N

Example Request

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

Example Response

The response returns a list of matching user groups.

{
  "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 Groups

Updates the user group associated with the specified user group ID.

PUT /traffic/usergroups/{id}

Partial updates are supported. Unspecified parameters are either not passed or passed as null and are ignored during update.

Parameters

The User Group ID is specified in the endpoint path. All other parameters are specified in the body of the application/json payload.

Table 159 Update User Groups Parameters
Parameter Parameter Type Description Data Type Required
id path Specifies the user group ID. integer Y
name body Specifies the name of the user group. string N
accountId body

Specifies the advertiser’s account ID.

To learn more, see Advertisers.

integer N
entries body Specifies an array of entries objects. array N

Example Request

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

Example Payload

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

Create User Groups

Creates a new user group.

POST /traffic/usergroups/

Parameters

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

Table 160 Update User Groups Parameters
Parameter Parameter Type Description Data Type Required
name body Specifies the name of the user group. string Y
accountId body

Specifies the advertiser’s account ID.

To learn more, see Advertisers.

integer N
entries body Specifies an array of entries objects. array Y

Example Request

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

Example Payload

{
  "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 Groups

The DSP Traffic API does not support deleting user groups.