Documentation Powered by ReDoc

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, as part of a Standard or Pro plan.

Authentication

apikey

The API key issued to you by ClickMagick.

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
search
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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/campaigns/projects

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "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 -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
id
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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/campaigns/projects/settings?id=29583&id=...

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "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 YYYY-MM-DDTHH:MM:SSZ 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 YYYY-MM-DDTHH:MM:SSZ 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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/campaigns/projects/utms?id=29583&start_time=...&end_time=...

Response samples

Content type
application/json
{
  • "utm": {
    },
  • "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 -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
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

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
string

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

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.

end_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ 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.

start_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ 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.

utm_campaign
string

Only match results with this utm_campaign value.

utm_content
string

Only match results with this utm_content value.

utm_medium
string

Only match results with this utm_medium value.

utm_source
string

Only match results with this utm_source value.

utm_term
string

Only match results with this utm_term value.

refresh
boolean
Default: false

Whether to regenerate the report from scratch. Stats reports are cached for a period of time depending upon how long it took to initially compute the report. The longer a report takes to generate, the longer the report will be cached for. Note that if the requested report does not include the most recent 24 hours, then it will stay in the cache much longer. 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.

Responses

Request samples 

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
{}

Create a stats report for a Project using a specific model

Create a stats report for a 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"

The source data model to use for this report.

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

A request to generate a campaign project stats report.

end_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ 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.

start_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ 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.

utm_campaign
string

Only match results with this utm_campaign value.

utm_content
string

Only match results with this utm_content value.

utm_medium
string

Only match results with this utm_medium value.

utm_source
string

Only match results with this utm_source value.

utm_term
string

Only match results with this utm_term value.

refresh
boolean
Default: false

Whether to regenerate the report from scratch. Stats reports are cached for a period of time depending upon how long it took to initially compute the report. The longer a report takes to generate, the longer the report will be cached for. Note that if the requested report does not include the most recent 24 hours, then it will stay in the cache much longer. 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.

Responses

Request samples 

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
{}

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.

Authorizations:
apikey
path Parameters
report_id
required
integer <int32> >= 1
Example: 3752921

The report id for this request.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "last_updated": "2025-10-22T18:38:59Z",
  • "progress": {
    },
  • "stats": {
    },
  • "status": "OK",
  • "total_seconds": 39
}

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.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

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.

Results are not returned in any specified order.

Authorizations:
apikey
query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "actions": [
    ],
  • "status": "OK"
}

Get Actions for all Projects using a specific model

Get actions for all Projects using a specific attribution model.

Results are not returned in any specified order.

Authorizations:
apikey
path Parameters
attribution_model
required
string (AttributionModel)
Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "actions": [
    ],
  • "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.

Results are not returned in any specified order.

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.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "actions": [
    ],
  • "status": "OK"
}

Get Actions for a Project using a specific model

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

Results are not returned in any specified order.

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"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "actions": [
    ],
  • "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.

Results are not returned in any specified order.

Authorizations:
apikey
query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get Engagements for all Projects using a specific model

Get engagements for all Projects using a specific attribution model.

Results are not returned in any specified order.

Authorizations:
apikey
path Parameters
attribution_model
required
string (AttributionModel)
Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "sales": [
    ],
  • "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.

Results are not returned in any specified order.

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.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get Engagements for a Project using a specific model

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

Results are not returned in any specified order.

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"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get Sales for all Projects

Get sales for all Projects using the last_click attribution model.

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

Results are not returned in any specified order.

Authorizations:
apikey
query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get Sales for all Projects using a specific model

Get sales for all Projects using a specific attribution model.

Results are not returned in any specified order.

Authorizations:
apikey
path Parameters
attribution_model
required
string (AttributionModel)
Enum: "first_click" "last_click" "linear" "pos_based" "time_decay"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "cursor": {
    },
  • "sales": [
    ],
  • "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.

Results are not returned in any specified order.

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.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get sales for a Project using a specific model

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

Results are not returned in any specified order.

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"

The source data model to use for this report.

query Parameters
cursor
string
Example: cursor=ZBDkPOxCKRi

The cursor representing your current place in the results.

end_time
string <date-time>
Example: end_time=2025-10-22T18:38:59Z

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.

limit
integer <int32> [ 1 .. 100 ]
Default: 100
Example: limit=10

Maximum number of items to fetch for this page.

start_time
string <date-time>
Example: start_time=2025-10-21T09:46:11Z

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.

utm_campaign
string
Example: utm_campaign=end+of+season

Only match results with this utm_campaign value.

utm_content
string
Example: utm_content=best+surfboard

Only match results with this utm_content value.

utm_medium
string
Example: utm_medium=cpc

Only match results with this utm_medium value.

utm_source
string
Example: utm_source=google

Only match results with this utm_source value.

utm_term
string
Example: utm_term=Hang+Ten

Only match results with this utm_term value.

Responses

Request samples 

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": {
    },
  • "sales": [
    ],
  • "status": "OK"
}

Get the settings for one or more Smart Links

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

Authorizations:
apikey
query Parameters
id
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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/links/settings?id=1731254&id=...

Response samples

Content type
application/json
{
  • "links": [
    ],
  • "status": "OK",
  • "errors": [ ],
  • "warnings": [ ]
}

Generate stats for one or more Smart Links

Get the stats for one or more Smart Links by Smart Link ID.

Authorizations:
apikey
Request Body schema: application/x-www-form-urlencoded
id
required
Array of integers <int32>

Pass in one or more Smart Link IDs. For example: id=12345&id=12346&id=12347

start_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ for the starting date and time of the time range for the link stats. Must be used in conjunction with end_time.

end_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ for the ending date and time of the time range for the link stats. Must be used in conjunction with start_time.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

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.

Authorizations:
apikey
path Parameters
report_id
required
integer <int32> >= 1
Example: 3752921

The report id for this request.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "last_updated": "2025-10-22T18:38:59Z",
  • "stats": [
    ],
  • "total_seconds": 39,
  • "progress": {
    },
  • "errors": [
    ],
  • "status": "OK",
  • "warnings": [
    ]
}

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.

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.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "rotators": [
    ],
  • "cursor": {
    },
  • "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/<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 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"

When repeat clicks come in for the random Rotator, where should they be redirected to. This is required if rotator_mode is set to random.

sequential_repeat_clicks
string
Enum: "same_url" "next_url"

When repeat clicks come in for the sequential Rotator, where should they be redirected to. This is required if rotator_mode is set to sequential.

spillover_repeat_clicks
string
Enum: "backup_url" "last_url" "top_of_rotator"

When repeat clicks come in for the spillover Rotator, where should they be redirected to. This is required if rotator_mode is set to spillover.

spillover_randomize
integer <int32>

This setting is only for Spillover Rotators. If set, it 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.

spillover_randomize_last_url
boolean
Default: true

If the Rotator is a Spillover Rotator and 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.

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 <= 255 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 <= 255 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 &lt;script&gt; .. &lt;/script&gt; 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 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 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 American 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.

If you use this parameter, all clicks that are explicitly excluded 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.

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 -X POST -H "apikey: YOURAPIKEY" https://api.clickmagick.com/v1/rotators -d "rotator_name=test&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
id
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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/rotators/settings?id=128364&id=...

Response samples

Content type
application/json
{
  • "rotators": [
    ],
  • "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 -X DELETE -H "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/<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 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"

When repeat clicks come in for the random Rotator, where should they be redirected to. This is required if rotator_mode is set to random.

sequential_repeat_clicks
string
Enum: "same_url" "next_url"

When repeat clicks come in for the sequential Rotator, where should they be redirected to. This is required if rotator_mode is set to sequential.

spillover_repeat_clicks
string
Enum: "backup_url" "last_url" "top_of_rotator"

When repeat clicks come in for the spillover Rotator, where should they be redirected to. This is required if rotator_mode is set to spillover.

spillover_randomize
integer <int32>

This setting is only for Spillover Rotators. If set, it 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. To unset this value, set it to nothing, e.g., spillover_randomize=&....

spillover_randomize_last_url
boolean
Default: true

If the Rotator is a Spillover Rotator and 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.

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 <= 255 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 <= 255 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 &lt;script&gt; .. &lt;/script&gt; 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 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 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 American 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.

If you use this parameter, all clicks from countries that explicitly excluded 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.

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 -X PATCH -H "apikey: YOURAPIKEY" https://api.clickmagick.com/v1/rotators/12345 -d "rotator_name=test2"

Response samples

Content type
application/json
{
  • "status": "OK",
  • "errors": [ ],
  • "warnings": [ ]
}

Generate stats for one or more Rotators

Get the stats for one or more Rotators by Rotator ID.

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

start_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ for the starting date and time of the time range for the Rotator stats. Must be used in conjunction with end_time.

end_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ for the ending date and time of the time range for the Rotator stats. Must be used in conjunction with start_time.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

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.

Authorizations:
apikey
path Parameters
report_id
required
integer <int32> >= 1
Example: 3752921

The report id for this request.

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "last_updated": "2025-10-22T18:38:59Z",
  • "stats": [
    ],
  • "total_seconds": 39,
  • "progress": {
    },
  • "errors": [
    ],
  • "status": "OK",
  • "warnings": [
    ]
}

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
status
string
Enum: "all_urls" "active_urls" "paused_urls" "archived_urls" "all_but_archived"

Restrict the URLs with the specified status.

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.

Responses

Request samples 

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": [
    ],
  • "cursor": {
    },
  • "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

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.

max_clicks
integer <int32> >= 1
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> >= 0

The maximum number of unique clicks to send to this Rotator per day. If not specified, it defaults to "unlimited".

bonus
integer <int32> [ 0 .. 100 ]
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 ]
Default: 0

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.

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 &lt;script&gt; .. &lt;/script&gt; tags.

start_time
string <datetime>

The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to start sending traffic to this Rotator URL.

end_time
string <datetime>

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

If you use this parameter, all clicks that are explicitly excluded 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 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: true

If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered.

notes
string

Notes that you would like to track for this link.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

Get the settings for one or more Rotator URLs

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

Authorizations:
apikey
query Parameters
id
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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/rotators/urls/settings?id=358792&id=...

Response samples

Content type
application/json
{
  • "rotator_urls": [
    ],
  • "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 -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
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
string

The URL to deliver clicks to.

position
integer <int32> >= 1

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.

max_clicks
integer <int32> >= 1
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> >= 0
Default: 0

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 .. 100 ]
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 ]
Default: 0

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 &lt;script&gt; .. &lt;/script&gt; tags. To clear pixels if it already has a value, set it to nothing, e.g., pixels=&....

start_time
string <datetime>

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

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

If you use this parameter, all clicks that are explicitly excluded 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 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: true

If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered.

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 -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": [ ]
}

Generate stats for one or more Rotator URLs

Get the stats for one or more Rotator URLs by Rotator URL ID.

Authorizations:
apikey
Request Body schema: application/x-www-form-urlencoded
id
required
Array of integers <int32>

Pass in one or more Rotator URL IDs.

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 YYYY-MM-DDTHH:MM:SSZ for the starting date and time of the time range for the link stats. Must be used in conjunction with end_time.

end_time
string <date-time>

The ISO-8601 timestamp YYYY-MM-DDTHH:MM:SSZ 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.

time_zone
string

To accurately determine the number of clicks received for clicks_today, we need the time zone for the day representing "today". Pass in the tz database time zone string, such as America/New_York. You can also pass offsets such as -04:00 as well. If you don't pass in this time zone, the time zone in the User Settings of the ClickMagick account will be used.

Responses

Request samples 

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

Response samples

Content type
application/json
{}

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.

Authorizations:
apikey
path Parameters
report_id
required
integer <int32> >= 1
Example: 3752921

The report id for this request.

Responses

Request samples 

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": "2025-10-22T18:38:59Z",
  • "stats": [
    ],
  • "total_seconds": 39,
  • "progress": {
    },
  • "errors": [
    ],
  • "status": "OK",
  • "warnings": [
    ]
}

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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/domains

Response samples

Content type
application/json
{
  • "domains": [
    ],
  • "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 <= 255 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 -X POST -H "X-APIKEY: YOURAPIKEY" https://dev-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 -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 & Rotator Groups

Return a list of available Link & Rotator Groups.

Authorizations:
apikey

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "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 -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 -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 -X DELETE -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/links/groups?group_id=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 -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 -X GET -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/rotators/groups

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "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 -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 -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 Links 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 -X DELETE -H "X-APIKEY: YOURAPIKEY" https://api.clickmagick.com/v1/rotators/groups?group_id=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 

 Response samples 
Content type
application/json
{
  • "errors": [ ],
  • "settings": {
    },
  • "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 blocks 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 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 American 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.


If you use this parameter, all clicks that are explcitly excluded will be redirected through the blocked_countries_url.


You can find a full list of two-letter country codes in the International Banking (IBAN) Country Code List.


blocked_countries_url
string
 
If set, blocked country clicks are redirected to this URL.


clickbank_secret_key
string
 Default:  null
 
If you want your account to receive and process ClickBank Instant Notifications, you need to set your ClickBank secret key here.


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
 Default:  null
 
The URL to the custom logo if the public_logo_type is set to custom_logo.


custom_logo_link_url
string
 Default:  null
 
If the custom logo is clicked on, the browser will be redirected to this URL.


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
 
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" 
 
notify_conversions
boolean
 Default:  false
 
Receive a notification by email each time you make a sale.


notify_split
boolean
 Default:  false
 
Receive a notification by email when you have a statistically valid Split Test winner.


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 
 Response samples 
Content type
application/json
{
  • "errors": [ ],
  • "status": "OK",
  • "warnings": [ ]
}