# List Groups

Retrieve a paginated list of contact groups (mailing lists) from your address book. This endpoint supports sorting and pagination to help manage large numbers of groups.

### <mark style="color:green;">`GET`</mark> `/addressbook/groups`&#x20;

#### Required Permission

```
read:Groups
```

Your API key must have this permission enabled in order to use this endpoint.

### Example Request

```bash
curl --location 'https://<hostname>/addressbook/groups?sortField=created_on&sortDir=DESC&offset=0&limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

Replace `YOUR_API_KEY` with your API key.

{% hint style="info" %}
All endpoints shown in this documentation use a **sample base URL**. The production API endpoint is provided by our team upon request.
{% endhint %}

### Request Parameters

| Field     | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| sortField | string | No       | Field to sort by (e.g. `created_on`).       |
| sortDir   | string | No       | Sort direction: `ASC` or `DESC`.            |
| offset    | number | No       | Number of records to skip (for pagination). |
| limit     | number | No       | Maximum number of records to return.        |

### Responses

#### Success (HTTP 200)

```json
{
  "success": true,
  "records": [
    {
      "id": "3392287d-7a79-4789-9ef8-7dc174836688",
      "name": "test1",
      "created_on": "2025-11-10T21:30:45.000Z"
    }
  ],
  "offset": 0,
  "limit": 10,
  "total": 12
}
```

{% hint style="success" %}
This endpoint supports sorting and pagination. See [Search & Pagination Parameters](https://wiki.mobivatebulksms.com/search-and-pagination-parameters/introduction-to-searching-and-pagination) for details.
{% endhint %}