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

# Contacts and groups

> Manage MsgFlash contacts, contact groups, and bulk deletions through the public API.

## Contacts

### Endpoints

| Method   | Endpoint                                      |
| -------- | --------------------------------------------- |
| `GET`    | `/api/v1/contacts`                            |
| `POST`   | `/api/v1/contacts`                            |
| `GET`    | `/api/v1/contacts/{id}`                       |
| `PUT`    | `/api/v1/contacts/{id}`                       |
| `DELETE` | `/api/v1/contacts/{id}`                       |
| `POST`   | `/api/v1/contacts/bulk-delete`                |
| `GET`    | `/api/v1/contacts/bulk-jobs`                  |
| `GET`    | `/api/v1/contacts/bulk-jobs/{jobId}`          |
| `GET`    | `/api/v1/contacts/bulk-jobs/{jobId}/progress` |
| `POST`   | `/api/v1/contacts/bulk-jobs/{jobId}/cancel`   |

### Parameters

#### `POST /api/v1/contacts`

| Field   | Type      | Required | Location | Description        |
| ------- | --------- | -------- | -------- | ------------------ |
| `name`  | string    | yes      | body     | Full name          |
| `phone` | string    | yes      | body     | E.164 number       |
| `tags`  | string\[] | no       | body     | Contact tags       |
| `meta`  | object    | no       | body     | Free-form metadata |

#### `PUT /api/v1/contacts/{id}`

| Field   | Type      | Required | Location | Description       |
| ------- | --------- | -------- | -------- | ----------------- |
| `id`    | UUID      | yes      | path     | Contact ID        |
| `name`  | string    | no       | body     | New name          |
| `phone` | string    | no       | body     | New number        |
| `tags`  | string\[] | no       | body     | Replaces tags     |
| `meta`  | object    | no       | body     | Replaces metadata |

#### `POST /api/v1/contacts/bulk-delete`

| Field        | Type    | Required | Location | Description    |
| ------------ | ------- | -------- | -------- | -------------- |
| `contactIds` | UUID\[] | yes      | body     | 1 to 10000 IDs |

### Create a contact

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/contacts \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Awa Doe",
    "phone": "+33612345000",
    "tags": ["vip", "newsletter"],
    "meta": {
      "city": "Cotonou"
    }
  }'
```

### Bulk delete contacts

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/contacts/bulk-delete \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
  }'
```

Response example:

```json theme={null}
{
  "data": {
    "requested": 2,
    "deleted": 1,
    "notFound": ["CONTACT_UUID_2"]
  }
}
```

Async response example (`>= 100` contacts):

```json theme={null}
{
  "data": {
    "mode": "async",
    "jobId": "job_abc123",
    "status": "pending",
    "operation": "bulk_delete_contacts",
    "requestedCount": 900,
    "progress": 0
  }
}
```

### Common errors

| Code               | HTTP | When                        |
| ------------------ | ---- | --------------------------- |
| `VALIDATION_ERROR` | 400  | Invalid body                |
| `NOT_FOUND`        | 404  | Requested contact not found |

***

## Contact groups

### Endpoints

| Method   | Endpoint                                    |
| -------- | ------------------------------------------- |
| `GET`    | `/api/v1/contacts/groups`                   |
| `POST`   | `/api/v1/contacts/groups`                   |
| `GET`    | `/api/v1/contacts/groups/{groupId}`         |
| `PUT`    | `/api/v1/contacts/groups/{groupId}`         |
| `DELETE` | `/api/v1/contacts/groups/{groupId}`         |
| `POST`   | `/api/v1/contacts/groups/{groupId}/members` |
| `DELETE` | `/api/v1/contacts/groups/{groupId}/members` |
| `GET`    | `/api/v1/contacts/groups/{groupId}/members` |
| `GET`    | `/api/v1/contacts/{id}/groups`              |

### Parameters

#### `POST /api/v1/contacts/groups`

| Field         | Type   | Required | Location | Description    |
| ------------- | ------ | -------- | -------- | -------------- |
| `name`        | string | yes      | body     | Group name     |
| `description` | string | no       | body     | Description    |
| `color`       | string | no       | body     | Hex color code |

#### `POST /api/v1/contacts/groups/{groupId}/members`

| Field        | Type    | Required | Location | Description               |
| ------------ | ------- | -------- | -------- | ------------------------- |
| `groupId`    | UUID    | yes      | path     | Group ID                  |
| `contactIds` | UUID\[] | yes      | body     | 1 to 10000 members to add |

#### `GET /api/v1/contacts/groups/{groupId}/members`

| Parameter | Type    | Required | Location | Description             |
| --------- | ------- | -------- | -------- | ----------------------- |
| `groupId` | UUID    | yes      | path     | Group ID                |
| `limit`   | integer | no       | query    | Page size               |
| `cursor`  | string  | no       | query    | Cursor                  |
| `search`  | string  | no       | query    | Filter by name or phone |

### Create a group

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/contacts/groups \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clients VIP",
    "description": "High-value clients",
    "color": "#F59E0B"
  }'
```

### Add members

```bash theme={null}
curl -X POST https://srv.msgflash.com/api/v1/contacts/groups/GROUP_ID/members \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
  }'
```

Async behavior:

* `< 100` contacts: synchronous response
* `>= 100` contacts: asynchronous `202` response with a `jobId`
* Poll `GET /api/v1/contacts/bulk-jobs/{jobId}/progress` every `2s`

### List members

```bash theme={null}
curl "https://srv.msgflash.com/api/v1/contacts/groups/GROUP_ID/members?limit=20&search=awa" \
  -H "x-api-key: msgf_live_your_api_key_here"
```

Response:

```json theme={null}
{
  "data": {
    "members": [],
    "nextCursor": null,
    "hasMore": false
  }
}
```

<Note>
  The groups exposed here are MsgFlash contact groups, not native WhatsApp groups.
</Note>

### Common errors

| Code                         | HTTP | When                                      |
| ---------------------------- | ---- | ----------------------------------------- |
| `MAX_CONTACT_GROUPS_REACHED` | 403  | Group limit reached                       |
| `NOT_FOUND`                  | 404  | Group or contact not found                |
| `CONFLICT`                   | 409  | A group with the same name already exists |