ClickMagick API (1.0)

Download OpenAPI specification:Download

URL: https://www.clickmagick.com/ License: Apache 2.0 Terms of Service

This API allows you to automate certain operations, such as managing Projects, Smart Links, Rotators, and retrieving stats.

These endpoints require the use of an API key, issued by ClickMagick. An API key can be read-only. A read-only key can use every endpoint that reads data, including the stats endpoints. A request that would create, change or delete something returns the error eReadOnlyKey.

For AI assistants and API tools, the full OpenAPI spec is at https://api.clickmagick.com/docs/openapi.yaml, and getting-started notes are at https://api.clickmagick.com/llms.txt.

Authentication

apikey

The API key issued to you by ClickMagick. A read-only key can't create, change or delete anything; those requests return eReadOnlyKey.

Security Scheme Type	API Key
Header parameter name:	x-apikey

Projects

A Project allows you to track all your traffic and conversions for a single website, store, or sales funnel - no matter how many landing pages, ads or traffic sources you have.

Get a list of Projects and their IDs

Get a list of Projects and their IDs.

Authorizations:

apikey

query Parameters

string <string>

Only include Projects where their name includes this string. Upper and lower case are ignored during the search. You can use letters, numbers, underscores, periods, dashes, and spaces.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects"

Response samples

Content type

application/json

{"projects": [{"id": 29583,
"name": "Bigfoot Surfboards",
"over_plan_limit": false
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a New Project

Create a new Project.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

name required	string The unique "friendly name" for this project. You can use letters, numbers, underscores, periods, dashes, and spaces.
time_zone	string Default: "The `time_zone` in your User Settings." The time zone for the Project specified using the named format in the IANA Time Zone Database, such as `America/New_York` and `Australia/Sydney`. You can find a list of the time zone names in this article: IANA Time Zone Database
currency	string 3 characters Default: "The currency setting in User Settings" If you're using the Auto Cost feature to pull in cost data from your Ad Account (Google, Facebook, etc.), and your ad account is sending cost data to ClickMagick in one currency, but all of your sales are being reported to ClickMagick in a different currency, then ClickMagick needs to convert your Auto Cost data from the currency that it's being reported in to the same currency that your sales are being reported in. The `currency` setting tells ClickMagick what currency your sales are being reported in so that it can convert Auto Cost data to match your sales data. The value of `currency` is the standard 3-letter International Bank Account Number (IBAN): `USD` for US dollars, `AUD` for Australian dollars, `EUR` for Euros, and so on. You can find a complete of International Bank Account Numbers at IBAN Currency Codes. ClickMagick only supports the most common currencies at this point. If you need a currency that is not currently supported, submit a ticket and we will add it.
project_domain	string Default: "not set" If set, only clicks and conversions from this domain will be processed. This is generally only set if somebody has copied your web page, along with your tracking code and is unknowingly sending tracking information to your Project. Do not include the protocol (`https://`), just pass a domain like `example.com` or `www.example.com`. You would normally leave this unset.
use_cogs	boolean Default: false Set to `true` if Cost Of Goods Sold (COGS) values should be used in computing stats for this Project.
attribution_window	integer >= 1 Default: "forever" Normally, conversions are tracked forever and attributed to the appropriate click for the visitor. In some cases, however, you may want to ignore conversions that happen after a certain number of days because they don’t relate to your current ad campaign. In that case, you would set `attribution_window` to the number of days you would like conversions to be recorded, and ignored after that.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects" -d "name=example.com"

Response samples

Content type

application/json

{"id": 29583,
"errors": [ ],
"status": "OK",
"warnings": [ ]
}

Get the settings for one or more Projects

Get the settings for one or more Projects by ID.

Authorizations:

apikey

query Parameters

required

integer <int32> >= 0

To get the settings for one or more Projects, pass in a single id value, or multiple id values.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/settings?id=29583&id=29584"

Response samples

Content type

application/json

{"projects": [{"created": "2026-10-16T22:55:40Z",
"currency": "AUD",
"id": 29583,
"name": "Bigfoot Surfboards",
"project_domain": "surf.example.com",
"time_zone": "Australia/Sydney",
"use_cogs": true,
"include_cogs_refunds": false
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Get the UTM values used with a Project

Get the UTM values used in clicks to a Project.

Authorizations:

apikey

query Parameters

id required	integer <int32> >= 0 The ID of the Project.
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the project utms. Must be used in conjunction with `end_time`. If a time range is specified, only UTM values used in that time range will be returned.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the project utms. Must be used in conjunction with `start_time`.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/utms?id=29583&start_time=2026-11-11T13:48:28Z&end_time=2026-11-12T22:41:16Z"

Response samples

Content type

application/json

{"utm": {"source": ["google",
"facebook"
],
"medium": ["cpc"
],
"campaign": ["spring-sale",
"summer-sale"
],
"term": [ ],
"content": [ ]
},
"status": "OK"
}

Delete a Project

Permanently delete a Project and all of its associated clicks, actions, engagements, and sales.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Edit the settings of a Project

Edit the settings of a Project.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 0

The ID of the project to update.

Request Body schema: application/x-www-form-urlencoded

time_zone	string The time zone for the project specified using the named format in the IANA Time Zone Database, such as `America/New_York` and `Australia/Sydney`. You can find a list of the time zone names in this article: IANA Time Zone Database
currency	string 3 characters If you're using the Auto Cost feature to pull in cost data from your Ad Account (Google, Facebook, etc.), and your ad account is sending cost data to ClickMagick in one currency, but all of your sales are being reported to ClickMagick in a different currency, then ClickMagick needs to convert your Auto Cost data from the currency that it's being reported in to the same currency that your sales are being reported in. The `currency` setting tells ClickMagick what currency your sales are being reported in so that it can convert Auto Cost data to match your sales data. The value of `currency` is the standard 3-letter International Bank Account Number (IBAN): `USD` for US dollars, `AUD` for Australian dollars, `EUR` for Euros, and so on. You can find a complete of International Bank Account Numbers at IBAN Currency Codes. ClickMagick only supports the most common currencies at this point. If you need a currency that is not currently supported, submit a ticket and we will add it.
project_domain	string If set, only clicks and conversions from this domain will be processed. This is generally only set if somebody has copied your web page, along with your tracking code and is unknowingly sending tracking information to your project. Do not include the protocol (`https://`), just pass a domain like `example.com` or `www.example.com`. You would normally leave this unset. To unset `project_domain` if it already has a value, set it to nothing, e.g., `project_domain=`.
use_cogs	boolean Set to `true` if Cost Of Goods Sold (COGS) values should be used in computing stats for this project.
attribution_window	integer >= 1 Normally, conversions are tracked forever and attributed to the appropriate click for the visitor. In some cases, however, you may want to ignore conversions that happen after a certain number of days because they don’t relate to your current ad campaign. In that case, you would set `attribution_window` to the number of days you would like conversions to be recorded, and ignored after that. To reset `attribution_window` to "forever" if it already has a value, set it to nothing, e.g., `attribution_window=`.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583" -d "time_zone=Australia/Sydney"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a stats report for a Project

Create a stats report for a Project using the 'last_click' attribution model.

To use other attribution models, see Create a stats report for a Project using a specific model.

The stats always include every sale type, new and repeat customers, every cmc_ref and organic traffic. The app's Filter Sales and Exclude Organic options don't apply, so a page that has them on can show different numbers.

This call returns a report id and url; poll that url with GET /campaigns/projects/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

Request Body schema: application/x-www-form-urlencoded

A request to generate a campaign project stats report.

start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also ISO-8601 in Wikipedia.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also ISO-8601 in Wikipedia.
utm_source	string Only match results with this utm_source value.
utm_medium	string Only match results with this utm_medium value.
utm_campaign	string Only match results with this utm_campaign value.
utm_term	string Only match results with this utm_term value.
utm_content	string Only match results with this utm_content value.
refresh	boolean Default: false Whether to regenerate the report from scratch. Stats reports are cached, and the web app shows the same ones. A report whose range includes the last 24 hours is cached for 5 to 20 minutes: the longer it took to generate, the longer it's kept. A report for an older range is cached for up to 3 days. The report's `last_updated` says when it was generated. Any date range that includes "today" is constantly changing as clicks come in throughout the day so stats must be continually recomputed. By default, cached reports are always returned to minimize the amount of recomputing required and stats are computed fresh only if they are not in the cache. With `refresh=true`, a cached report that has finished is replaced by a new report with a new `id`. A report that finished less than 5 minutes ago is not replaced: you get it back with the warning `refresh ignored: this report was generated less than 5 minutes ago.` A report that is still being generated is never replaced: you get its `id` back. A report that failed to generate is always replaced. Without `refresh=true`, requesting or polling it gets the error `This report failed to generate. Try a shorter date range, or create it again with refresh=true.`
group_by	string Enum: "utm_source" "utm_medium" "utm_campaign" "utm_term" "utm_content" "day" "country" "device" "hour" "weekday" "month" Break the stats down into one row per value of this field, instead of one set of totals. To compare UTM values, days, months, countries, devices or times, use this instead of one request per value. `day`, `hour`, `weekday` and `month` are in the project's time zone. `month` is the calendar month, such as `2026-10`. `device` is `Desktop`, `Mobile` or `Tablet` (or the stored device code for anything else). `country` is the ISO country code. A breakdown covers whole days in the project's time zone. A range from midnight to midnight ends on the day before, and a `start_time` or `end_time` that isn't at the start or end of a day gets a warning saying which days were used. Without `start_time` and `end_time`, it covers your account's data window. `day` is always last-click: any other attribution model gets an error. `day`, `hour`, `weekday` and `month` put each stat at the time it happened: a sale at the time of the sale, not of the click it's attributed to. So an hour's rates, such as `roas`, `epc` and `scr`, compare the sales made in that hour with the clicks made in it, not with the sales those clicks led to. For when conversions come in, use the counts and revenue. Grouping by a UTM field ignores a filter on that same field. Filters on the other UTM fields still apply, so `group_by=utm_campaign` with `utm_source=facebook` gives the campaigns within Facebook traffic. Each UTM filter can be at most 100 characters. Values with no data, such as an empty UTM, country or device, are left out. A breakdown has no totals, and its rows don't always add up to the totals: they leave out data with no value for the field, and a visitor in more than one group counts in each group's actions, engagements and customers. A totals request with exact times can also differ slightly. Adding up the rows' counts and amounts gives the app's totals row; work out rates such as `aov`, `roas` and `acr` from those sums instead of adding them. For the project's totals, send the same request without `group_by`. Breakdowns have their own limits on unfinished reports, separate from totals: up to 3 each for UTM fields, for `day`, and for `country`, `device`, `hour`, `weekday` and `month` together. The `report.url` you get back carries `group_by` and any `sort_by`, `sort_direction` and `limit` you sent. Poll it exactly as given.
sort_by	string Only with `group_by`. Sort the rows by `group` or by any numeric field of `stats` (any field except `currency`, `currency_symbol` and `project_id`). Default: `revenue` for UTM fields, `country` and `device`; `group` for `day`, `month`, `hour` and `weekday`. Sorting by `group` puts days and months in date order, hours in numeric order, weekdays Sunday through Saturday, and other values in alphabetical order. Ties are broken by `group`, and missing values sort last in either direction.
sort_direction	string Enum: "asc" "desc" Only with `group_by`. Default: `desc`, except `asc` for `hour` and `weekday`. So days and months are newest first.
limit	integer <int32> [ 1 .. 1000 ] Default: 100 Only with `group_by`. The most rows to return. `total_rows` in the report says how many there are.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/stats" -d "utm_source=google"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Create a stats report for a Project using a specific model

Create a stats report for a Project using a specific attribution model.

This call returns a report id and url; poll that url with GET /campaigns/projects/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

On linear, pos_based and time_decay, every click before a conversion gets credit for it, and a sale's amount is split between those clicks. Conversion lists have one row per credited click, and the stats count each credited click as a sale. So sales, aov and cps can't be compared with last_click or first_click; revenue, customers, actions and engagements can.

Request Body schema: application/x-www-form-urlencoded

A request to generate a campaign project stats report.

start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also ISO-8601 in Wikipedia.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also ISO-8601 in Wikipedia.
utm_source	string Only match results with this utm_source value.
utm_medium	string Only match results with this utm_medium value.
utm_campaign	string Only match results with this utm_campaign value.
utm_term	string Only match results with this utm_term value.
utm_content	string Only match results with this utm_content value.
refresh	boolean Default: false Whether to regenerate the report from scratch. Stats reports are cached, and the web app shows the same ones. A report whose range includes the last 24 hours is cached for 5 to 20 minutes: the longer it took to generate, the longer it's kept. A report for an older range is cached for up to 3 days. The report's `last_updated` says when it was generated. Any date range that includes "today" is constantly changing as clicks come in throughout the day so stats must be continually recomputed. By default, cached reports are always returned to minimize the amount of recomputing required and stats are computed fresh only if they are not in the cache. With `refresh=true`, a cached report that has finished is replaced by a new report with a new `id`. A report that finished less than 5 minutes ago is not replaced: you get it back with the warning `refresh ignored: this report was generated less than 5 minutes ago.` A report that is still being generated is never replaced: you get its `id` back. A report that failed to generate is always replaced. Without `refresh=true`, requesting or polling it gets the error `This report failed to generate. Try a shorter date range, or create it again with refresh=true.`
group_by	string Enum: "utm_source" "utm_medium" "utm_campaign" "utm_term" "utm_content" "day" "country" "device" "hour" "weekday" "month" Break the stats down into one row per value of this field, instead of one set of totals. To compare UTM values, days, months, countries, devices or times, use this instead of one request per value. `day`, `hour`, `weekday` and `month` are in the project's time zone. `month` is the calendar month, such as `2026-10`. `device` is `Desktop`, `Mobile` or `Tablet` (or the stored device code for anything else). `country` is the ISO country code. A breakdown covers whole days in the project's time zone. A range from midnight to midnight ends on the day before, and a `start_time` or `end_time` that isn't at the start or end of a day gets a warning saying which days were used. Without `start_time` and `end_time`, it covers your account's data window. `day` is always last-click: any other attribution model gets an error. `day`, `hour`, `weekday` and `month` put each stat at the time it happened: a sale at the time of the sale, not of the click it's attributed to. So an hour's rates, such as `roas`, `epc` and `scr`, compare the sales made in that hour with the clicks made in it, not with the sales those clicks led to. For when conversions come in, use the counts and revenue. Grouping by a UTM field ignores a filter on that same field. Filters on the other UTM fields still apply, so `group_by=utm_campaign` with `utm_source=facebook` gives the campaigns within Facebook traffic. Each UTM filter can be at most 100 characters. Values with no data, such as an empty UTM, country or device, are left out. A breakdown has no totals, and its rows don't always add up to the totals: they leave out data with no value for the field, and a visitor in more than one group counts in each group's actions, engagements and customers. A totals request with exact times can also differ slightly. Adding up the rows' counts and amounts gives the app's totals row; work out rates such as `aov`, `roas` and `acr` from those sums instead of adding them. For the project's totals, send the same request without `group_by`. Breakdowns have their own limits on unfinished reports, separate from totals: up to 3 each for UTM fields, for `day`, and for `country`, `device`, `hour`, `weekday` and `month` together. The `report.url` you get back carries `group_by` and any `sort_by`, `sort_direction` and `limit` you sent. Poll it exactly as given.
sort_by	string Only with `group_by`. Sort the rows by `group` or by any numeric field of `stats` (any field except `currency`, `currency_symbol` and `project_id`). Default: `revenue` for UTM fields, `country` and `device`; `group` for `day`, `month`, `hour` and `weekday`. Sorting by `group` puts days and months in date order, hours in numeric order, weekdays Sunday through Saturday, and other values in alphabetical order. Ties are broken by `group`, and missing values sort last in either direction.
sort_direction	string Enum: "asc" "desc" Only with `group_by`. Default: `desc`, except `asc` for `hour` and `weekday`. So days and months are newest first.
limit	integer <int32> [ 1 .. 1000 ] Default: 100 Only with `group_by`. The most rows to return. `total_rows` in the report says how many there are.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/stats/linear" -d "utm_source=google"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Retrieve a stats report

Retrieve a stats report once it has been generated.

If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Once the report has been generated, a 200 status will be returned, along with the data of the report.

Always poll the report.url from the create response, exactly as given. A breakdown's url carries its group_by, and its id can match the id of another report, so a poll without the url's parameters gets the wrong report or an error.

A finished report whose date range includes today is deleted 5 to 20 minutes after it finishes. Polling it after that gets a missing-report error: create it again.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

query Parameters

group_by	string Enum: "utm_source" "utm_medium" "utm_campaign" "utm_term" "utm_content" "day" "country" "device" "hour" "weekday" "month" For a breakdown: the `group_by` it was created with, as given in `report.url`.
sort_by	string Only with `group_by`. How to sort the rows: `group` or any numeric field of `stats`. See the create request.
sort_direction	string Enum: "asc" "desc" Only with `group_by`. `asc` or `desc`. See the create request.
limit	integer <int32> [ 1 .. 1000 ] Default: 100 Only with `group_by`. The most rows to return.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/stats/reports/3752921"

Response samples

Content type

application/json

Example

{"last_updated": "2026-11-12T22:41:16Z",
"progress": {"completed": true,
"percentage_completed": 100
},
"stats": {"acr": 69.7,
"actions": 3374,
"ad_cost": 6498,
"ad_spend": 7098,
"aov": 62.11,
"cac": 35.49,
"cogs": 600,
"cost": 7098,
"cpa": 1.93,
"cpc": 1.34,
"cpe": 2.67,
"cps": 7.39,
"currency_symbol": "£",
"customers": 243,
"customers_new": 200,
"customers_repeat": 43,
"ecr": 50.2,
"engagements": 2432,
"epa": 19.89,
"epc": 13.86,
"epe": 27.6,
"ltv": 335.56,
"profit": 59902,
"project_id": 29583,
"refunds": 111.02,
"refunds_cogs": 91.02,
"revenue": 67111.02,
"revenue_backend": 7383.98,
"revenue_initial": 9931.75,
"revenue_recurring": 7483.56,
"revenue_upsells": 5854.61,
"roas": 10.33,
"roas_24h": 2.74,
"roi": 844,
"sales": 960,
"scr": 4.1,
"unique_clicks": 4843
},
"status": "OK",
"total_seconds": 39
}

Get a Project's Lifetime Value report

Get a Project's Lifetime Value report: how much new customers go on to spend after their first purchase, as the Lifetime Value page in ClickMagick shows it.

Customers are grouped into cohorts by when their first purchase was, one cohort for each week, month or quarter in the date range. Each cohort has its new customers, its customer acquisition cost (CAC), the average first sale, and the cumulative revenue per customer by the end of each period since. Revenue is only followed through the end date, so to see what a cohort is worth N periods after it starts, the end date must be at least N periods later. Compare a cohort's cumulative revenue per customer with its CAC to see when it paid back what its customers cost to acquire. Unlike the ltv stat in a stats report, which divides all the revenue in a date range by the new customers in it, these numbers follow each group of new customers over time.

The report uses the last_click attribution model. Refunded sales are left out, so a customer whose first purchase was refunded isn't counted. With a UTM filter, only first purchases with those UTM values make customers, and only their later purchases with those values count.

Weeks are 7 days from the start date. Months end on the last day of a month, and quarters are three months counted from the start date's month, not calendar quarters. The first cohort starts on the start date and the last ends on the end date, so either can be a partial period. The report covers whole days in the project's time zone. Without start_time and end_time, it covers the last 6 months (2 for weeks) from the 1st of a month, through today. A range can have at most 26 periods, in the years 2000 through 2099 in the project's time zone.

This is a slow report. An account can run only one slow report at a time, so a request sent while another is still running gets HTTP status 429: wait the number of seconds in Retry-After and try again.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

query Parameters

period	string Default: "month" Enum: "week" "month" "quarter" The length of each cohort's period.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/lifetime-value?period=month"

Response samples

Content type

application/json

{"status": "OK",
"currency": "USD",
"period": "month",
"time_zone": "America/Chicago",
"start_date": "2026-01-01",
"end_date": "2026-03-31",
"cohorts": [{"start_date": "2026-01-01",
"end_date": "2026-01-31",
"new_customers": 40,
"cac": 35.5,
"avg_first_sale": 47,
"cumulative_revenue_per_customer": [52.25,
61.8,
66.1
]
},
{"start_date": "2026-02-01",
"end_date": "2026-02-28",
"new_customers": 32,
"cac": 41.2,
"avg_first_sale": 45.5,
"cumulative_revenue_per_customer": [49,
57.4
]
},
{"start_date": "2026-03-01",
"end_date": "2026-03-31",
"new_customers": 0,
"cac": null,
"avg_first_sale": null,
"cumulative_revenue_per_customer": [null
]
}
]
}

Get a Project's Conversion Velocity report

Get a Project's Conversion Velocity report: how long visitors take to convert after their first click, as the Conversion Velocity page in ClickMagick shows it.

Each visitor's first sale (or first action, or first engagement, with type) is counted once, in a bucket for how long after their first click it came. scale picks the buckets: day runs from 1 hour to more than 24 hours, week from 1 day to more than 7 days, month from 1-4 days to more than 31 days, and year from 1 day to more than 180 days. Each bucket includes its upper limit, so a sale exactly 1 hour after the first click is in the 1 hour bucket. Visitors who never converted aren't in the report, so it can't give a conversion rate: a project stats report has those. It has no average: for the typical time, use the first bucket whose cumulative_percent reaches 50.

The date range picks visitors by the day of their first click, not the day they converted, and the UTM filters match their first click's UTM values. Visitors whose first click was recent have had less time to convert, so a range that ends recently has fewer slow conversions than it will later: for the full picture, end the range at least as long ago as the slowest bucket that matters (180 days ago for year). The report covers whole days in the project's time zone. Without start_time and end_time, it covers the last 30 days, through today. Dates must be in the years 2000 through 2099 in the project's time zone.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

query Parameters

type	string Default: "sales" Enum: "sales" "actions" "engagements" Which conversions to count.
scale	string Default: "year" Enum: "day" "week" "month" "year" Which buckets to count them in: `day` for hours up to 24, `week` for days up to 7, `month` for up to 31 days, and `year` for up to 180 days.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/conversion-velocity?type=sales&scale=week"

Response samples

Content type

application/json

{"status": "OK",
"type": "sales",
"scale": "week",
"time_zone": "America/Chicago",
"start_date": "2026-10-01",
"end_date": "2026-10-31",
"conversions": 200,
"buckets": [{"label": "1 Day",
"up_to_seconds": 86400,
"conversions": 120,
"percent": 60,
"cumulative_percent": 60
},
{"label": "2 Days",
"up_to_seconds": 172800,
"conversions": 30,
"percent": 15,
"cumulative_percent": 75
},
{"label": "3 Days",
"up_to_seconds": 259200,
"conversions": 14,
"percent": 7,
"cumulative_percent": 82
},
{"label": "4 Days",
"up_to_seconds": 345600,
"conversions": 8,
"percent": 4,
"cumulative_percent": 86
},
{"label": "5 Days",
"up_to_seconds": 432000,
"conversions": 5,
"percent": 2.5,
"cumulative_percent": 88.5
},
{"label": "6 Days",
"up_to_seconds": 518400,
"conversions": 4,
"percent": 2,
"cumulative_percent": 90.5
},
{"label": "7 Days",
"up_to_seconds": 604800,
"conversions": 3,
"percent": 1.5,
"cumulative_percent": 92
},
{"label": ">7 Days",
"up_to_seconds": null,
"conversions": 16,
"percent": 8,
"cumulative_percent": 100
}
]
}

Get a Visitor Profile

Returns a single visitor's identity profile plus a unified, time-sorted log of their clicks and conversions — the same information shown by the Visitor Profile tool in the ClickMagick app.

Look a visitor up by their Visitor ID (e.g. cmc1234567890) or by their email address, using the search parameter.

The events log is returned oldest-first (chronological order) by default and is paged like the other log endpoints. The visitor summary — including total_orders and lifetime_value — is computed over the visitor's entire history and is returned on every page.

Authorizations:

apikey

query Parameters

search required	string Example: search=cmc1234567890 A Visitor ID (e.g. `cmc1234567890`) or an email address (e.g. `john.doe@example.com`) to look up. A Visitor ID that was merged into another visitor gets that visitor's profile, as in the app.
cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "asc" Enum: "asc" "desc" The order of the `events` log by timestamp. Defaults to `asc` (oldest first, chronological).

Responses

Request samples

By Visitor ID
By email address

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/visitor-profile?search=cmc1234567890"

Response samples

Content type

application/json

{"status": "OK",
"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"visitor": {"visitor_id": "cmc2516938438",
"merged_visitor_ids": [ ],
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "111-222-4444",
"mobile": null,
"location": {"city": "Chicago",
"region": "Illinois",
"country": "US"
},
"total_orders": 3,
"lifetime_value": 292.56,
"currency": "USD"
},
"events": [{"type": "sale",
"click_type": null,
"cmc_project": "Bigfoot Surfboards",
"project_id": 29583,
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "end+of+season",
"utm_term": "",
"utm_content": "",
"cmc_ref": "purchase",
"cmc_amt": 97.52,
"currency": "USD",
"device": "desktop",
"ip": "192.0.2.1",
"country": "US",
"shopify_order_id": "#1001",
"sale_type": "initial",
"timestamp": "2026-11-12T22:41:16Z"
},
{"type": "click",
"click_type": "unique",
"cmc_project": "Bigfoot Surfboards",
"project_id": 29583,
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "end+of+season",
"utm_term": "",
"utm_content": "",
"cmc_ref": "",
"cmc_amt": null,
"currency": null,
"device": "mobile",
"ip": "192.0.2.1",
"country": "US",
"shopify_order_id": null,
"sale_type": null,
"timestamp": "2026-11-11T13:48:28Z"
}
]
}

Get URLs built using the URL Builder

Get a list of the UTM-powered URLs that were built using the URL Builder.

Authorizations:

apikey

query Parameters

limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
cursor	string <string> Pass in the previous page's cursor `next` or `prev` response value to retrieve the next page or previous page of data. This allows you to move through the data either forward or backwards. Send it with the same other parameters as the request it came from.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/urls"

Response samples

Content type

application/json

{"urls": [{"notes": null,
"url": "https://example.com?utm_source=facebook&utm_medium=social&utm_campaign=xbox"
}
],
"cursor": {"next": "ZBDkPOxCKRi",
"prev": "ODM3MjYyMTE"
},
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Project Logs

These are the action, engagement, and sales conversion logs for your Projects.

Get Actions for all Projects

Get actions for all projects using the last_click attribution model.

To use other attribution models, see Get actions for all projects using a specific model.

Actions are listed newest first, by the time of the action. An action recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

Authorizations:

apikey

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/actions?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"actions": [{"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 3956114,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Actions for all Projects using a specific model

Get actions for all Projects using a specific attribution model.

Actions are listed newest first, by the time of the action. An action recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

Authorizations:

apikey

path Parameters

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/actions/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"actions": [{"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 3956114,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Actions for a Project

Get actions for a specific Project using the last_click attribution model.

To use other attribution models, see Get actions for a Project using a specific model.

Actions are listed newest first, by the time of the action. An action recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/actions?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"actions": [{"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 3956114,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Actions for a Project using a specific model

Get actions for a specific Project using a specific attribution model.

Actions are listed newest first, by the time of the action. An action recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/actions/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"actions": [{"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 3956114,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Engagements for all Projects

Get engagements for all Projects using the last_click attribution model.

To use other attribution models, see Get engagements for all Projects using a specific model.

Engagements are listed newest first, by the time of the engagement. An engagement recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

Authorizations:

apikey

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/engagements?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "checkoutpage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 809274,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Engagements for all Projects using a specific model

Get engagements for all Projects using a specific attribution model.

Authorizations:

apikey

path Parameters

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/engagements/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "checkoutpage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 809274,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Engagements for a Project

Get engagements for a specific Project using the last_click attribution model.

To use other attribution models, see Get engagements for a Project using a specific model.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/engagements?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "checkoutpage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 809274,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Engagements for a Project using a specific model

Get engagements for a specific Project using a specific attribution model.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/engagements/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "checkoutpage",
"cmc_tid": null,
"country": "US",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 809274,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Sales for all Projects

Get sales for all Projects using the last_click attribution model.

Sales are listed newest first, by the time of the sale, and include refunded sales. A sale recorded later with an earlier time, such as an Offline Conversions import, is listed at its own time, not as the newest.

To use other attribution models, see Get sales for all Projects using a specific model.

Authorizations:

apikey

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/sales?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"currency": "USD",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 910176,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"refunded": null,
"sale_type": "initial",
"shopify_order_id": "#000-10",
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Sales for all Projects using a specific model

Get sales for all Projects using a specific attribution model.

Authorizations:

apikey

path Parameters

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/sales/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"currency": "USD",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 910176,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"refunded": null,
"sale_type": "initial",
"shopify_order_id": "#000-10",
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get Sales for a Project

Get sales for a specific Project using the last_click attribution model.

To use other attribution models, see Get sales for a Project using a specific model.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/sales?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"currency": "USD",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 910176,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"refunded": null,
"sale_type": "initial",
"shopify_order_id": "#000-10",
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Get sales for a Project using a specific model

Get sales for a specific Project using a specific attribution model.

Authorizations:

apikey

path Parameters

project_id

required

integer <int32> >= 1

Example: 29583

The project id for this request.

attribution_model

required

string (AttributionModel)

Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

How credit for conversions is shared across a visitor's clicks.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
sort_direction	string Default: "desc" Enum: "asc" "desc" The order by time: `desc` for newest first, `asc` for oldest first.
start_time	string <date-time> Example: start_time=2026-11-11T13:48:28Z The ISO-8601 timestamp for the starting date and time of the time range for the request. Must be used in conjunction with `end_time`. See also ISO-8601 in Wikipedia.
end_time	string <date-time> Example: end_time=2026-11-12T22:41:16Z The ISO-8601 timestamp for the ending date and time of the time range for the request. Must be used in conjunction with `start_time`. See also ISO-8601 in Wikipedia.
utm_source	string Example: utm_source=google Only match results with this utm_source value.
utm_medium	string Example: utm_medium=cpc Only match results with this utm_medium value.
utm_campaign	string Example: utm_campaign=end+of+season Only match results with this utm_campaign value.
utm_term	string Example: utm_term=Hang+Ten Only match results with this utm_term value.
utm_content	string Example: utm_content=best+surfboard Only match results with this utm_content value.
country	string^[A-Za-z]{2}$ Only include conversions from this country, as a two-letter code such as `US`.
device	string Enum: "desktop" "mobile" "tablet" Only include conversions on this device.
hour	integer [ 0 .. 23 ] Only include conversions in this hour of the day, 0 to 23, in the Project's time zone. Only on the endpoints for one Project.
weekday	string Enum: "Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" "Saturday" Only include conversions on this day of the week, in the Project's time zone. Only on the endpoints for one Project.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/sales/linear?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"sales": [{"cmc_amt": 97.52,
"cmc_project": "Bigfoot Surfboards",
"cmc_ref": "salespage",
"cmc_tid": null,
"country": "US",
"currency": "USD",
"device": "desktop",
"fbclid": null,
"gclid": null,
"id": 910176,
"ip": "192.0.2.1",
"msclkid": null,
"project_id": 29583,
"refunded": null,
"sale_type": "initial",
"shopify_order_id": "#000-10",
"timestamp": "2026-11-12T22:41:16Z",
"utm_campaign": "end+of+season",
"utm_content": "best+surfboard",
"utm_medium": "cpc",
"utm_source": "google",
"utm_term": "Hang+Ten",
"visitor_id": "cmc2516938438"
}
],
"status": "OK"
}

Smart Links

Smart Links are like bitly links - but smarter.

Get a list of Smart Links and their IDs

Retrieve a list of your Smart Links and IDs.

For more information on Smart Links, please see the knowledgebase.

Authorizations:

apikey

query Parameters

cursor	string <string> Pass in the previous page's cursor `next` or `prev` response value to retrieve the next page or previous page of data. This allows you to move through the data either forward or backward. Send it with the same other parameters as the request it came from. If no `cursor` is specified, the first page of data is returned.
group_id	integer <int32> If you provide a top-level `group_id`, then only links in that top-level group are returned and none from any subgroups, unless a `subgroup_id` is passed in or `recursive` is `true`.
include_archived	boolean Default: false Include archived links in the results or not.
limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
recursive	boolean Default: false Return Smart Links for the group specified by `group_id` and all of the subgroups of that group.
subgroup_id	integer <int32> Return only the links in the subgroup specified by the `subgroup_id`. You must pass in the corresponding parent `group_id` if you pass in a `subgroup_id`.
search	string <string> Only include links where their `link_name` includes this string.
sort_direction	string <string> Default: "newest_first" Enum: "alpha" "newest_first" "oldest_first" Specify how links should be sorted: `alpha` for alphabetical order, `oldest_first` for ordering the oldest-created links first, and `newest_first` which orders the most recently created links first.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links?limit=1"

Response samples

Content type

application/json

{"cursor": {"next": "ZBDkPOxCKRi",
"prev": "ODM3MjYyMTE"
},
"errors": [ ],
"links": [{"archived": false,
"group_id": 18365,
"id": 1731254,
"link_name": "Callaway Golf Bags",
"link_slug": "golfbags",
"subgroup_id": 10435
}
],
"status": "OK",
"warnings": [ ]
}

Create a Smart Link

Create a new Smart Link.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

backup_url	string <= 2048 characters The URL that clicks will be redirected to if they can't be redirected to any other URL in the link settings. For example, if the `max_clicks` setting for this link has been reached, or you have geotargetting set up and the setting doesn't match the click.
blank_referrer	string Default: "false" Enum: "true" "false" Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from.
cost	number <float> Default: 0 The cost of your clicks, if known in advance. Must be greater than 0 if `cost_type` is set to anything other than `no_cost_type`.
cost_type	string Default: "no_cost_type" Enum: "no_cost_type" "one_time_cost" "cost_per_click" "daily" "monthly" The type of cost for this Smart Link.
domain_id	integer <int32> >= 0 Default: 0 If you have any custom tracking domains set up to use with your Smart Links, you can use any of those domains at any time with any of your Smart Links. This `domain_id` setting simply specifies your preferred domain for this particular Smart Link. This is useful in the UI, for example, when ClickMagick needs to copy a Smart Link to the clipboard. It will use this domain in the Smart Link rather than another domain that you might have set up.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this link, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
filter_abuser	string Default: "nothing" Enum: "block" "flag" "nothing" An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Smart Link 30 times in one minute or clicking 30 different Smart Links within one minute. Setting this to `flag` will send these clicks through to your Smart Link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks.
filter_anon	string Default: "nothing" Enum: "block" "flag" "nothing" An anonymous user is one who is using an anonymous proxy, Virtual Private Network, TOR, or similiar technologies to mask the IP address where their click is originating from. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_bot	string Default: "flag" Enum: "block" "flag" "nothing" A bot is any type of automated program or software that accesses your Smart Links or Rotators. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_server	string Default: "flag" Enum: "block" "flag" "nothing" This represents a "click" from a known web server or hosting company. The overwhelming majority of the time these are scripts used by scammers to generate fake clicks. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_spider	string Default: "flag" Enum: "block" "flag" "nothing" A "spider" is a piece of code that search engines use to index the web, following links in pages as they find them during the indexing process. These spider "clicks" are generally innocent, but they don't represent real clicks from real users and they mess up your stats. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_user	string Default: "flag" Enum: "block" "flag" "nothing" These are the clicks that come from the IPs or IP ranges that you have manually added via your IP Manager page. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this link, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
ios_url	string <= 2048 characters If the click is from an iOS device, clicks will be redirected to this URL instead of to the `primary_url`. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices.
link_group	integer <int32> >= 0 Default: 0 The ID of the group to organize this link under. If you specify `link_group`, you must also specify `link_subgroup`. If you don't want the link associated with any group, set `link_group` to 0, or don't specify it at all.
link_name	string [ 4 .. 32 ] characters The unique "friendly name" of this link. In the UI, if this is not specified, the `link_slug` is displayed instead. Link names cannot include these special characters: : & \| ; $ % @ " ' < > ( ) + , \
link_slug	string [ 4 .. 20 ] characters A unique identifier used as part of the Smart Link, e.g., `https://clkmg.com/<username>/<link_slug>`. If not set, a random slug like `1pk3wb` will be generated for you. Although not required, you'll generally want to set this to a human-readable value such as `golfbags`. Letters, numbers, and hyphens are allowed, but no spaces.
link_subgroup	integer <int32> >= 0 Default: 0 The ID of the subgroup to organize this link under. If you specify `link_subgroup`, you must also specify `link_group`. If you don't want the link in a subgroup, set `link_subgroup` to 0.
max_clicks	integer <int32> [ 1 .. 999999 ] If specified, this is the maximum number of clicks to redirect through the Smart Link. All additional clicks will then be redirected through the `backup_url`. If you set `max_clicks`, you must also set `backup_url`.
mobile_url	string <= 2048 characters The URL that clicks from mobile devices will be redirected to instead of to the `primary_url`. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`.
notes	string <= 1024 characters Notes that you would like to keep for this link.
password	string <= 20 characters Setting a password will display a generic login page that the user must enter the password to continue.
pixels	string <= 2560 characters The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags.
primary_url required	string <= 2048 characters The primary URL to deliver clicks to.
repeat_on_primary_url	string Default: "false" Enum: "true" "false" Redirect visitors to the `repeat_url` if the visitor has ever been redirected to the same `primary_url` even if it was from a different Smart Link.
repeat_url	string <= 2048 characters Repeat clicks from the same visitor will be redirected to this URL.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links" -d "primary_url=https://www.example.com/"

Response samples

Content type

application/json

{"errors": [ ],
"id": 1731254,
"public_stats_url": "https://www.clickmagick.com/share/002f6ed01a6ab6",
"status": "OK",
"warnings": [ ]
}

Get the settings for one or more Smart Links

Get the settings for one or more Smart Links by ID.

Authorizations:

apikey

query Parameters

required

integer <int32> >= 0

To get the settings of one or more Smart Links, pass in a single id value, or multiple id values.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/settings?id=1731254&id=1731255"

Response samples

Content type

application/json

{"links": [{"archived": false,
"backup_url": null,
"blank_referrers": false,
"cost": 0.54,
"cost_type": "cost_per_click",
"created": "2026-10-16T22:55:40Z",
"domain_id": 49735,
"exclude_countries": ["NG"
],
"filter_abuser": "nothing",
"filter_anon": "flag",
"filter_bot": "flag",
"filter_server": "flag",
"filter_spider": "flag",
"filter_user": "flag",
"has_split_urls": false,
"id": 1731254,
"include_countries": [ ],
"ios_url": null,
"last_click": "2026-10-16T23:55:40Z",
"last_reset": "2026-11-05T18:22:04Z",
"link_group": 27395,
"link_name": "Callaway Golf Bags",
"link_slug": "golfbags",
"link_subgroup": null,
"max_clicks": null,
"mobile_url": null,
"notes": null,
"password": null,
"pixels": null,
"primary_url": "https://example.com",
"public_stats_url": "https://www.clickmagick.com/share/002f6ed01a6ab6",
"repeat_primary_url": false,
"repeat_url": null,
"split_type": "epc"
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Smart Link

Permanently delete a Smart Link and all of its associated clicks.

Authorizations:

apikey

path Parameters

link_id

required

integer <int32> >= 0

The ID of the Link to delete.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/1731254"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Edit a Smart Link

Edit an existing Smart Link.

Authorizations:

apikey

path Parameters

link_id

required

integer <int32> >= 0

The ID of the Link to update.

Request Body schema: application/x-www-form-urlencoded

primary_url	string <= 2048 characters The primary URL to deliver clicks to. It cannot be cleared.
link_slug	string [ 4 .. 20 ] characters A unique identifier used as part of the Smart Link, e.g., `https://clkmg.com/<username>/<link_slug>`. Pass it empty, e.g., `link_slug=&...`, to replace the current slug with a random one like `1pk3wb`. We recommend using a human-readable value such as `golfbags`. Letters, numbers, and hyphens are allowed, but no spaces.
link_name	string [ 4 .. 32 ] characters The unique "friendly name" of this link. In the UI, if this is not specified, the `link_slug` is displayed instead. To unset this value, set it to nothing, e.g., `link_name=&...`. Link names cannot include these special characters: : & \| ; $ % @ " ' < > ( ) + , \
domain_id	integer <int32> >= 0 Default: 0 If you have any custom tracking domains set up to use with your Smart Links, you can use any of those domains at any time with any of your Smart Links. This `domain_id` setting simply specifies your preferred domain for this particular Smart Link. This is useful in the UI, for example, when ClickMagick needs to copy a Smart Link to the clipboard. It will use this domain in the Smart Link rather than another domain that you might have set up.
link_group	integer <int32> >= 0 Default: 0 The ID of the group to organize this link under. If you specify `link_group`, you must also specify `link_subgroup`. If you don't want the link associated with any group, set `link_group` to 0, or set it to nothing, e.g., `link_group=&...`.
link_subgroup	integer <int32> >= 0 Default: 0 The ID of the subgroup to organize this link under. If you specify `link_subgroup`, you must also specify `link_group`. If you don't want the link in a subgroup, set `link_subgroup` to 0, or set it to nothing, e.g., `link_subgroup=&...`.
archived	boolean Default: false Indicates if this link is archived. You can still send traffic to this link, but the link won't show up with other links in the UI unless you're viewing the "Archived Links" view.
pixels	string <= 2560 characters The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To unset this value, set it to nothing, e.g., `pixels=&...`.
cost	number <float> Default: 0 The cost of your clicks, if known in advance. Must be greater than 0 if `cost_type` is set to anything other than `no_cost_type`. To unset this value, set it to nothing, e.g., `cost=&...` and set `cost_type` to `no_cost_type`.
cost_type	string Enum: "no_cost_type" "one_time_cost" "cost_per_click" "daily" "monthly" The type of cost for this Smart Link. `cost` and `cost_type` must be sent together.
backup_url	string <= 2048 characters The URL that clicks will be redirected to if they can't be redirected to any other URL in the link settings. For example, if the `max_clicks` setting for this link has been reached, or you have geotargetting set up and the setting doesn't match the click. To unset this value, set it to nothing, e.g., `backup_url=&...`.
mobile_url	string <= 2048 characters The URL that clicks from mobile devices will be redirected to instead of to the `primary_url`. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`. To unset this value, set it to nothing, e.g., `mobile_url=&...`.
ios_url	string <= 2048 characters If the click is from an iOS device, clicks will be redirected to this URL instead of to the `primary_url`. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices. To unset this value, set it to nothing, e.g., `ios_url=&...`.
repeat_url	string <= 2048 characters Repeat clicks from the same visitor will be redirected to this URL. To unset this value, set it to nothing, e.g., `repeat_url=&...`.
repeat_on_primary_url	boolean Default: false Redirect visitors to the `repeat_url` if the visitor has ever been redirected to the same `primary_url` even if it was from a different Smart Link.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this link, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this link, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
filter_abuser	string Default: "nothing" Enum: "block" "flag" "nothing" An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Smart Link 30 times in one minute or clicking 30 different Smart Links within one minute. Setting this to `flag` will send these clicks through to your Smart Link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks.
filter_anon	string Default: "nothing" Enum: "block" "flag" "nothing" An anonymous user is one who is using an anonymous proxy, Virtual Private Network, TOR, or similiar technologies to mask the IP address where their click is originating from. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_bot	string Default: "flag" Enum: "block" "flag" "nothing" A bot is any type of automated program or software that accesses your Smart Links or Rotators. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_server	string Default: "flag" Enum: "block" "flag" "nothing" This represents a "click" from a known web server or hosting company. The overwhelming majority of the time these are scripts used by scammers to generate fake clicks. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_spider	string Default: "flag" Enum: "block" "flag" "nothing" A "spider" is a piece of code that search engines use to index the web, following links in pages as they find them during the indexing process. These spider "clicks" are generally innocent, but they don't represent real clicks from real users and they mess up your stats. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_user	string Default: "flag" Enum: "block" "flag" "nothing" These are the clicks that come from the IPs or IP ranges that you have manually added via your IP Manager page. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
max_clicks	integer <int32> [ 1 .. 999999 ] If specified, this is the maximum number of clicks to redirect through the Smart Link. All additional clicks will then be redirected through the `backup_url`. If you set `max_clicks`, you must also set `backup_url`. To unset this value, set it to nothing, e.g., `max_clicks=&...`.
blank_referrer	string Default: false Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from.
password	string <= 20 characters Setting a password will display a generic login page that the user must enter the password to continue. To unset this value, set it to nothing, e.g., `password=&...`.
notes	string <= 1024 characters Notes that you would like to track for this link. To unset this value, set it to nothing, e.g., `notes=&...`.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/12345" -d "link_name=Example Test"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a stats report for one or more Smart Links

Create a stats report for one or more Smart Links by Smart Link ID. This call returns a report id and url; poll that url with GET /links/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

id required	Array of integers <int32> Pass in one or more Smart Link IDs, up to a maximum of 20. For example: id=12345&id=12346&id=12347
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the link stats. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the link stats. Must be used in conjunction with `start_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/stats" -d "id=1731254&id=1731255"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for the specified Smart Links stats report

Poll for the specified links stats report. If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Once the report has been generated, a 200 status will be returned with the stats.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/stats/reports/3752921"

Response samples

Content type

application/json

{"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"link_id": 1731254,
"total_clicks": 1447,
"unique_clicks": 134,
"flagged_clicks": 4,
"cost": 2477.1,
"cpc": 1.88,
"revenue": 45453.75,
"profit": 42976.65,
"epc": 34.54,
"roi": 1735
}
],
"total_seconds": 39,
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK",
"warnings": ["string"
]
}

Generate a Sub-ID stats report for one or more Smart Links

Generate a report of stats grouped by a Sub-ID (s1–s5) across one or more Smart Links. Stats are aggregated across all the links you pass in, returning one row per distinct Sub-ID value with total, unique and flagged clicks.

This is an asynchronous report. This call returns a report id and url; poll that url with GET /links/subids/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

id required	Array of integers <int32> <= 20 items Pass in one or more Smart Link IDs, up to a maximum of 20. For example: id=12345&id=12346&id=12347. Stats are aggregated across all the links you pass in.
subid required	integer Enum: 1 2 3 4 5 Which Sub-ID position to group the stats by — `1` through `5`.
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range. Must be used in conjunction with `start_time`. The `HH:MM:SS` for an `end_time` is normally `23:59:59`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/subids/stats" -d "id=1731254&id=1731255&subid=1"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for the specified Smart Link Sub-ID stats report

Poll for the specified Sub-ID stats report. If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Once the report has been generated, a 200 status will be returned with the stats: a page of rows, most total clicks first, with total_rows and a cursor. To get the next page, poll again with cursor set to the last response's cursor.next, and the same limit. When cursor.next is null, there are no more rows.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 1000 ] Default: 1000 Example: limit=100 The most rows to return in this page.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/subids/stats/reports/3752921"

Response samples

Content type

application/json

{"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"subid": "affiliate-42",
"total_clicks": 1200,
"unique_clicks": 134,
"flagged_clicks": 5
}
],
"total_rows": 2400,
"cursor": {"next": "ZBDkPOxCKRi",
"prev": "ODM3MjYyMTE"
},
"total_seconds": 2,
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK",
"warnings": ["string"
]
}

Create a stats report for all Smart Links or a link group

Create a report of the Smart Links dashboard's stats: every link in scope, one row per link, sorted by the stat you choose and limited to the top rows, with totals across all of them. Use it for rankings and totals across all your Smart Links or a link group, such as the 10 links with the most clicks this month. For particular links, use POST /links/stats instead: it computes only the links you name, where this report always computes every link in scope.

This call returns a report id and url. Poll that url exactly as given, with GET /links/dashboard/stats/reports/{report_id}, until the report has been generated. The url carries the sort_by, sort_direction, limit and offset you sent.

The report covers whole days in your account's time zone. A range from midnight to midnight ends on the day before, and a start_time or end_time that isn't at the start or end of a day gets a warning saying which days were used. Without start_time and end_time, it covers your account's data window, as the dashboard's All Time does.
Reports are cached and shared with the Smart Links dashboard in the web app: the same settings there and here give the same report. Sending the same request again returns the same report. A report whose range includes today in your account's time zone is cached for 5 to 20 minutes; a report for an older range is cached for up to 3 days. The report's last_updated says when it was generated, and refresh=true asks for a new one.
A change to your account's Smart Links, link groups or Show Subgroup Links setting clears its cached reports. Polling a finished report after that gets a missing-report error, and a report that was still generating gets an error saying it's out of date: create it again either way.
You can have up to 3 unfinished Smart Links dashboard reports at a time, including ones the web dashboard started. A request that would start a fourth gets HTTP status 429. A request for a report that already exists always succeeds, unless refresh=true asks for a new one.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the start of the time range. Must be used with `end_time`. The report starts at the beginning of this day in your account's time zone.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the end of the time range. Must be used with `start_time`. The report runs to the end of this day in your account's time zone; midnight ends it on the day before. The `HH:MM:SS` is normally `23:59:59`.
group_id	integer <int32> Only the links in this link group or subgroup, an `id` from `GET /links/groups`. Without it, all your Smart Links that aren't archived. A top-level group includes its subgroups' links only when your account's Show Subgroup Links setting is on, as on the dashboard. The report's `filters` says whether they're included, and when they're left out its `warnings` names the subgroups. Can't be used with `archived`.
archived	boolean Default: false Only your archived Smart Links. Without it, archived links are left out.
traffic	string Default: "all" Enum: "all" "desktop" "mobile" Only clicks from desktop or mobile devices. With `desktop` or `mobile`, the report's `cost`, `revenue`, `profit`, `epc` and `roi` are `null`: they're per-link amounts that can't be split by device. Click counts are correct.
subid1	string <= 255 characters Only clicks whose Sub-ID 1 (`s1`) is exactly this value. Other Sub-IDs aren't filtered. It can contain letters, digits and the characters `- _ . = ? % @ + : { }`, and can't be `ALL` or `None`. With it, the report's `cost`, `revenue`, `profit`, `epc` and `roi` are `null`: they're per-link amounts that can't be split by Sub-ID. Click counts are correct.
sort_by	string Default: "total_clicks" Enum: "name" "total_clicks" "unique_clicks" "flagged_clicks" "cost" "revenue" "profit" "epc" "roi" How to sort the rows. `name` sorts by the link's name, or its slug when it has no name, ignoring case. Ties are broken by name, then `link_id`, so `limit` and `offset` give the same rows on every poll. A `null` `roi` sorts last in either direction. Sorting by `cost`, `revenue`, `profit`, `epc` or `roi` isn't possible with `traffic` or `subid1`.
sort_direction	string Enum: "asc" "desc" Default: `asc` for `name`, otherwise `desc`.
limit	integer <int32> [ 1 .. 1000 ] Default: 100 The most rows to return. `total_rows` in the report says how many links there are.
offset	integer <int32> >= 0 Default: 0 How many rows to skip, for the next page of rows.
refresh	boolean Default: false Whether to generate the report again. With `refresh=true`, a cached report that has finished is replaced by a new report with a new `id`. A report that finished less than 5 minutes ago is not replaced: you get it back with the warning `refresh ignored: this report was generated less than 5 minutes ago.` A report that is still being generated is never replaced: you get its `id` back. A report that failed to generate is always replaced. Without `refresh=true`, requesting or polling it gets the error `This report failed to generate. Try a shorter date range or a link group, or create it again with refresh=true.`

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/dashboard/stats" -d "start_time=2026-10-01T00:00:00-07:00&end_time=2026-10-31T23:59:59-07:00&sort_by=total_clicks&limit=10"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for a Smart Links dashboard stats report

Poll for a Smart Links dashboard stats report. If the report is still being generated, a 202 status is returned with its progress. Once it has been generated, a 200 status is returned with its rows and totals.

Always poll the report.url from the create response, exactly as given: it carries the sort_by, sort_direction, limit and offset you asked for.

A finished report whose date range includes today is deleted 5 to 20 minutes after it finishes, and one for an older range after 1 to 3 days. A change to your account's Smart Links, link groups or Show Subgroup Links setting clears its reports sooner. Polling a report that's gone gets a missing-report error, and one that was still generating when the change happened gets an error saying it's out of date: create it again either way.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

query Parameters

sort_by	string Default: "total_clicks" Enum: "name" "total_clicks" "unique_clicks" "flagged_clicks" "cost" "revenue" "profit" "epc" "roi" How to sort the rows. See the create request.
sort_direction	string Enum: "asc" "desc" `asc` or `desc`. Default: `asc` for `name`, otherwise `desc`.
limit	integer <int32> [ 1 .. 1000 ] Default: 100 The most rows to return.
offset	integer <int32> >= 0 Default: 0 How many rows to skip.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/dashboard/stats/reports/3752921?sort_by=total_clicks&limit=10"

Response samples

Content type

application/json

{"currency": "USD",
"filters": {"start_date": "2026-10-01",
"end_date": "2026-10-31",
"group_id": 170318,
"subgroups_included": false,
"archived": false,
"traffic": "all",
"subid1": null
},
"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"link_id": 1731254,
"link_name": "Spring Sale",
"link_slug": "spring-sale",
"archived": false,
"total_clicks": 1204,
"unique_clicks": 988,
"flagged_clicks": 12,
"cost": 250,
"revenue": 1100,
"profit": 850,
"epc": 1.11,
"roi": 340
}
],
"time_zone": "America/New_York",
"total_rows": 412,
"totals": {"total_clicks": 18512,
"unique_clicks": 15233,
"flagged_clicks": 402,
"cost": 5120.5,
"revenue": 21840,
"profit": 16719.5,
"epc": 1.43,
"roi": 327
},
"total_seconds": 4,
"warnings": ["string"
],
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK"
}

Rotators

Rotators allow you to take a single link and distribute incoming clicks across multiple destination URLs.

Get a List of Rotators

Get a list of your rotators.

For more information on rotators, please see the knowledgebase.

Authorizations:

apikey

query Parameters

limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
group_id	integer <int32> If you provide a `group_id`, then only rotators in that group are returned.
cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
sort_direction	string <string> Default: "newest_first" Enum: "alpha" "newest_first" "oldest_first" Specify how rotators should be sorted: `alpha` for alphabetical order, `oldest_first` for ordering the oldest-created rotators first, and `newest_first` which orders the most recently created rotators first.
search	string <string> Only include rotators where their `rotator_name` includes this string. For rotators with no `rotator_name`, the `rotator_slug` is searched instead.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators?limit=1"

Response samples

Content type

application/json

{"rotators": [{"id": 128364,
"rotator_mode": "spillover",
"rotator_name": "Health-related Traffic",
"rotator_slug": "healthtraffic"
}
],
"cursor": {"next": "ZBDkPOxCKRi",
"prev": "ODM3MjYyMTE"
},
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a New Rotator

Create a new rotator.

For more information on rotators, please see the knowledgebase.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

rotator_slug required	string [ 4 .. 20 ] characters A unique identifier used as part of the Rotator link, e.g., `https://clkmr.com/<username>/<rotator_slug>`. We recommend using a human-readable value such as `healthtraffic`. Letters, numbers, and dashes are allowed, but no spaces.
rotator_name	string [ 4 .. 32 ] characters The unique "friendly name" of this Rotator. In the UI, if this is not specified, the `rotator_slug` is displayed instead. Rotator names cannot include these special characters: : & \| ; $ % @ " ' < > ( ) + , \
domain_id	integer <int32> >= 0 Default: 0 If you have any custom Rotator domains set up to use with your Rotator links, you can use any of those domains at any time with any of your Rotator links. This `domain_id` setting simply specifies your preferred domain for this particular Rotator link. This is useful in the UI, for example, when ClickMagick needs to copy a Rotator link to the clipboard. It will use this domain in the Rotator link rather than another domain that you might have set up.
rotator_group	integer <int32> >= 0 The ID of the group to organize this Rotator under. If not specified, the 'All' group will be used.
rotator_mode required	string Enum: "fulfillment" "spillover" "random" "sequential" ClickMagick offers four Rotator modes to deliver clicks to your Rotator URLs in different ways, depending upon what you’re trying to accomplish. For a complete explanation of how these different modes work, see this article: What are the 4 different Rotator modes?
random_repeat_clicks	string Enum: "same_url" "random_url" Where repeat clicks should be redirected when they come in for a `random` Rotator. Defaults to `same_url`. This can only be set for `random` Rotators.
sequential_repeat_clicks	string Enum: "same_url" "next_url" Where repeat clicks should be redirected when they come in for a `sequential` Rotator. Defaults to `same_url`. This can only be set for `sequential` Rotators.
spillover_repeat_clicks	string Enum: "backup_url" "last_url" "top_of_rotator" Where repeat clicks should be redirected when they come in for a `spillover` Rotator. Defaults to `backup_url`. This can only be set for `spillover` Rotators.
spillover_randomize	integer <int32> If set, this is the number of minutes that ClickMagick should wait before randomly shuffling all of the Rotator's URLs. This random shuffling is useful at times because clicks are always delivered starting with the Rotator URL that's in the first position, and then down from there. Shuffling causes the URLs to get different priorities after they have been shuffled. If you don't specify anything for this setting, no shuffling occurs. This can only be set for `spillover` Rotators.
spillover_randomize_last_url	boolean Default: true If `spillover_randomize` is set so that the URLs are shuffled regularly, this setting tells ClickMagick whether to include the very last Rotator URL in the shuffling process. You would want to set this to `false` if you don't want the last URL to be shuffled. Typically, this would be the case where the last URL is a "catch all" URL that processes the click specially if it wasn't possible to deliver the click to any of the other URLs. This can only be set for `spillover` Rotators.
backup_url required	string Clicks for this Rotator will be sent to the `backup_url` if they can't be delivered to any of the Rotator URLs. For example if the URL only wants mobile clicks and this is a desktop click, or if the URL only wants 50 clicks per day and it has already received 50 clicks today. If no URL can accept the click, it will be redirected through the `backup_url`.
mobile_url	string <= 2048 characters The URL that clicks from mobile devices will be redirected to instead of being processed by this Rotator. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`.
ios_url	string <= 2048 characters If the click is from an iOS device, clicks will be redirected to this URL instead of to the rotator. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices.
pixels	string <= 2560 characters The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags.
email_start_subject	string The subject of the notification email when delivery starts for a Rotator URL. For more information on notification emails, please visit the knowledgebase.
email_start	string The body of the starting email, in plain text or HTML.
email_finish_subject	string The subject of the notification email when all clicks have been delivered.
email_finish	string The body of the finish email, in plain text or HTML.
email_reply_to	string The Reply-To email address for both the starting and finish email messages.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this Rotator, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. Note: Clicks to Rotators are included or excluded before they are processed by any geotargetting settings in a particular URL of the Rotator.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this Rotator, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
filter_abuser	string Default: "nothing" Enum: "block" "flag" "nothing" An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Rotator link 30 times in one minute or clicking 30 different Rotator links within one minute. Setting this to `flag` will send these clicks through to your Rotator link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks.
filter_anon	string Default: "nothing" Enum: "block" "flag" "nothing" An anonymous user is one who is using an anonymous proxy, Virtual Private Network, TOR, or similiar technologies to mask the IP address where their click is originating from. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_bot	string Default: "flag" Enum: "block" "flag" "nothing" A bot is any type of automated program or software that accesses your Rotator links or Rotators. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_server	string Default: "flag" Enum: "block" "flag" "nothing" This represents a "click" from a known web server or hosting company. The overwhelming majority of the time these are scripts used by scammers to generate fake clicks. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_spider	string Default: "flag" Enum: "block" "flag" "nothing" A "spider" is a piece of code that search engines use to index the web, following links in pages as they find them during the indexing process. These spider "clicks" are generally innocent, but they don't represent real clicks from real users and they mess up your stats. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_user	string Default: "flag" Enum: "block" "flag" "nothing" These are the clicks that come from the IPs or IP ranges that you have manually added via your IP Manager page. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
blank_referrer	boolean Default: false Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from.
notes	string <= 1024 characters Notes that you would like to keep for this Rotator.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators" -d "rotator_slug=healthtraffic&rotator_mode=spillover&backup_url=https://www.example.com/backup"

Response samples

Content type

application/json

{"id": 128364,
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Get the settings for one or more Rotators

Get the settings for one or more Rotators by ID.

Authorizations:

apikey

query Parameters

required

integer <int32> >= 0

To get the settings of one or more Rotators, pass in a single id value, or multiple id values.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/settings?id=128364&id=128365"

Response samples

Content type

application/json

{"rotators": [{"backup_url": "backup.example.com",
"blank_referrer": false,
"created": "2026-10-16T22:55:40Z",
"domain_id": 0,
"email_finish": null,
"email_finish_subject": null,
"email_reply_to": null,
"email_start": null,
"email_start_subject": null,
"exclude_countries": ["NG"
],
"filter_abuser": "nothing",
"filter_anon": "flag",
"filter_bot": "flag",
"filter_server": "flag",
"filter_spider": "flag",
"filter_user": "flag",
"id": 128364,
"include_countries": [ ],
"ios_url": null,
"last_reset": "2026-11-05T18:22:04Z",
"mobile_url": null,
"notes": null,
"pixels": null,
"random_repeat_clicks": null,
"rotator_group": 0,
"rotator_mode": "spillover",
"rotator_name": "Health-related Traffic",
"rotator_slug": "healthtraffic",
"sequential_repeat_clicks": null,
"spillover_randomize": 0,
"spillover_randomize_last_url": false,
"spillover_repeat_clicks": "top_of_rotator"
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Rotator

Permanently delete a Rotator and all of its associated clicks.

Authorizations:

apikey

path Parameters

rotator_id

required

integer <int32> >= 0

The ID of the Rotator to delete.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/12345"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Edit a Rotator

Update an existing Rotator.

Authorizations:

apikey

path Parameters

rotator_id

required

integer <int32> >= 0

The ID of the Rotator to update.

Request Body schema: application/x-www-form-urlencoded

rotator_slug	string [ 4 .. 20 ] characters A unique identifier used as part of the Rotator link, e.g., `https://clkmr.com/<username>/<rotator_slug>`. It cannot be cleared. We recommend using a human-readable value such as `healthtraffic`. Letters, numbers, and dashes are allowed, but no spaces.
rotator_name	string [ 4 .. 32 ] characters The unique "friendly name" of this Rotator. In the UI, if this is not specified, the `rotator_slug` is displayed instead. To unset this value, set it to nothing, e.g., `rotator_name=&...`. Rotator names cannot include these special characters: : & \| ; $ % @ " ' < > ( ) + , \
domain_id	integer <int32> >= 0 Default: 0 If you have any custom Rotator domains set up to use with your Rotator links, you can use any of those domains at any time with any of your Rotator links. This `domain_id` setting simply specifies your preferred domain for this particular Rotator link. This is useful in the UI, for example, when ClickMagick needs to copy a Rotator link to the clipboard. It will use this domain in the Rotator link rather than another domain that you might have set up. To unset this value, set it to nothing, e.g., `domain_id=&...`.
rotator_group	integer <int32> >= 0 The ID of the group to organize this Rotator under. If not specified, the 'All' group will be used. To unset this value, set it to nothing, e.g., `rotator_group=&...`.
rotator_mode	string Enum: "fulfillment" "spillover" "random" "sequential" ClickMagick offers four Rotator modes to deliver clicks to your Rotator URLs in different ways, depending upon what you’re trying to accomplish. For a complete explanation of how these different modes work, see this article: What are the 4 different Rotator modes?
random_repeat_clicks	string Enum: "same_url" "random_url" Where repeat clicks should be redirected when they come in for a `random` Rotator. This can only be set for `random` Rotators.
sequential_repeat_clicks	string Enum: "same_url" "next_url" Where repeat clicks should be redirected when they come in for a `sequential` Rotator. This can only be set for `sequential` Rotators.
spillover_repeat_clicks	string Enum: "backup_url" "last_url" "top_of_rotator" Where repeat clicks should be redirected when they come in for a `spillover` Rotator. This can only be set for `spillover` Rotators.
spillover_randomize	integer <int32> If set, this is the number of minutes that ClickMagick should wait before randomly shuffling all of the Rotator's URLs. This random shuffling is useful at times because clicks are always delivered starting with the Rotator URL that's in the first position, and then down from there. Shuffling causes the URLs to get different priorities after they have been shuffled. To turn off shuffling, set it to nothing, e.g., `spillover_randomize=&...`. This can only be set for `spillover` Rotators.
spillover_randomize_last_url	boolean Default: true If `spillover_randomize` is set so that the URLs are shuffled regularly, this setting tells ClickMagick whether to include the very last Rotator URL in the shuffling process. You would want to set this to `false` if you don't want the last URL to be shuffled. Typically, this would be the case where the last URL is a "catch all" URL that processes the click specially if it wasn't possible to deliver the click to any of the other URLs. This can only be set for `spillover` Rotators.
backup_url	string Clicks for this Rotator will be sent to the `backup_url` if they can't be delivered to any of the Rotator URLs. For example if the URL only wants mobile clicks and this is a desktop click, or if the URL only wants 50 clicks per day and it has already received 50 clicks today. If no URL can accept the click, it will be redirected through the `backup_url`.
mobile_url	string <= 2048 characters The URL that clicks from mobile devices will be redirected to instead of being processed by this Rotator. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`. To unset this value, set it to nothing, e.g., `mobile_url=&...`.
ios_url	string <= 2048 characters If the click is from an iOS device, clicks will be redirected to this URL instead of to the rotator. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices. To unset this value, set it to nothing, e.g., `ios_url=&...`.
pixels	string <= 2560 characters The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To unset this value, set it to nothing, e.g., `pixels=&...`.
email_start_subject	string The subject of the notification email when delivery starts for a Rotator URL. To unset this value, set it to nothing, e.g., `email_start_subject=&...`. For more information on notification emails, please visit the knowledgebase.
email_start	string The body of the starting email, in plain text or HTML. To unset this value, set it to nothing, e.g., `email_start=&...`.
email_finish_subject	string The subject of the notification email when all clicks have been delivered. To unset this value, set it to nothing, e.g., `email_finish_subject=&...`.
email_finish	string The body of the finish email, in plain text or HTML. To unset this value, set it to nothing, e.g., `email_finish=&...`.
email_reply_to	string The Reply-To email address for both the starting and finish email messages. To unset this value, set it to nothing, e.g., `email_reply_to=&...`.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this Rotator, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. Note: Clicks to Rotators are included or excluded before they are processed by any geotargetting settings in a particular URL of the Rotator.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this Rotator, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
filter_abuser	string Default: "nothing" Enum: "block" "flag" "nothing" An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Rotator link 30 times in one minute or clicking 30 different Rotator links within one minute. Setting this to `flag` will send these clicks through to your Rotator link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks.
filter_anon	string Default: "nothing" Enum: "block" "flag" "nothing" An anonymous user is one who is using an anonymous proxy, Virtual Private Network, TOR, or similar technologies to mask the IP address where their click is originating from. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_bot	string Default: "flag" Enum: "block" "flag" "nothing" A bot is any type of automated program or software that accesses your Rotator links or Rotators. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_server	string Default: "flag" Enum: "block" "flag" "nothing" This represents a "click" from a known web server or hosting company. The overwhelming majority of the time these are scripts used by scammers to generate fake clicks. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_spider	string Default: "flag" Enum: "block" "flag" "nothing" A "spider" is a piece of code that search engines use to index the web, following links in pages as they find them during the indexing process. These spider "clicks" are generally innocent, but they don't represent real clicks from real users and they mess up your stats. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_user	string Default: "flag" Enum: "block" "flag" "nothing" These are the clicks that come from the IPs or IP ranges that you have manually added via your IP Manager page. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
blank_referrer	boolean Default: false Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from.
notes	string <= 1024 characters Notes that you would like to keep for this Rotator.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/12345" -d "rotator_name=test2"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a stats report for one or more Rotators

Create a stats report for one or more Rotators by Rotator ID. This call returns a report id and url; poll that url with GET /rotators/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

id required	Array of integers <int32> Pass in one or more Rotator IDs. `&id=128364&id=128365`
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the Rotator stats. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the Rotator stats. Must be used in conjunction with `start_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/stats" -d "id=128364&id=128365"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for the specified Rotators stats report

Poll for the specified Rotators stats report. If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Once the report has been generated, a 200 status will be returned with the stats.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/stats/reports/3752921"

Response samples

Content type

application/json

{"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"rotator_id": 128364,
"active_urls": 10,
"paused_urls": 4,
"archived_urls": 0,
"total_clicks": 507,
"unique_clicks": 134,
"flagged_clicks": 5
}
],
"total_seconds": 39,
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK",
"warnings": ["string"
]
}

Rotator URLs

Every Rotator has a list of Rotator URLs that it distributes clicks to. Use these endpoints to manage the URLs for a specific Rotator.

Get a list of Rotator URLs and their IDs

Get the list of Rotator URLs and IDs for a specific Rotator.

Authorizations:

apikey

path Parameters

rotator_id

required

integer <int32> >= 0

The ID of the parent Rotator of these Rotator URLs.

query Parameters

limit	integer <int32> [ 1 .. 100 ] Default: 100 Example: limit=10 Maximum number of items to fetch for this page.
cursor	string <string> Pass in the previous page's cursor `next` or `prev` response value to retrieve the next page or previous page of data. This allows you to move through the data either forward or backwards. Send it with the same other parameters as the request it came from.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls?limit=1"

Response samples

Content type

application/json

{"rotator_urls": [{"id": 358792,
"name": "Terry Jones 500C",
"status": "active"
}
],
"cursor": {"next": "ZBDkPOxCKRi",
"prev": null
},
"errors": [ ],
"status": "OK",
"warnings": [ ]
}

Create a new Rotator URL

Create a new Rotator URL.

Authorizations:

apikey

path Parameters

rotator_id

required

integer <int32> >= 0

The ID of the Rotator to create a URL for.

Request Body schema: application/x-www-form-urlencoded

name required	string The name of this Rotator URL.
status	string Default: "active" Enum: "active" "paused" "archived" Set the initial state that the Rotator URL should be in. In almost all cases, you'll want to set this to `active`, even if you're setting the `start_time` for a date in the future. URLs with start times in the future are not paused — they are actively waiting until the start time. The `paused` status means that the Rotator will stay paused, no matter what, until it is changed to `active` either manually in the UI or through the API. To be absolutely clear, a user-paused Rotator will not automatically unpause, ever, even if there is a `start_time` scheduled and that time arrives.
url required	string The URL to deliver clicks to.
position	integer <int32> [ 1 .. 9999 ] The position in the Rotator. If the position is not specified, it will be added to the last position in the Rotator.
weight	integer <int32> [ 1 .. 10 ] Default: 1 When using a Sequential Rotator, this allows you to specify at what speed the URL should get traffic. For example, a weight of 2 means that this URL will get twice the traffic during the same period of time as compared to URLs that have the default weight of 1. If you set this to 3, traffic will be delivered 3 times faster. This can only be set for URLs in `sequential` Rotators.
max_clicks	integer <int32> [ 1 .. 999999 ] Default: null The maximum number of unique clicks to send to this Rotator. If not specified, it defaults to "unlimited".
max_clicks_daily	integer <int32> [ 1 .. 9999 ] The maximum number of unique clicks to send to this Rotator per day. If not specified, it defaults to "unlimited".
bonus	integer <int32> [ 0 .. 99 ] Default: 0 The percentage of max_clicks to over-deliver.
min_t1	integer <int32> [ 0 .. 100 ] Default: 0 The minimum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. If you set `min_t1`, you must also set `max_t1` at the same time.
max_t1	integer <int32> [ 0 .. 100 ] Default: 100 The maximum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. If you set `max_t1`, you must also set `min_t1` at the same time.
min_mobile	integer <int32> [ 0 .. 100 ] Default: 0 The minimum amount of mobile traffic this URL will receive on a percentage basis. If you set `min_mobile`, you must also set `max_mobile` at the same time.
max_mobile	integer <int32> [ 0 .. 100 ] The maximum amount of mobile traffic this URL will receive on a percentage basis. If you set `max_mobile`, you must also set `min_mobile` at the same time. If not specified, it defaults to "unlimited".
pixels	string The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags.
start_time	string <date-time> The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to start sending traffic to this Rotator URL.
end_time	string <date-time> The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to stop sending traffic to this Rotator URL.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this Rotator URL, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. NOTE: The geotargetting settings of the parent Rotator are processed first. That means that if you include a country in this Rotator URL, but the Rotator itself excludes that country, this URL will never get those clicks.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this Rotator URL, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. NOTE: The geotargetting settings of the parent Rotator are processed first. That means that more countries may be excluded from this Rotator URL than you have explicitly specified here.
email	string The email address to use when sending start and finish notification messages.
send_start_email	string Enum: "on_add" "on_first_click" If the parent Rotator has a "start" email set up, should that email be sent as soon as this URL is added to the system or should the email wait until the first click has been delivered to the URL?
send_finish_email	boolean Default: false If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered. This only works if `max_clicks` is set. If `max_clicks` has no value, `send_finish_email` is set to `false`.
notes	string Notes that you would like to track for this link.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls" -d "name=Terry Jones 500C&url=https://www.example.com/salespage"

Response samples

Content type

application/json

{"errors": [ ],
"id": 358792,
"public_stats_url": "https://www.clickmagick.com/share/002f6ed001f56c0057988",
"status": "OK",
"warnings": [ ]
}

Get the settings for one or more Rotator URLs

Get the settings for one or more Rotator URLs by ID.

Authorizations:

apikey

query Parameters

required

integer <int32> >= 0

To get the settings of one or more Rotator URLs, pass in a single id value, or multiple id values.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/settings?id=358792&id=358793"

Response samples

Content type

application/json

{"rotator_urls": [{"id": 358792,
"public_stats_url": "https://www.clickmagick.com/share/002f6ed001f56c0057988",
"rotator_id": 128364,
"name": "Terry Jones 500C",
"status": "active",
"url": "https://www.example.com/salespage",
"position": 1,
"weight": 1,
"max_clicks": 500,
"max_clicks_daily": 25,
"bonus": 0,
"min_t1": 60,
"max_t1": null,
"min_mobile": null,
"max_mobile": null,
"pixels": null,
"start_time": null,
"end_time": null,
"include_countries": [ ],
"exclude_countries": ["NG"
],
"email": "terry@example.com",
"send_start_email": "on_first_click",
"send_finish_email": true,
"notes": null,
"last_reset": "2026-11-05T18:22:04Z",
"created": "2026-10-16T22:55:40Z"
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Rotator URL

Permanently delete a Rotator URL and all of its associated clicks.

Authorizations:

apikey

path Parameters

rotator_id required	integer <int32> >= 0 The ID of the parent Rotator of these Rotator URLs.
url_id required	integer <int32> >= 0 The ID of the Rotator URL to delete.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls/358792"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Edit a Rotator URL

Update a Rotator URL.

Authorizations:

apikey

path Parameters

rotator_id required	integer <int32> >= 0 The ID of the parent Rotator of these Rotator URLs.
url_id required	integer <int32> >= 0 The ID of the URL to edit.

Request Body schema: application/x-www-form-urlencoded

name	string The name of this Rotator URL.
status	string Enum: "active" "paused" "archived" Set the initial state that the Rotator URL should be in. In almost all cases, you'll want to set this to `active`, even if you're setting the `start_time` for a date in the future. URLs with start times in the future are not paused — they are actively waiting until the start time. The `paused` status means that the Rotator will stay paused, no matter what, until it is changed to `active` either manually in the UI or through the API. To be absolutely clear, a user-paused Rotator will not automatically unpause, ever, even if there is a `start_time` scheduled and that time arrives.
url	string The URL to deliver clicks to.
position	integer <int32> [ 1 .. 9999 ] The position in the Rotator. To move the URL to the last position, set it to nothing, e.g., `position=&...`.
weight	integer <int32> [ 1 .. 10 ] Default: 1 When using a Sequential Rotator, this allows you to specify at what speed the URL should get traffic. For example, a weight of 2 means that this URL will get twice the traffic during the same period of time as compared to URLs that have the default weight of 1. If you set this to 3, traffic will be delivered 3 times faster. This can only be set for URLs in `sequential` Rotators.
max_clicks	integer <int32> [ 1 .. 999999 ] Default: null The maximum number of unique clicks to send to this Rotator. If not specified, it defaults to "unlimited". To reset `max_clicks` to "unlimited" if it already has a value, set it to nothing, e.g., `max_clicks=&...`.
max_clicks_daily	integer <int32> [ 1 .. 9999 ] The maximum number of unique clicks to send to this Rotator per day. If not specified, it defaults to "unlimited". To reset `max_clicks_daily` to "unlimited" if it already has a value, set it to nothing, e.g., `max_clicks_daily=&...`.
bonus	integer <int32> [ 0 .. 99 ] Default: 0 The percentage of max_clicks to over-deliver.
min_t1	integer <int32> [ 0 .. 100 ] Default: 0 The minimum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. To reset `min_t1` if it already has a value, set it to nothing, e.g., `min_t1=&...`. If you set `min_t1`, you must also set `max_t1` at the same time.
max_t1	integer <int32> [ 0 .. 100 ] Default: 100 The maximum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. To reset `max_t1` if it already has a value, set it to nothing, e.g., `max_t1=&...`. If you set `max_t1`, you must also set `min_t1` at the same time.
min_mobile	integer <int32> [ 0 .. 100 ] Default: 0 The minimum amount of mobile traffic this URL will receive on a percentage basis. To reset `min_mobile` if it already has a value, set it to nothing, e.g., `min_mobile=&...`. If you set `min_mobile`, you must also set `max_mobile` at the same time.
max_mobile	integer <int32> [ 0 .. 100 ] The maximum amount of mobile traffic this URL will receive on a percentage basis. To reset `max_mobile` if it already has a value, set it to nothing, e.g., `max_mobile=&...`. If you set `max_mobile`, you must also set `min_mobile` at the same time.
pixels	string The `pixel` setting allows you to pass in HTML that will be loaded behind the scenes as the click is being redirected. You can add `<img>` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To clear `pixels` if it already has a value, set it to nothing, e.g., `pixels=&...`.
start_time	string <date-time> The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to start sending traffic to this Rotator URL. To clear `start_time` if it already has a value, set it to nothing, e.g., `start_time=&...`.
end_time	string <date-time> The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to stop sending traffic to this Rotator URL. To clear `end_time` if it already has a value, set it to nothing, e.g., `end_time=&...`.
include_country	string Default: "all countries" If you want clicks only from specific countries to be delivered to this Rotator URL, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. NOTE: The geotargetting settings of the parent Rotator are processed first. That means that if you include a country in this Rotator URL, but the Rotator itself excludes that country, this URL will never get those clicks. To clear `include_country` if it already has a value, set it to nothing, e.g., `include_country=&...`.
exclude_country	string Default: "no countries" If you want to exclude clicks from specific countries from being delivered to this Rotator URL, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List. NOTE: The geotargetting settings of the parent Rotator are processed first. That means that more countries may be excluded from this Rotator URL than you have explicitly specified here. To clear `exclude_country` if it already has a value, set it to nothing, e.g., `exclude_country=&...`.
email	string The email address to use when sending start and finish notification messages. To clear `email` if it already has a value, set it to nothing, e.g., `email=&...`.
send_start_email	string Enum: "on_add" "on_first_click" If the parent Rotator has a "start" email set up, should that email be sent as soon as this URL is added to the system or should the email wait until the first click has been delivered to the URL?
send_finish_email	boolean Default: false If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered. This only works if `max_clicks` is set. If `max_clicks` has no value, `send_finish_email` is set to `false`.
notes	string Notes that you would like to track for this link. To clear `notes` if it already has a value, set it to nothing, e.g., `notes=&...`.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls/358792" -d "url=https://www.example.com/offer"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a stats report for one or more Rotator URLs

Create a stats report for one or more Rotator URLs by Rotator URL ID. This call returns a report id and url; poll that url with GET /rotators/urls/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

id required	Array of integers <int32> Pass in one or more Rotator URL IDs. For example: id=12345&id=12346&id=12347
rotator_id required	integer <int32> The ID of the Rotator that the URL IDs belong to.
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range for the link stats. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range for the link stats. Must be used in conjunction with `start_time`. The `HH:MM:SS` for an `end_time` is normally `23:59:59`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
time_zone	string The time zone that decides which day is "today" for `clicks_today`, as a `tz database` name such as `America/New_York`. If you don't pass it, the time zone in your ClickMagick account's User Settings is used. It only affects `clicks_today`. It doesn't change the time range: `start_time` and `end_time` are exact moments, so to get stats for whole days in a particular time zone, give them with that time zone's offset from UTC.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/stats" -d "rotator_id=128364&id=358792"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for the specified Rotator URLs stats report

Poll for the specified Rotator URLs stats report. If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Once the report has been generated, a 200 status will be returned with the stats.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/stats/reports/3752921"

Response samples

Content type

application/json

{"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"url_id": 358792,
"rotator_id": 128364,
"total_clicks": 193,
"unique_clicks": {"delivered": 186,
"max_clicks": 200,
"bonus_clicks": 10
},
"flagged_clicks": 5,
"clicks_today": {"delivered": 10,
"max_clicks_daily": 15
},
"status": "paused",
"status_paused_reason": "user_paused"
}
],
"total_seconds": 39,
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK",
"warnings": ["string"
]
}

Generate a Sub-ID stats report for a Rotator's URLs

Generate a report of a Rotator's clicks grouped by Rotator URL and by the values of one Sub-ID (s1–s5): one row per Rotator URL per Sub-ID value, with total, unique and flagged clicks. There are no totals across URLs; add up the rows.

This is an asynchronous report. This call returns a report id and url; poll that url with GET /rotators/urls/subids/stats/reports/{report_id} until the report has been generated.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

rotator_id required	integer <int32> The ID of the Rotator.
id	Array of integers <int32> <= 20 items Optional. One or more of the Rotator's URL IDs, up to 20. For example: id=12345&id=12346. If you leave it out, the report covers every URL the Rotator has now.
subid required	integer Enum: 1 2 3 4 5 Which Sub-ID position to group the stats by — `1` through `5`.
start_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the starting date and time of the time range. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.
end_time	string <date-time> The ISO-8601 timestamp, in UTC as `YYYY-MM-DDTHH:MM:SSZ` or with an offset from UTC such as `2026-12-01T00:00:00-05:00` (midnight in New York), for the ending date and time of the time range. Must be used in conjunction with `start_time`. The `HH:MM:SS` for an `end_time` is normally `23:59:59`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/subids/stats" -d "rotator_id=128364&subid=1"

Response samples

Content type

application/json

{"report": {"id": 3752921,
"url": "https://api.clickmagick.com/v1/foo/bar/reports/3752921"
},
"status": "OK"
}

Poll for the specified Rotator Sub-ID stats report

Poll for the specified Sub-ID stats report. If the report is still being generated, a 202 status will be returned with the progress of how much of the report has been generated.

Most reports are ready in well under a second. Poll on this schedule:

Wait 250 milliseconds after creating the report, then check it.
If it isn't ready, wait 500 milliseconds and check again.
After that, check once a second.
If it still isn't ready after 30 seconds, check every 5 seconds.

Authorizations:

apikey

path Parameters

report_id

required

integer <int32> >= 1

Example: 3752921

The report id for this request.

query Parameters

cursor	string Example: cursor=ZBDkPOxCKRi The cursor representing your current place in the results. Send it with the same other parameters as the request it came from.
limit	integer <int32> [ 1 .. 1000 ] Default: 1000 Example: limit=100 The most rows to return in this page.

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/subids/stats/reports/3752921"

Response samples

Content type

application/json

{"last_updated": "2026-11-12T22:41:16Z",
"stats": [{"url_id": 54321,
"subid": "affiliate-42",
"total_clicks": 1200,
"unique_clicks": 134,
"flagged_clicks": 5
}
],
"total_rows": 2400,
"cursor": {"next": "ZBDkPOxCKRi",
"prev": "ODM3MjYyMTE"
},
"total_seconds": 2,
"progress": {"completed": false,
"percentage_completed": 47
},
"errors": ["string"
],
"status": "OK",
"warnings": ["string"
]
}

Custom Domains

Use these endpoints to manage the Custom Domains for your Smart Links and Rotators.

Get all Custom Domains

Return the settings for all custom domains that have been set up for Smart Links and Rotators.

For more information on Domains, please see the knowledgebase.

Authorizations:

apikey

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains"

Response samples

Content type

application/json

{"domains": [{"id": 49735,
"domain": "example.com",
"type": "link",
"setup": "cname",
"error_url": null
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a Custom Domain

Create a custom domain for use by Smart Links or Rotators. The custom domain does not have to be a root domain. It can have subdomains, e.g., track.example.com.

For more information on Domains, please see the knowledgebase.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

domain required	string <= 255 characters The domain name to use as a custom domain.
type required	string Enum: "link" "rotator" The type of tracking to use this custom domain for.
error_url	string <= 2048 characters The URL to redirect visitors to if an error occurs with your custom domain when using it. This is most commonly caused by using a non-existent or misspelled link slug or Rotator slug with the domain. For example, you meant to send clicks to `https://example.com/golfclubs` but you entered the URL in your ad as `https://example.com/glofclubs`. It's perfectly okay to set the `error_url` to the URL of another Smart Link or Rotator.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains" -d "domain=example.com&type=link"

Response samples

Content type

application/json

{"id": 49735,
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Custom Domain

Permanently delete a custom domain. Any URLs that use the deleted domain will obviously no longer work. The Smart Links or Rotators can still be used if you use the generic ClickMagick domains instead: clkmg.com for Smart Links, or clkmr.com for Rotators.

For more information on Domains, please see the knowledgebase.

Authorizations:

apikey

path Parameters

domain_id

required

integer <int32> >= 0

The ID of the domain to permanently delete.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains/49735"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Groups

Use Groups and Subgroups to organize your Smart Links and Rotators.

Note that if you delete a Group or Subgroup, all links in the group will be moved to the "All" group.

Get a list of Link Groups

Return a list of your Link Groups and their subgroups.

Authorizations:

apikey

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups"

Response samples

Content type

application/json

{"groups": [{"id": 27395,
"name": "Gardening",
"subgroups": [{"id": 14273,
"name": "Composters"
}
]
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a Link Group

Create a new Smart Link Group that can be used for organizing your Links.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

name

required

string

The name of the Link Group to create.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups" -d "name=Gardening"

Response samples

Content type

application/json

{"id": 27395,
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Rename a Link Group

Rename an existing Smart Link group or subgroup.

Authorizations:

apikey

query Parameters

name required	string The new name of the group or subgroup.
group_id required	integer <int32> >= 0 The ID of the top-level Group.
subgroup_id	integer <int32> >= 0 If you're renaming a subgroup, pass both the `group_id` and the `subgroup_id`.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups?group_id=27395&name=Gardening"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Link Group

Delete an existing Smart Link group or subgroup. If you delete a top-level group, all subgroups will be deleted as well. All affected Links will be assigned to the default "All" Group.

Authorizations:

apikey

path Parameters

group_id

required

integer <int32> >= 0

The ID of the top-level Smart Link group.

query Parameters

subgroup_id

integer <int32> >= 0

If you're deleting a subgroup, pass in the additional subgroup_id.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups/27395?subgroup_id=14273"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a Link Subgroup

Create a new Smart Link subgroup.

Authorizations:

apikey

path Parameters

group_id

required

integer <int32> >= 0

The Group ID that this new subgroup should be added to.

Request Body schema: application/x-www-form-urlencoded

name

required

string

The name of the subgroup to create.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups/27395/subgroups" -d "name=Composters"

Response samples

Content type

application/json

{"id": 14273,
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Get a list of Rotator Groups

Return a list of Rotator Groups. Unlike Smart Link Groups, Rotator Groups do not have Subgroups.

Authorizations:

apikey

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups"

Response samples

Content type

application/json

{"groups": [{"id": 27395,
"name": "Weightloss"
}
],
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Create a Rotator Group

Create a new Rotator Group.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

name

required

string

The name of the Rotator Group to create.

Responses

Request samples

curl

curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups" -d "name=Weightloss"

Response samples

Content type

application/json

{"id": 27395,
"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Rename a Rotator Group

Rename an existing Rotator group.

Authorizations:

apikey

query Parameters

name required	string The new name of the group.
group_id required	integer <int32> >= 0 The ID of the Rotator roup.

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups?group_id=27395&name=Weightloss"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

Delete a Rotator Group

Delete an existing Rotator group. All affected Rotators will be assigned to the default "All" Group.

Authorizations:

apikey

path Parameters

group_id

required

integer <int32> >= 0

The ID of the rotator group.

Responses

Request samples

curl

curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups/27395"

Response samples

Content type

application/json

{"status": "OK",
"errors": [ ],
"warnings": [ ]
}

User Settings

User settings allow you to modify the global default values for your Projects, Smart Links, and Rotators.

Get account settings

Returns the settings for your account.

Authorizations:

apikey

Responses

Request samples

curl

curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/user/settings"

Response samples

Content type

application/json

{"errors": [ ],
"settings": {"affiliate_username": null,
"blocked_country": ["NG"
],
"blocked_countries_url": "https://www.example.com/blocked",
"copy_to_clipboard": true,
"currency": "USD",
"custom_logo_image_url": null,
"custom_logo_link_url": null,
"date_range": "today",
"error_url": "https://www.example.com/error",
"filter_abuser": "block",
"filter_anon": "nothing",
"filter_bot": "flag",
"filter_server": "flag",
"filter_spider": "flag",
"filter_user": "flag",
"invalid_click_threshold": 10,
"notify_conversions": true,
"public_logo_type": "clickmagick_logo",
"show_subgroup_links": true,
"stat_labels": {"actions": "Leads",
"engagements": "Engaged",
"sales": "Sales"
},
"tablet": "desktop",
"time_zone": "Australia/Sydney"
},
"status": "OK",
"warnings": [ ]
}

Edit account settings

Allows you to update your account settings.

Authorizations:

apikey

Request Body schema: application/x-www-form-urlencoded

affiliate_username	string Is this user also an affiliate marketer for ClickMagick? This is their username if so.
blocked_country	string Default: "no countries" If you want to block clicks from specific countries from ever being delivered to any Smart Link or Rotator, use the `blocked_country` parameter. For each country that you want to block clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to block all clicks from North America use: `blocked_country=US&blocked_country=MX&blocked_country=CA` You can also block Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `blocked_countries_url`, if one is set. You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.
blocked_countries_url	string <uri> If set, blocked country clicks are redirected to this URL.
copy_to_clipboard	boolean When saving or creating a Smart Link or Rotator link, should the Smart Link or Rotator link be automatically copied to the clipboard? If `true`, Smart Links and Rotator links will be copied to the clipboard.
currency	string 3 characters Default: "USD" If you're using the Auto Cost feature to pull in cost data from your Ad Account (Google, Facebook, etc.), and your ad account is sending cost data to ClickMagick in one currency, but all of your sales are being reported to ClickMagick in a different currency, then ClickMagick needs to convert your Auto Cost data from the currency that it's being reported in to the same currency that your sales are being reported in. The `currency` setting tells ClickMagick what currency your sales are being reported in so that it can convert Auto Cost data to match your sales data. The value of `currency` is the standard 3-letter International Bank Account Number (IBAN): `USD` for US dollars, `AUD` for Australian dollars, `EUR` for Euros, and so on. You can find a complete of International Bank Account Numbers at IBAN Currency Codes. ClickMagick only supports the most common currencies at this point. If you need a currency that is not currently supported, submit a ticket and we will add it.
custom_logo_image_url	string <uri> Default: null The URL of your custom logo image. This only applies when `public_logo_type` is `custom_logo`, so to set or change this URL, include `public_logo_type=custom_logo` in the same request.
custom_logo_link_url	string <uri> Default: null If the custom logo is clicked on, the browser will be redirected to this URL. Optional, and it has no effect unless your logo type is `custom_logo`. Pass an empty value to remove it.
date_range	string Enum: "today" "last_7_days" "last_30_days" "this_month" "this_year" "all_time" This is the default date range whenever you first log in to ClickMagick.
error_url	string <uri> The URL to redirect visitors to if an incoming click can't be delivered. This is most commonly caused by using a non-existent or misspelled link slug or Rotator slug in your link. For example, you meant to send clicks to `https://example.com/golfclubs` but you entered the URL in your ad as `https://example.com/glofclubs`. It's perfectly okay to set the `error_url` to the URL of another Smart Link or Rotator.
filter_abuser	string Default: "nothing" Enum: "block" "flag" "nothing" An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Smart Link 30 times in one minute or clicking 30 different Smart Links within one minute. Setting this to `flag` will send these clicks through to your link or Rotator but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks.
filter_anon	string Default: "nothing" Enum: "block" "flag" "nothing" An anonymous user is one who is using an anonymous proxy, Virtual Private Network, TOR, or similiar technologies to mask the IP address where their click is originating from. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_apply	boolean Default: false If set to `true`, apply these filter settings to all existing Smart Links and Rotators.
filter_bot	string Default: "flag" Enum: "block" "flag" "nothing" A bot is any type of automated program or software that accesses your Smart Links or Rotators. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_server	string Default: "flag" Enum: "block" "flag" "nothing" This represents a "click" from a known web server or hosting company. The overwhelming majority of the time these are scripts used by scammers to generate fake clicks. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_spider	string Default: "flag" Enum: "block" "flag" "nothing" A "spider" is a piece of code that search engines use to index the web, following links in pages as they find them during the indexing process. These spider "clicks" are generally innocent, but they don't represent real clicks from real users and they mess up your stats. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
filter_user	string Default: "flag" Enum: "block" "flag" "nothing" These are the clicks that come from the IPs or IP ranges that you have manually added via your IP Manager page. See `filter_abuser` for an explanation of `flag`, `block`, and `nothing`.
invalid_click_threshold	integer Default: 10 ClickMagick will send an email if it detects this setting's number of non-existent Smart Link or Rotator link requests to your account within a short period of time. This can be caused by normal web activity, but can also be caused if you delete a Smart Link or Rotator link from your account and you have a web page that is still sending traffic to the deleted link.
public_logo_type	string Default: "clickmagick_logo" Enum: "clickmagick_logo" "custom_logo" "no_logo" The logo shown on your shared stats pages. Send this parameter to change the logo.
notify_conversions	boolean Default: false Receive a notification by email each time you make a sale.
show_subgroup_links	boolean If `true`, it means that when a top-level Smart Link group is selected for displaying links, all links in any subgroups of that top-level group will also be shown. If this is `false`, Smart Links in subgroups are only displayed when the subgroup itself is selected for viewing.
tablet	string Default: "desktop" Enum: "desktop" "mobile" Treat traffic from tablet devices as either `mobile` or `desktop` traffic.
time_zone	string The default time zone that ClickMagick uses for the account, specified using the named format in the IANA Time Zone Database, such as `America/New_York` and `Australia/Sydney`. You can find a list of the time zone names in this article: IANA Time Zone Database

Responses

Request samples

curl

curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/user/settings" -d "time_zone=Australia/Sydney&date_range=last_7_days"

Response samples

Content type

application/json

{"errors": [ ],
"status": "OK",
"warnings": [ ]
}