V1 to V2 Migration Guide

The v2 API is a complete evolution of the Trackly SMS platform API. It introduces new resources, cleaner naming conventions, and fully functional CRUD endpoints. This guide covers every breaking change and new feature to help you migrate smoothly.

The v1 API is deprecated. All v1 responses now include deprecation headers. While v1 endpoints continue to function, we strongly recommend migrating to v2 as soon as possible.

What’s Still the Same

Before diving into changes, here is what has not changed:

Base URL: https://api.tracklysms.com/api
Authentication: The X-Api-Key header with your trk_[32-char-alphanumeric] key works identically in v2.
Content type: All requests use Content-Type: application/json.
HTTP methods: Standard REST conventions (GET, POST, PUT, PATCH, DELETE).

V1 Deprecation Headers

All v1 responses now include deprecation headers to signal that the endpoint is deprecated:

HTTP/1.1 200 OK
X-API-Deprecated: v1 is deprecated
Deprecation: true
Content-Type: application/json

Header	Value	Description
`X-API-Deprecated`	`v1 is deprecated`	Custom header indicating the endpoint is deprecated.
`Deprecation`	`true`	Standard deprecation header per RFC 8594.

Key Field Renames

The most impactful change is the renaming of core fields used in message sending.

Concept	v1 Field Name	v2 Field Name	Format
Sending number	`from_phone_number_id`	`list_number`	E.164
Recipient number	`to_msisdn` or `to`	`to`	E.164

Important Notes

list_number replaces from_phone_number_id. In v1, you passed a Trackly ID for the sending number. In v2, you pass the phone number itself in E.164 format (e.g. +14155551234).
to remains the same field name but now strictly requires E.164 format (e.g. +14155556789).

Response Format Changes

All v2 responses include a top-level success boolean field: V2 success response:

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

V2 error response:

{
  "error": "body is required",
  "code": "missing_body"
}

Success responses include a top-level success: true field. Error responses return a flat object with error (human-readable message) and code (machine-readable code) — no success field is included in errors.

Endpoint Path Changes

Message Sending

Action	v1 Endpoint	v2 Endpoint
Send a message	`POST /v1/messages`	`POST /v2/send`
Bulk send	`POST /v1/messages/bulk`	`POST /v2/send/bulk`

Contacts

Action	v1 Endpoint	v2 Endpoint
List contacts	`GET /v1/contacts`	`GET /v2/contacts`
Create contact	`POST /v1/contacts`	`POST /v2/contacts`
Get contact	`GET /v1/contacts/:id`	`GET /v2/contacts/:id`
Update contact	—	`PATCH /v2/contacts/:id`
Delete contact	—	`DELETE /v2/contacts/:id`
Bulk create	—	`POST /v2/contacts/bulk`

V1 contact endpoints (/v1/contacts) are no-ops — they accept requests but do not actually create, update, or persist contacts. V2 contact endpoints are fully functional with real CRUD operations.

New Resources in V2

The following resources are only available in v2 and have no v1 equivalent:

Resource	Endpoints	Description
Lists	`/v2/lists`	Manage sending lists and phone numbers.
Creatives	`/v2/creatives`	Create and manage message creatives with offer link placeholders.
Audiences	`/v2/audiences`	Build audience segments with conditions and filters.
Offers	`/v2/offers`	Manage affiliate offers linked to creatives.
Schedules	`/v2/schedules`	Schedule message sends for future delivery.
Revenue	`/v2/revenue`	Query revenue and conversion data.
History Import	`/v2/history/import`	Bulk import historical send data.

Side-by-Side: Sending a Message

V1 (Deprecated)

curl -X POST https://api.tracklysms.com/api/v1/messages \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from_phone_number_id": "6507f1f55bcf86cd799439011",
    "to_msisdn": "+14155556789",
    "body": "Hello from v1!"
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v1/messages",
    headers={"X-Api-Key": "trk_your_api_key_here"},
    json={
        "from_phone_number_id": "6507f1f55bcf86cd799439011",
        "to_msisdn": "+14155556789",
        "body": "Hello from v1!"
    }
)

data = response.json()
print(data)

const response = await fetch("https://api.tracklysms.com/api/v1/messages", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from_phone_number_id: "6507f1f55bcf86cd799439011",
    to_msisdn: "+14155556789",
    body: "Hello from v1!",
  }),
});

const data = await response.json();
console.log(data);

V1 Response:

{
  "id": "6507f1f55bcf86cd799439011",
  "message_id": "6507f1f55bcf86cd799439011",
  "status": "queued",
  "segments": 1,
  "gsm7": true,
  "deprecated": true
}

V2 (Current)

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 '{
    "list_number": "+14155551234",
    "to": "+14155556789",
    "body": "Hello from v2!"
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/send",
    headers={"X-Api-Key": "trk_your_api_key_here"},
    json={
        "list_number": "+14155551234",
        "to": "+14155556789",
        "body": "Hello from v2!"
    }
)

result = response.json()
if result.get("success"):
    print(f"Queued: {result['message_id']}")
else:
    print(f"Error: {result.get('error')}")

const response = await fetch("https://api.tracklysms.com/api/v2/send", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    list_number: "+14155551234",
    to: "+14155556789",
    body: "Hello from v2!",
  }),
});

const result = await response.json();
if (result.success) {
  console.log(`Queued: ${result.message_id}`);
} else {
  console.error(`Error: ${result.error}`);
}

V2 Response:

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

Migration Checklist

Use this checklist to track your migration progress:

Update send endpoint: Change POST /v1/messages to POST /v2/send
Rename from_phone_number_id: Replace with list_number using the E.164 phone number
Rename to_msisdn: Replace with to (if you were using to_msisdn)
Handle success field: Update response parsing to check the success boolean
Replace contact no-ops: If you were using /v1/contacts, switch to /v2/contacts for real CRUD
Adopt new resources: Evaluate whether /v2/creatives, /v2/audiences, /v2/schedules, and other new endpoints can simplify your integration
Test in development: Verify all updated endpoints before deploying to production
Remove deprecation header handling: Once fully migrated, you can stop monitoring for X-API-Deprecated headers

Need Help?

If you encounter issues during migration, reach out to our support team. When reporting an issue, include:

The full request URL and method
The request headers (redact your API key)
The request body
The full response body and status code

Next Steps

V2 API Overview

Explore all v2 endpoints and features

Error Codes

Handle v2 error responses

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

V1 to V2 Migration Guide

V1 to V2 Migration Guide

What’s Still the Same

V1 Deprecation Headers

Key Field Renames

Important Notes

Response Format Changes

Endpoint Path Changes

Message Sending

Contacts

New Resources in V2

Side-by-Side: Sending a Message

V1 (Deprecated)

V2 (Current)

Migration Checklist

Need Help?

Next Steps

V2 API Overview

Error Codes

​V1 to V2 Migration Guide

​What’s Still the Same

​V1 Deprecation Headers

​Key Field Renames

​Important Notes

​Response Format Changes

​Endpoint Path Changes

​Message Sending

​Contacts

​New Resources in V2

​Side-by-Side: Sending a Message

​V1 (Deprecated)

​V2 (Current)

​Migration Checklist

​Need Help?

​Next Steps

V2 API Overview

Error Codes

V1 to V2 Migration Guide

What’s Still the Same

V1 Deprecation Headers

Key Field Renames

Important Notes

Response Format Changes

Endpoint Path Changes

Message Sending

Contacts

New Resources in V2

Side-by-Side: Sending a Message

V1 (Deprecated)

V2 (Current)

Migration Checklist

Need Help?

Next Steps