> ## 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.

# V2 API Overview

> The Trackly SMS v2 API — send messages, manage contacts, audiences, schedules, and more

The v2 API is the current, production-ready version of the Trackly SMS API. It replaces the deprecated v1 API with expanded functionality, consistent field naming, and new resource types.

## Base URL

All v2 API requests should be made to:

```
https://api.tracklysms.com/api/v2
```

## Authentication

Every request requires an API key in the `X-Api-Key` header:

```bash theme={null}
curl -X POST https://api.tracklysms.com/api/v2/send \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "list_number": "+18005551234", "body": "Hello!"}'
```

API keys follow the format `trk_[32-char-alphanumeric]`. See [Authentication](/api-reference/authentication) for details.

## What's New in V2

| Feature           | V1                   | V2                                           |
| ----------------- | -------------------- | -------------------------------------------- |
| Send messages     | Single & bulk        | Single, bulk, raw, raw bulk                  |
| Contacts          | No-op stubs          | Full CRUD + bulk + journey enrollment        |
| Lists             | Not available        | Read-only list management                    |
| Number Requests   | Not available        | Request number provisioning + track status   |
| Business Profiles | Not available        | Read-only brand/KYB profiles                 |
| Creatives         | Not available        | Full CRUD with segment estimation            |
| Audiences         | Not available        | Full CRUD with filter DSL + size calculation |
| Offers            | Not available        | Full CRUD with metadata                      |
| Schedules         | Not available        | Full CRUD with blast variants                |
| Revenue           | Not available        | Attribution tracking, single & bulk          |
| Data import       | Not available        | Import sends, clicks, revenue history        |
| Webhooks          | Delivery status only | Delivery, unsubscribe, reply events          |

## Request Format

* All requests must include `Content-Type: application/json`
* Phone numbers must be in E.164 format (e.g., `+14155551234`)
* Request bodies must be valid JSON
* Maximum payload size: 5 MB

## Response Format

All v2 responses use a consistent JSON structure.

<Tabs>
  <Tab title="Success (2xx)">
    ```json theme={null}
    {
      "success": true,
      "message_id": "AbC12345",
      "status": "queued"
    }
    ```
  </Tab>

  <Tab title="Error (4xx)">
    ```json theme={null}
    {
      "error": "Human-readable error description",
      "code": "machine_readable_error_code"
    }
    ```
  </Tab>
</Tabs>

## Pagination

Endpoints that return lists support pagination via query parameters:

| Parameter  | Default | Max                            | Description    |
| ---------- | ------- | ------------------------------ | -------------- |
| `page`     | 1       | —                              | Page number    |
| `per_page` | 50      | 1000 (contacts) / 100 (others) | Items per page |

Paginated responses include a `pagination` object:

```json theme={null}
{
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 238,
    "total_pages": 5
  }
}
```

## Bulk Operations

Bulk endpoints accept up to **1,000 records** per request. Each record is processed individually — partial success is possible. Bulk responses include per-record error details:

```json theme={null}
{
  "queued_count": 995,
  "error_count": 5,
  "errors": [
    {"index": 3, "to": "+1invalid", "code": "invalid_phone", "error": "Invalid recipient phone number format"}
  ]
}
```

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Messages" icon="paper-plane" href="/api-reference/v2/messages/send-single">
    Send single and bulk SMS messages
  </Card>

  <Card title="Raw Messages" icon="bolt" href="/api-reference/v2/messages/send-raw-single">
    Send raw messages with skip options
  </Card>

  <Card title="Contacts" icon="user" href="/api-reference/v2/contacts/list-contacts">
    Create, list, and manage contacts
  </Card>

  <Card title="Lists" icon="list" href="/api-reference/v2/lists/list-all">
    View sending lists and contact counts
  </Card>

  <Card title="Number Requests" icon="phone" href="/api-reference/v2/number-requests/list-all">
    Request number provisioning and track status
  </Card>

  <Card title="Business Profiles" icon="building" href="/api-reference/v2/business-profiles/list-all">
    Look up brand/KYB profiles
  </Card>

  <Card title="Creatives" icon="paintbrush" href="/api-reference/v2/creatives/list-creatives">
    Manage message templates with offer links
  </Card>

  <Card title="Audiences" icon="users" href="/api-reference/v2/audiences/list-audiences">
    Build dynamic audience segments
  </Card>

  <Card title="Offers" icon="tag" href="/api-reference/v2/offers/list-offers">
    Manage tracking offers and payouts
  </Card>

  <Card title="Schedules" icon="calendar" href="/api-reference/v2/schedules/list-schedules">
    Create and manage scheduled campaigns
  </Card>

  <Card title="Links" icon="link" href="/api-reference/v2/links/create-link">
    Create trackable short links for offers
  </Card>

  <Card title="Revenue" icon="dollar-sign" href="/api-reference/v2/revenue/record-revenue">
    Record revenue attribution
  </Card>

  <Card title="Data Import" icon="upload" href="/api-reference/v2/history/import-sends">
    Import historical sends, clicks, and revenue
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/v2/webhooks/events">
    Receive delivery and reply events
  </Card>

  <Card title="Audience Filters" icon="filter" href="/api-reference/v2/audience-filter-dsl">
    Build complex audience filter queries
  </Card>
</CardGroup>

## Migration from V1

If you're using the deprecated v1 API, see the [Migration Guide](/api-reference/v2/migration-guide) for a field-by-field comparison and upgrade path.

## Next Steps

<CardGroup cols={2}>
  <Card title="Send First SMS" icon="paper-plane" href="/quickstarts/send-first-sms">
    Send your first message in 5 minutes
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Set up your API key
  </Card>
</CardGroup>