V2 API Overview - Trackly SMS

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:

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

Success (2xx)
Error (4xx)

{
  "success": true,
  "message_id": "AbC12345",
  "status": "queued"
}

{
  "error": "Human-readable error description",
  "code": "machine_readable_error_code"
}

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:

{
  "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:

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

Available Endpoints

Messages

Send single and bulk SMS messages

Raw Messages

Send raw messages with skip options

Contacts

Create, list, and manage contacts

Lists

View sending lists and contact counts

Number Requests

Request number provisioning and track status

Business Profiles

Look up brand/KYB profiles

Creatives

Manage message templates with offer links

Audiences

Build dynamic audience segments

Offers

Manage tracking offers and payouts

Schedules

Create and manage scheduled campaigns

Links

Create trackable short links for offers

Revenue

Record revenue attribution

Data Import

Import historical sends, clicks, and revenue

Webhooks

Receive delivery and reply events

Audience Filters

Build complex audience filter queries

Migration from V1

If you’re using the deprecated v1 API, see the Migration Guide for a field-by-field comparison and upgrade path.

​Base URL

​Authentication

​What’s New in V2

​Request Format

​Response Format

​Pagination

​Bulk Operations

​Available Endpoints

Messages

Raw Messages

Contacts

Lists

Number Requests

Business Profiles

Creatives

Audiences

Offers

Schedules

Links

Revenue

Data Import

Webhooks

Audience Filters

​Migration from V1

​Next Steps

Send First SMS

Authentication

Base URL

Authentication

What’s New in V2

Request Format

Response Format

Pagination

Bulk Operations

Available Endpoints

Migration from V1

Next Steps