# List round robins

Returns the round robins your account can open, one page at a time. Filter by name, status and people, and read assignment totals in deal_summary.

Source: https://dev.alterestate.com/deals/round-robins
Last updated: 2026-10-13

A round robin distributes incoming leads across a list of agents. Use this list to read the rules in your company and to copy a uid for the round_robin field on Create a lead. Every request uses the account token and stays inside that user’s company.

```http
GET https://secure.alterestate.com/api/v1/campaigns/round-robins/
```

Authentication: `Authorization: Token your_api_key_here`

| Parameter | In | Type | Required | Group | Description |
| --- | --- | --- | --- | --- | --- |
| `page` | query | integer | no | Pagination | Page number. Defaults to 1. |
| `page_size` | query | integer | no | Pagination | Results per page. The maximum is 25. A larger value is capped at 25. |
| `name` | query | string | no | Round robin | Partial name, case insensitive. |
| `uid` | query | string | no | Round robin | Exact round robin uid, case insensitive. |
| `is_active` | query | boolean | no | Round robin | true returns active round robins. false returns inactive ones. |
| `created_by` | query | integer | no | People | Numeric user id of who created the round robin. Repeat the parameter to match any of several users. The id is the one returned by List users. |
| `followers` | query | integer | no | People | Numeric user id of the follower on the round robin. Repeat the parameter to match any of several users. |
| `participants` | query | integer | no | People | Numeric user id of an agent who participates in the rotation. Repeat the parameter to match any of several agents. |
| `sort` | query | string | no | Sorting | Field to sort by. Prefix with - for descending. Defaults to newest first. See Sorting below. |

Example request:

```bash
curl --request GET \
  --url 'https://secure.alterestate.com/api/v1/campaigns/round-robins/?name=Website&is_active=true' \
  --header 'Authorization: Token your_api_key_here' \
  --header 'Accept: application/json'
```

Response 200 OK:

```json
{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 18,
      "company": 7,
      "uid": "K7M2PQ9X4A",
      "name": "Website leads",
      "last_assigned": 2,
      "created_by": "John Smith",
      "is_active": true,
      "is_public": true,
      "follower": "Ana Martinez",
      "notes": "Leads from the agency website.",
      "deals_goal": 40,
      "wondeals_goal": 8,
      "notify_to": "leads@agency.com",
      "redirect_emails": false,
      "timestamp": "2026-03-01T23:40:12.000000-04:00",
      "deal_summary": {
        "total": 24,
        "total_with_round_robin": 26,
        "won": 4,
        "lost": 6,
        "open": 14,
        "participant": 5,
        "assignments": 24,
        "duplicated_assignments": 2,
        "total_assignments": 26,
        "successful_deals": 24,
        "conversion_rate": 16.67
      }
    }
  ]
}
```

Response 401 Unauthorized:

```json
{
  "message": "Unauthorized user data",
  "error": "401"
}
```

## Who is included

The list is limited to the company of the token. A user allowed to view every campaign sees every round robin in that company. A team leader also sees round robins that include an agent on a team they lead. Every other user sees round robins they follow or participate in.

## Response

| Field | Description |
| --- | --- |
| count | Number of round robins that match the filters. |
| next, previous | URLs of the next and previous pages. null on the last or first page. |
| results | Round robins on this page. Newest first unless you send sort. |

## Fields on each round robin

| Field | Description |
| --- | --- |
| uid | Public identifier. Send this value as round_robin when you create a lead. |
| id | Internal numeric id. |
| company | Numeric id of the company that owns the round robin. |
| name | Name shown in the dashboard. |
| is_active | true while the round robin accepts new leads. |
| is_public | true when the round robin is marked visible to the whole company. |
| created_by | Display name of the user who created it, or null. |
| follower | Display name of the follower, or null. |
| notes | Internal notes, or null. |
| deals_goal, wondeals_goal | Target number of deals, and target number of won deals. |
| notify_to | Email that receives round robin notifications, or null. |
| redirect_emails | true sends those notifications to notify_to, or to the company email when notify_to is empty. |
| last_assigned | Cursor of the last assignment turn. The next agent is chosen from assignment history. |
| timestamp | When the round robin was created. |
| deal_summary | Assignment and deal totals. See below. |

## deal_summary

Counts cover deals that were actually handed to an agent (assigned or reassigned). total and successful_deals are the same number. conversion_rate is won divided by that number, as a percent with two decimals, or 0 when there are no successful deals.

| Field | Description |
| --- | --- |
| total, successful_deals | Deals assigned or reassigned through this round robin. |
| total_with_round_robin | Every deal linked to the round robin, including ones that were not assigned. |
| open, won, lost | Those successful deals, split by deal status. |
| participant | Agents currently in the rotation. |
| assignments | Successful assignment logs. |
| duplicated_assignments | Logs marked as a duplicate. |
| total_assignments | Every assignment log, including duplicates. |
| conversion_rate | Percent of successful deals that are won. |

## Sorting

Prefix the value with - to sort descending. Without sort, results are newest first.

| Value | Sorts by |
| --- | --- |
| timestamp | Date the round robin was created. |
| name | Name. |
| is_active | Active flag. |
| created_by | First name of the user who created it. |
| follower | First name of the follower. |
| participants | Number of agents in the rotation. |
| assignments | Number of successful assignments. |
| leads | Number of distinct deals assigned through the round robin. |

## Status codes

| Status | Meaning |
| --- | --- |
| 200 | The request succeeded. |
| 400 | A parameter or the body is invalid. The response names the field. |
| 401 | The token is missing, invalid, or the user cannot open this deal. |
| 404 | The resource or route does not exist. |
| 429 | Too many requests. Wait and retry. |
| 500 | Server error while processing the request. |

- [Assign a lead with round_robin](https://dev.alterestate.com/leads)
- [List deals](https://dev.alterestate.com/deals/list)
- [User ids for the people filters](https://dev.alterestate.com/users)

## FAQ

### How do I assign a lead to a round robin?

Copy uid from a result and send it as round_robin on POST /api/v1/leads/. That field takes precedence over related.

### Which round robins does the list return?

Only round robins in the token user’s company. A user who can view every campaign sees all of them. A team leader also sees round robins with an agent on a team they lead. Other users see round robins they follow or participate in.

### How do I filter by an agent?

Pass the numeric user id from List users. created_by matches who created the round robin, followers matches the follower, and participants matches an agent in the rotation. Repeat the same parameter to match any of several users.

### How many round robins does each page return?

25. page_size cannot go above 25. Pass page to move forward. next is null on the last page.