---
title: "User Groups"
slug: "user-groups"
updated: 2024-10-15T19:13:04Z
published: 2024-10-15T19:13:04Z
canonical: "help.yahooinc.com/user-groups"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/dsp-api/docs/ab-testing).

## Hierarchy

A `User Group` is an advertiser-level object.

## Endpoint

```plaintext
/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](/dsp-api/docs/advertisers). | `integer` | Required | Optional |
| `entries` | Specifies an array of [entries](/dsp-api/docs/user-groups#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](/dsp-api/docs/user-groups#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.

```plaintext
GET /traffic/usergroups/{id}
```

### Parameters

| **Parameter** | **Parameter Type** | **Description** | **Data Type** | **Required** |
| --- | --- | --- | --- | --- |
| `id` | path | Specifies the user group ID. | `integer` | Y |

#### Example Request URL

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

#### Example Response

```plaintext
{
  "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.

```plaintext
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

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

#### Example Response

```plaintext
{
  "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.

```plaintext
POST /traffic/usergroups/
```

### Parameters

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

#### Example Request URL

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

#### Example Request Body

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

#### Example Response

```plaintext
{
  "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.

```plaintext
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

```plaintext
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 displays a payload that updates two existing subgroups (`32438` and `32439`) and adds a third named `zz99`.

```plaintext
{
  "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

```plaintext
{
  "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.