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

# Trial Testing Groups

> Create, inspect and close customer-owned testing groups through the existing API-key scopes.

A testing group organizes trial messages. It does not own a physical sending number or receive a separate allowance. Public API paths use the name `trial-campaigns`; these customer groups are separate from staff-managed carrier registrations.

| Method and path | Scope | Successful response |
| - | - | - |
| `GET /v2/trial-campaigns` | `sends.read` | `200` with `trial_campaigns` and nullable `next_cursor` |
| `POST /v2/trial-campaigns` | `sends.write` | `201` with `trial_campaign` |
| `GET /v2/trial-campaigns/{id}` | `sends.read` | `200` with `trial_campaign` |
| `DELETE /v2/trial-campaigns/{id}` | `sends.write` | `200` with the closed `trial_campaign` |

Every group contains `id`, `name`, `state` (`active` or `closed`), `created_at` and nullable `closed_at`. Timestamps use UTC. Foreign or absent IDs return `404 trial_not_found`.

## Create a group

```bash theme={null}
curl -X POST 'https://api.tracklysms.com/api/v2/trial-campaigns' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Webhook integration testing"}'
```

The body accepts only `name`: nonempty text after trimming, at most 200 characters. Creation requires an active eligible trial and enabled new-work availability. Sandbox keys cannot create or close groups.

## Browse and inspect

```bash theme={null}
curl 'https://api.tracklysms.com/api/v2/trial-campaigns?limit=25' \
  -H 'X-Api-Key: YOUR_API_KEY'
curl 'https://api.tracklysms.com/api/v2/trial-campaigns/YOUR_GROUP_ID' \
  -H 'X-Api-Key: YOUR_API_KEY'
```

The default page size is 50; `limit` accepts 1 through 100. Pass the returned opaque `next_cursor` as the next request's `cursor` query parameter. Do not interpret or construct cursors.

## Close a group

```bash theme={null}
curl -X DELETE 'https://api.tracklysms.com/api/v2/trial-campaigns/YOUR_GROUP_ID' \
  -H 'X-Api-Key: YOUR_API_KEY'
```

Closure fences new submissions and recoverably cancels queued reservations. It preserves history, used allowance and permanent conversation ownership. An attempted message may still arrive. Reads and closure remain available when new trial work is disabled, subject to normal authorization and backend availability.

Malformed input returns `400 trial_invalid_request`; disabled new work returns `403 trial_disabled`; an ended or ineligible trial returns `403 trial_inactive`; a competing revision can return `409 trial_revision_conflict`; unavailable authority returns `503 trial_unavailable`. Refresh before retrying a conflict.

The dashboard uses session authentication and permits only account owners to create or close groups. These public API-key scopes and send contracts remain unchanged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.