Skip to main content

​
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://app.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
HeaderValueDescription
X-API-Deprecatedv1 is deprecatedCustom header indicating the endpoint is deprecated.
DeprecationtrueStandard deprecation header per RFC 8594.

​
Key Field Renames

The most impactful change is the renaming of core fields used in message sending.
Conceptv1 Field Namev2 Field NameFormat
Sending numberfrom_phone_number_idlist_numberE.164
Recipient numberto_msisdn or totoE.164

​
Important Notes

  • list_number replaces from_phone_number_id. In v1, you passed an internal 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

Actionv1 Endpointv2 Endpoint
Send a messagePOST /v1/messagesPOST /v2/send
Bulk sendPOST /v1/messages/bulkPOST /v2/send/bulk

​
Contacts

Actionv1 Endpointv2 Endpoint
List contactsGET /v1/contactsGET /v2/contacts
Create contactPOST /v1/contactsPOST /v2/contacts
Get contactGET /v1/contacts/:idGET /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:
ResourceEndpointsDescription
Lists/v2/listsManage sending lists and phone numbers.
Creatives/v2/creativesCreate and manage message creatives with offer link placeholders.
Audiences/v2/audiencesBuild audience segments with conditions and filters.
Offers/v2/offersManage affiliate offers linked to creatives.
Schedules/v2/schedulesSchedule message sends for future delivery.
Revenue/v2/revenueQuery revenue and conversion data.
History Import/v2/history/importBulk import historical send data.

​
Side-by-Side: Sending a Message

​
V1 (Deprecated)

curl -X POST https://app.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!"
  }'
V1 Response: 
{
  "id": "6507f1f55bcf86cd799439011",
  "message_id": "6507f1f55bcf86cd799439011",
  "status": "queued",
  "segments": 1,
  "gsm7": true,
  "deprecated": true
}

​
V2 (Current)

curl -X POST https://app.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!"
  }'
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:
  1. The full request URL and method
  2. The request headers (redact your API key)
  3. The request body
  4. The full response body and status code

​
Next Steps

V2 API Overview

Explore all v2 endpoints and features

Error Codes

Handle v2 error responses