Create Offer

{
  "success": true,
  "offer": {
    "id": "664f1a2b3c4d5e6f7a8b9c0d",
    "slug": "ofr_summer-promo_a1b2c3",
    "name": "Summer Promo",
    "tracking_url": "https://track.example.com/click?offer_id=123",
    "external_platform": "tune",
    "external_id": "4521",
    "advertiser_id": "adv_882",
    "advertiser_name": null,
    "payout": 2.50,
    "payout_type": "cpa",
    "filter_bots": true,
    "status": "active",
    "metadata": {
      "vertical": "health",
      "geo": "US"
    },
    "excluded_days_of_week": [],
    "day_parting_enabled": false,
    "day_parting": {},
    "created_at": "2025-11-01T14:30:00",
    "updated_at": "2025-11-01T14:30:00"
  }
}

{
  "error": "name is required",
  "code": "missing_name"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

POST

offers

{
  "success": true,
  "offer": {
    "id": "664f1a2b3c4d5e6f7a8b9c0d",
    "slug": "ofr_summer-promo_a1b2c3",
    "name": "Summer Promo",
    "tracking_url": "https://track.example.com/click?offer_id=123",
    "external_platform": "tune",
    "external_id": "4521",
    "advertiser_id": "adv_882",
    "advertiser_name": null,
    "payout": 2.50,
    "payout_type": "cpa",
    "filter_bots": true,
    "status": "active",
    "metadata": {
      "vertical": "health",
      "geo": "US"
    },
    "excluded_days_of_week": [],
    "day_parting_enabled": false,
    "day_parting": {},
    "created_at": "2025-11-01T14:30:00",
    "updated_at": "2025-11-01T14:30:00"
  }
}

{
  "error": "name is required",
  "code": "missing_name"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

Creates a new offer on your account. At minimum, a name and tracking_url are required. You can optionally link the offer to an external affiliate platform such as TUNE or Everflow.

Body Parameters

string

required

Display name for the offer. Maximum 255 characters.

string

required

The tracking/click URL for this offer. Must be a valid URL.

string

External affiliate platform integration. Accepted values: tune, everflow, or null.

string

The offer ID on the external platform. Useful for syncing data with TUNE or Everflow.

string

Advertiser ID associated with the offer.

float

default:"0"

Payout amount for the offer.

string

default:"cpa"

Payout model. Accepted values: cpa (cost per action) or cpc (cost per click).

boolean

default:"false"

Whether to enable bot click filtering for this offer. When enabled, suspected bot clicks are flagged and excluded from reporting.

string

default:"active"

Initial status of the offer. Accepted values: active or paused.

object

Custom key-value pairs for storing additional information about the offer. Stored as-is; no type validation is enforced on keys or values, so nested objects, numbers, and booleans are accepted.

array

Weekday names (lowercase monday through sunday) on which the SMS ad server will not send this offer, evaluated in the contact’s local time. Duplicates are removed and the list is normalized to weekday order.

boolean

default:"false"

Whether intra-day send-window restrictions apply. When true, day_parting must be non-empty or the request is rejected with invalid_day_parting.

object

Allow-list of send windows keyed by lowercase weekday, evaluated in Eastern Time. Shape: {"monday": [{"start": "HH:MM", "end": "HH:MM"}]}. Times are 24-hour zero-padded; start must be before end (no overnight crossing); maximum 6 ranges per day. Omit a weekday to block sending on that day.

Response Fields

boolean

Indicates whether the offer was created successfully.

object

The full offer object. See List Offers for the complete field reference.

Examples

cURL

curl -X POST "https://api.tracklysms.com/api/v2/offers" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Promo",
    "tracking_url": "https://track.example.com/click?offer_id=123",
    "external_platform": "tune",
    "external_id": "4521",
    "advertiser_id": "adv_882",
    "payout": 2.50,
    "payout_type": "cpa",
    "filter_bots": true,
    "metadata": {
      "vertical": "health",
      "geo": "US"
    }
  }'

Python

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/offers",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "name": "Summer Promo",
        "tracking_url": "https://track.example.com/click?offer_id=123",
        "external_platform": "tune",
        "external_id": "4521",
        "advertiser_id": "adv_882",
        "payout": 2.50,
        "payout_type": "cpa",
        "filter_bots": True,
        "metadata": {
            "vertical": "health",
            "geo": "US"
        }
    }
)

data = response.json()
print(data["offer"]["id"])

Node.js

const response = await fetch("https://api.tracklysms.com/api/v2/offers", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "Summer Promo",
    tracking_url: "https://track.example.com/click?offer_id=123",
    external_platform: "tune",
    external_id: "4521",
    advertiser_id: "adv_882",
    payout: 2.50,
    payout_type: "cpa",
    filter_bots: true,
    metadata: {
      vertical: "health",
      geo: "US"
    }
  })
});

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

{
  "success": true,
  "offer": {
    "id": "664f1a2b3c4d5e6f7a8b9c0d",
    "slug": "ofr_summer-promo_a1b2c3",
    "name": "Summer Promo",
    "tracking_url": "https://track.example.com/click?offer_id=123",
    "external_platform": "tune",
    "external_id": "4521",
    "advertiser_id": "adv_882",
    "advertiser_name": null,
    "payout": 2.50,
    "payout_type": "cpa",
    "filter_bots": true,
    "status": "active",
    "metadata": {
      "vertical": "health",
      "geo": "US"
    },
    "excluded_days_of_week": [],
    "day_parting_enabled": false,
    "day_parting": {},
    "created_at": "2025-11-01T14:30:00",
    "updated_at": "2025-11-01T14:30:00"
  }
}

{
  "error": "name is required",
  "code": "missing_name"
}

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

Error Codes

HTTP Status	Error Code	Description
400	`missing_name`	The `name` field was not provided.
400	`missing_tracking_url`	The `tracking_url` field was not provided.
400	`name_too_long`	The `name` exceeds 255 characters.
400	`invalid_external_platform`	The `external_platform` value is not `tune`, `everflow`, or `null`.
400	`invalid_payout_type`	The `payout_type` value is not `cpa` or `cpc`.
400	`invalid_status`	The `status` value is not `active` or `paused`.
400	`invalid_excluded_days`	`excluded_days_of_week` is not a list or contains a non-weekday value.
400	`invalid_day_parting`	`day_parting` is malformed, or `day_parting_enabled` is `true` with an empty `day_parting`.
401	`invalid_credentials`	API key is missing or invalid.
403	`account_suspended`	Your account is suspended. Resolve outstanding billing or contact support.
429	`rate_limited`	Request throttled; retry with exponential backoff after the window resets.
500	`server_error`	An unexpected error occurred on the server.

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)

Body Parameters

Response Fields

Examples

Error Codes

Next Steps

Offers Overview

Record Revenue

​Body Parameters

​Response Fields

​Examples

​Error Codes

​Next Steps

Offers Overview

Record Revenue

Body Parameters

Response Fields

Examples

Error Codes

Next Steps