---
title: "Fetch Groups"
description: "Retrieve the contact groups available on your Bulkit account."
---

# Fetch Groups

Use this endpoint to list the contact groups that belong to your account, including contact counts for each group.

## Short description

Retrieve the contact groups available to the authenticated Bulkit account.

## HTTP method and path

```http
GET /api/v2/contacts/groups
```

## Authorization requirements

This endpoint supports:

- **Bearer token (recommended):** `Authorization: Bearer <your_api_token>`
- Legacy headers: `X-API-Key` and `X-API-Secret`
- URL query parameter: `?apikey=<your_api_token>`

## Authorization example

```http
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md
```

## Parameters

This endpoint does not require a request body.

### Authentication parameters

| Parameter | Location | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | Header | Yes (recommended) | string | `Bearer <your_api_token>` |
| `X-API-Key` | Header | Optional (legacy) | string | Your Bulkit key |
| `X-API-Secret` | Header | Optional (legacy) | string | Your Bulkit secret |
| `apikey` | Query | Optional fallback | string | API key used in URL authorization |

## Request examples

<CodeGroup>

```bash curl
curl -X GET "https://api.bulkitsms.com/api/v2/contacts/groups" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md"
```

```python python.py
import requests

response = requests.get(
    "https://api.bulkitsms.com/api/v2/contacts/groups",
    headers={
        "Authorization": "Bearer bk_live_8n6JQv3K1h9Lp0Md",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

```go main.go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.bulkitsms.com/api/v2/contacts/groups", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer bk_live_8n6JQv3K1h9Lp0Md")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", result)
}
```

```php php
<?php

$ch = curl_init("https://api.bulkitsms.com/api/v2/contacts/groups");

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md",
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    throw new Exception(curl_error($ch));
}

curl_close($ch);
echo $response . PHP_EOL;
```

</CodeGroup>

## Success response example

```json
{
  "status": "success",
  "data": [
    {
      "id": 14,
      "name": "Customers",
      "contact_count": 248
    }
  ]
}
```

## Error response examples

```json
{
  "status": "error",
  "message": "Invalid credentials"
}
```

## Notes

- call this endpoint first if your integration needs to validate or look up a destination group ID
- `contact_count` can be used to power sync dashboards and reconciliation jobs