openapi: 3.0.1 info: title: ClickMagick API description: > 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. For AI assistants and API tools, the full OpenAPI spec is at https://api.clickmagick.com/docs/openapi.yaml, and getting-started notes are at https://api.clickmagick.com/llms.txt. termsOfService: https://www.clickmagick.com/terms/ contact: name: API Support url: https://www.clickmagick.com/ license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: '1.0' servers: - url: https://api.clickmagick.com/v1 security: - apikey: [] tags: - name: Projects description: > 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. - name: Project Logs description: > These are the action, engagement, and sales conversion logs for your Projects. - name: Smart Links description: | Smart Links are like bitly links - but smarter. - name: Rotators description: > Rotators allow you to take a single link and distribute incoming clicks across multiple destination URLs. - name: Rotator URLs description: > Every Rotator has a list of Rotator URLs that it distributes clicks to. Use these endpoints to manage the URLs for a specific Rotator. - name: Custom Domains description: > Use these endpoints to manage the Custom Domains for your Smart Links and Rotators. - name: Groups description: > 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. - name: User Settings description: > User settings allow you to modify the global default values for your Projects, Smart Links, and Rotators. paths: /campaigns/projects: get: tags: - Projects summary: Get a list of Projects and their IDs description: | Get a list of Projects and their IDs. operationId: getProjects x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects" parameters: - name: search in: query description: > 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. schema: type: string format: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignProjectList' example: projects: - id: 29583 name: Bigfoot Surfboards status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Projects summary: Create a New Project description: | Create a new Project. operationId: createCampaignsProject x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects" -d "name=example.com" requestBody: content: application/x-www-form-urlencoded: schema: required: - name properties: name: type: string description: > The unique "friendly name" for this project. You can use letters, numbers, underscores, periods, dashes, and spaces. time_zone: type: string default: The `time_zone` in your User Settings. description: > 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) currency: type: string minLength: 3 maxLength: 3 default: The currency setting in User Settings description: > 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](https://www.iban.com/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: type: string default: not set description: > 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: type: boolean default: false description: > Set to `true` if Cost Of Goods Sold (COGS) values should be used in computing stats for this Project. attribution_window: type: integer minimum: 1 default: forever description: > 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. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: 29583 errors: [] status: OK warnings: [] '429': $ref: '#/components/responses/429' /campaigns/projects/settings: get: tags: - Projects summary: Get the settings for one or more Projects description: | Get the settings for one or more Projects by ID. operationId: getCampaignProjectSettings x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/settings?id=29583&id=29584" parameters: - name: id in: query description: > To get the settings for one or more Projects, pass in a single `id` value, or multiple `id` values. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignProjectSettings' example: projects: - created: 2026-09-20T19:51:26Z currency: AUD id: 29583 name: Bigfoot Surfboards project_domain: surf.example.com time_zone: Australia/Sydney use_cogs: true status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /campaigns/projects/utms: get: tags: - Projects summary: Get the UTM values used with a Project description: | Get the UTM values used in clicks to a Project. operationId: getCampaignProjectUtms x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/utms?id=29583&start_time=2026-10-16T10:44:14Z&end_time=2026-10-17T19:37:02Z" parameters: - name: id in: query description: | The ID of the Project. required: true schema: minimum: 0 type: integer format: int32 - name: start_time in: query description: > 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. required: false schema: type: string format: date-time - name: end_time in: query description: > 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`. required: false schema: type: string format: date-time responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignProjectUtms' example: utm: source: - google - facebook medium: - cpc campaign: - spring-sale - summer-sale term: [] content: [] status: OK '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}: delete: tags: - Projects summary: Delete a Project description: > Permanently delete a Project and all of its associated clicks, actions, engagements, and sales. operationId: deleteCampaignProject x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583" parameters: - $ref: '#/components/parameters/project_id' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Projects summary: Edit the settings of a Project description: | Edit the settings of a Project. operationId: updateCampaignProject x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583" -d "time_zone=Australia/Sydney" parameters: - name: project_id in: path description: | The ID of the project to update. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: properties: time_zone: type: string description: > 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) currency: type: string minLength: 3 maxLength: 3 description: > 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](https://www.iban.com/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: type: string description: > 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: type: boolean description: > Set to `true` if Cost Of Goods Sold (COGS) values should be used in computing stats for this project. attribution_window: type: integer minimum: 1 description: > 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=`. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/stats: post: operationId: getCampaignStats tags: - Projects summary: Create a stats report for a Project description: > 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](#operation/getCampaignStatsByModel). This call returns a report `id` and `url`; poll that url with `GET /campaigns/projects/stats/reports/{report_id}` until the report has been generated. x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/stats" -d "utm_source=google" parameters: - $ref: '#/components/parameters/project_id' requestBody: $ref: '#/components/requestBodies/getCampaignStatsByModel' responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/stats/{attribution_model}: post: operationId: getCampaignStatsByModel tags: - Projects summary: Create a stats report for a Project using a specific model description: > Create a stats report for a Project using a specific attribution model. This call returns a report `id` and `url`; poll that url with `GET /campaigns/projects/stats/reports/{report_id}` until the report has been generated. x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/stats/linear" -d "utm_source=google" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/attribution_model' requestBody: $ref: '#/components/requestBodies/getCampaignStatsByModel' responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /campaigns/projects/stats/reports/{report_id}: get: operationId: getCampaignStatsReport tags: - Projects summary: Retrieve a stats report description: | 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. Most reports are ready in well under a second. Poll on this schedule: 1. Wait 250 milliseconds after creating the report, then check it. 2. If it isn't ready, wait 500 milliseconds and check again. 3. After that, check once a second. 4. If it still isn't ready after 30 seconds, check every 5 seconds. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/stats/reports/3752921" parameters: - $ref: '#/components/parameters/report_id' responses: '200': description: Report is ready content: application/json: schema: $ref: '#/components/schemas/CampaignProjectStatsReport' '202': $ref: '#/components/responses/GetReportProgress' '429': $ref: '#/components/responses/429' /visitor-profile: get: operationId: getVisitorProfile tags: - Projects summary: Get a Visitor Profile description: > Returns a single visitor's identity profile plus a unified, time-sorted log of their clicks and conversions — the same information shown by the Visitor Profile tool in the ClickMagick app. Look a visitor up by their Visitor ID (e.g. `cmc1234567890`) or by their email address, using the `search` parameter. The `events` log is returned oldest-first (chronological order) by default and is paged like the other log endpoints. The `visitor` summary — including `total_orders` and `lifetime_value` — is computed over the visitor's entire history and is returned on every page. x-codeSamples: - lang: curl label: By Visitor ID source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/visitor-profile?search=cmc1234567890" - lang: curl label: By email address source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/visitor-profile?search=john.doe@example.com" parameters: - name: search in: query required: true schema: type: string description: > A Visitor ID (e.g. `cmc1234567890`) or an email address (e.g. `john.doe@example.com`) to look up. example: cmc1234567890 - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - name: sort_direction in: query schema: type: string enum: - asc - desc default: asc description: > The order of the `events` log by timestamp. Defaults to `asc` (oldest first, chronological). responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/VisitorProfileResponse' '429': $ref: '#/components/responses/429' /campaigns/actions: get: operationId: getAllCampaignActions tags: - Project Logs summary: Get Actions for all Projects description: > 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](#operation/getAllCampaignActionsByModel). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/actions?limit=1" parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignActions' '429': $ref: '#/components/responses/429' /campaigns/actions/{attribution_model}: get: operationId: getAllCampaignActionsByModel tags: - Project Logs summary: Get Actions for all Projects using a specific model description: | Get actions for all Projects using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/actions/linear?limit=1" parameters: - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignActions' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/actions: get: operationId: getActions tags: - Project Logs summary: Get Actions for a Project description: > 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](#operation/getActionsByModel). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/actions?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignActions' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/actions/{attribution_model}: get: operationId: getActionsByModel tags: - Project Logs summary: | Get Actions for a Project using a specific model description: | Get actions for a specific Project using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/actions/linear?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignActions' '429': $ref: '#/components/responses/429' /campaigns/engagements: get: operationId: getAllCampaignEngagements tags: - Project Logs summary: Get Engagements for all Projects description: > 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](#operation/getAllProjectEngagementsByModel). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/engagements?limit=1" parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignEngages' '429': $ref: '#/components/responses/429' /campaigns/engagements/{attribution_model}: get: operationId: getAllProjectEngagementsByModel tags: - Project Logs summary: Get Engagements for all Projects using a specific model description: | Get engagements for all Projects using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/engagements/linear?limit=1" parameters: - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignEngages' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/engagements: get: operationId: getProjectEngagements tags: - Project Logs summary: Get Engagements for a Project description: > 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](#operation/getEngagements). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/engagements?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignEngages' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/engagements/{attribution_model}: get: operationId: getEngagements tags: - Project Logs summary: | Get Engagements for a Project using a specific model description: > Get engagements for a specific Project using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/engagements/linear?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignEngages' '429': $ref: '#/components/responses/429' /campaigns/sales: get: operationId: getAllCampaignSales tags: - Project Logs summary: Get Sales for all Projects description: > 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](#operation/getAllCampaignSalesByModel). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/sales?limit=1" parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignSales' '429': $ref: '#/components/responses/429' /campaigns/sales/{attribution_model}: get: operationId: getAllCampaignSalesByModel tags: - Project Logs summary: Get Sales for all Projects using a specific model description: | Get sales for all Projects using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/sales/linear?limit=1" parameters: - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignSales' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/sales: get: operationId: getSales tags: - Project Logs summary: Get Sales for a Project description: > 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](#operation/getSalesByModel). Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/sales?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignSales' '429': $ref: '#/components/responses/429' /campaigns/projects/{project_id}/sales/{attribution_model}: get: operationId: getSalesByModel tags: - Project Logs summary: | Get sales for a Project using a specific model description: | Get sales for a specific Project using a specific attribution model. Results are not returned in any specified order. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/projects/29583/sales/linear?limit=1" parameters: - $ref: '#/components/parameters/project_id' - $ref: '#/components/parameters/attribution_model' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start_time' - $ref: '#/components/parameters/end_time' - $ref: '#/components/parameters/utm_source' - $ref: '#/components/parameters/utm_medium' - $ref: '#/components/parameters/utm_campaign' - $ref: '#/components/parameters/utm_term' - $ref: '#/components/parameters/utm_content' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignSales' '429': $ref: '#/components/responses/429' /campaigns/urls: get: tags: - Projects summary: Get URLs built using the URL Builder description: > Get a list of the UTM-powered URLs that were built using the URL Builder. operationId: getCampaignUrls x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/campaigns/urls" parameters: - $ref: '#/components/parameters/limit' - name: cursor in: query description: > 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. schema: type: string format: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CampaignUrls' example: urls: - notes: null url: >- https://example.com?utm_source=facebook&utm_medium=social&utm_campaign=xbox cursor: next: ZBDkPOxCKRi prev: ODM3MjYyMTE status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /domains: get: tags: - Custom Domains summary: Get all Custom Domains description: > 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](https://www.clickmagick.com/kb/?answer=140). operationId: getDomains x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains" responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Domains' example: domains: - id: 49735 domain: example.com type: link setup: cname error_url: null status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Custom Domains summary: Create a Custom Domain description: > 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](https://www.clickmagick.com/kb/?answer=140). operationId: createDomain x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains" -d "domain=example.com&type=link" requestBody: content: application/x-www-form-urlencoded: schema: required: - domain - type properties: domain: maxLength: 255 type: string description: | The domain name to use as a custom domain. type: type: string description: | The type of tracking to use this custom domain for. enum: - link - rotator error_url: maxLength: 2048 type: string description: > 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. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DomainCreated' example: id: 49735 status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /domains/{domain_id}: delete: tags: - Custom Domains summary: Delete a Custom Domain description: > 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](https://www.clickmagick.com/kb/?answer=140). operationId: deleteDomain x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/domains/49735" parameters: - name: domain_id in: path description: | The ID of the domain to permanently delete. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links/groups: get: tags: - Groups summary: Get a list of Link Groups description: | Return a list of your Link Groups and their subgroups. operationId: getLinkGroups x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups" responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LinkGroups' example: groups: - id: 27395 name: Gardening subgroups: - id: 14273 name: Composters status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Groups summary: Create a Link Group description: > Create a new Smart Link Group that can be used for organizing your Links. operationId: createLinkGroup x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups" -d "name=Gardening" requestBody: content: application/x-www-form-urlencoded: schema: required: - name properties: name: type: string description: | The name of the Link Group to create. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: 27395 status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Groups summary: Rename a Link Group description: | Rename an existing Smart Link group or subgroup. operationId: updateLinkGroup x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups?group_id=27395&name=Gardening" parameters: - name: name in: query description: | The new name of the group or subgroup. required: true schema: type: string - name: group_id in: query description: | The ID of the top-level Group. required: true schema: minimum: 0 type: integer format: int32 - name: subgroup_id in: query description: > If you're renaming a subgroup, pass both the `group_id` and the `subgroup_id`. required: false schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links/groups/{group_id}: delete: tags: - Groups summary: Delete a Link Group description: > 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. operationId: deleteLinkGroup x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups/27395?subgroup_id=14273" parameters: - name: group_id in: path description: | The ID of the top-level Smart Link group. required: true schema: minimum: 0 type: integer format: int32 - name: subgroup_id in: query description: | If you're deleting a subgroup, pass in the additional `subgroup_id`. required: false schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links/groups/{group_id}/subgroups: post: tags: - Groups summary: Create a Link Subgroup description: | Create a new Smart Link subgroup. operationId: createLinkSubgroup x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/groups/27395/subgroups" -d "name=Composters" parameters: - name: group_id in: path description: | The Group ID that this new subgroup should be added to. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: required: - name properties: name: type: string description: | The name of the subgroup to create. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: 14273 status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/groups: get: tags: - Groups summary: Get a list of Rotator Groups description: > Return a list of Rotator Groups. Unlike Smart Link Groups, Rotator Groups do not have Subgroups. operationId: getRotatorGroups x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups" responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorGroups' example: groups: - id: 27395 name: Weightloss status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Groups summary: Create a Rotator Group description: | Create a new Rotator Group. operationId: createRotatorGroup x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups" -d "name=Weightloss" requestBody: content: application/x-www-form-urlencoded: schema: required: - name properties: name: type: string description: | The name of the Rotator Group to create. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: 27395 status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Groups summary: Rename a Rotator Group description: | Rename an existing Rotator group. operationId: updateRotatorGroup x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups?group_id=27395&name=Weightloss" parameters: - name: name in: query description: | The new name of the group. required: true schema: type: string - name: group_id in: query description: | The ID of the Rotator roup. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/groups/{group_id}: delete: tags: - Groups summary: Delete a Rotator Group description: > Delete an existing Rotator group. All affected Rotators will be assigned to the default "All" Group. operationId: deleteRotatorGroup x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/groups/27395" parameters: - name: group_id in: path description: | The ID of the rotator group. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links: get: tags: - Smart Links summary: Get a list of Smart Links and their IDs description: > Retrieve a list of your Smart Links and IDs. For more information on Smart Links, please see the [knowledgebase](https://www.clickmagick.com/kb/?cat=102). operationId: getLinks x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links?limit=1" parameters: - name: cursor in: query description: > Pass in the previous page's cursor `next` or `prev` response value to retrieve the next page or previous page of data. This allows you to move through the data either forward or backward. If no `cursor` is specified, the first page of data is returned. schema: type: string format: string - name: group_id in: query description: > If you provide a top-level `group_id`, then only links in that top-level group are returned and none from any subgroups, unless a `subgroup_id` is passed in or `recursive` is `true`. schema: type: integer format: int32 - name: include_archived in: query description: Include archived links in the results or not. schema: type: boolean default: false - $ref: '#/components/parameters/limit' - name: recursive in: query description: > Return Smart Links for the group specified by `group_id` and all of the subgroups of that group. schema: type: boolean default: false - name: subgroup_id in: query description: > Return only the links in the subgroup specified by the `subgroup_id`. You must pass in the corresponding parent `group_id` if you pass in a `subgroup_id`. schema: type: integer format: int32 - name: search in: query description: | Only include links where their `link_name` includes this string. schema: type: string format: string - name: sort_direction in: query description: > Specify how links should be sorted: `alpha` for alphabetical order, `oldest_first` for ordering the oldest-created links first, and `newest_first` which orders the most recently created links first. schema: type: string format: string default: newest_first enum: - alpha - newest_first - oldest_first responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LinksList' example: cursor: next: ZBDkPOxCKRi prev: ODM3MjYyMTE errors: [] links: - archived: false group_id: 18365 id: 1731254 link_name: Callaway Golf Bags link_slug: golfbags subgroup_id: 10435 status: OK warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Smart Links summary: Create a Smart Link description: | Create a new Smart Link. operationId: createLink x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links" -d "primary_url=https://www.example.com/" requestBody: content: application/x-www-form-urlencoded: schema: required: - primary_url properties: backup_url: maxLength: 2048 type: string description: > The URL that clicks will be redirected to if they can't be redirected to any other URL in the link settings. For example, if the `max_clicks` setting for this link has been reached, or you have geotargetting set up and the setting doesn't match the click. blank_referrer: description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. type: string default: 'false' enum: - 'true' - 'false' cost: type: number description: > The cost of your clicks, if known in advance. Must be greater than 0 if `cost_type` is set to anything other than `no_cost_type`. format: float default: 0 cost_type: type: string description: | The type of cost for this Smart Link. enum: - no_cost_type - one_time_cost - cost_per_click - daily - monthly default: no_cost_type domain_id: minimum: 0 type: integer description: > If you have any custom tracking domains set up to use with your Smart Links, you can use any of those domains at any time with any of your Smart Links. This `domain_id` setting simply specifies your _preferred_ domain for this particular Smart Link. This is useful in the UI, for example, when ClickMagick needs to copy a Smart Link to the clipboard. It will use this domain in the Smart Link rather than another domain that you might have set up. format: int32 default: 0 exclude_country: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this link, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: type: string description: > An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Smart Link 30 times in one minute or clicking 30 different Smart Links within one minute. Setting this to `flag` will send these clicks through to your Smart Link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing include_country: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this link, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). ios_url: maxLength: 2048 type: string description: > If the click is from an iOS device, clicks will be redirected to this URL instead of to the `primary_url`. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices. link_group: minimum: 0 type: integer description: > The ID of the group to organize this link under. If you specify `link_group`, you must also specify `link_subgroup`. If you don't want the link associated with any group, set `link_group` to 0, or don't specify it at all. format: int32 default: 0 link_name: maxLength: 32 minLength: 4 type: string description: > The unique "friendly name" of this link. In the UI, if this is not specified, the `link_slug` is displayed instead. Link names cannot include these special characters: : & | ; $ % @ " ' < > ( ) + , \ link_slug: maxLength: 20 minLength: 4 type: string description: > A unique identifier used as part of the Smart Link, e.g., `https://clkmg.com//`. If not set, a random slug like `1pk3wb` will be generated for you. Although not required, you'll generally want to set this to a human-readable value such as `golfbags`. Letters, numbers, and hyphens are allowed, but no spaces. link_subgroup: minimum: 0 type: integer description: > The ID of the subgroup to organize this link under. If you specify `link_subgroup`, you must also specify `link_group`. If you don't want the link in a subgroup, set `link_subgroup` to 0. format: int32 default: 0 max_clicks: type: integer format: int32 minimum: 1 maximum: 999999 description: > If specified, this is the maximum number of clicks to redirect through the Smart Link. All additional clicks will then be redirected through the `backup_url`. If you set `max_clicks`, you must also set `backup_url`. mobile_url: maxLength: 2048 type: string description: > The URL that clicks from mobile devices will be redirected to instead of to the `primary_url`. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`. notes: maxLength: 1024 type: string description: | Notes that you would like to keep for this link. password: maxLength: 20 type: string description: > Setting a password will display a generic login page that the user must enter the password to continue. pixels: maxLength: 2560 type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. primary_url: maxLength: 2048 type: string description: | The primary URL to deliver clicks to. repeat_on_primary_url: description: > Redirect visitors to the `repeat_url` if the visitor has ever been redirected to the same `primary_url` even if it was from a different Smart Link. type: string default: 'false' enum: - 'true' - 'false' repeat_url: maxLength: 2048 type: string description: > Repeat clicks from the same visitor will be redirected to this URL. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LinkResponse' example: errors: [] id: 1731254 public_stats_url: https://www.clickmagick.com/share/002f6ed01a6ab6 status: OK warnings: [] '429': $ref: '#/components/responses/429' /links/settings: get: tags: - Smart Links summary: Get the settings for one or more Smart Links description: | Get the settings for one or more Smart Links by ID. operationId: getLinkSettings x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/settings?id=1731254&id=1731255" parameters: - name: id in: query description: > To get the settings of one or more Smart Links, pass in a single `id` value, or multiple `id` values. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/LinkSettings' example: links: - archived: false backup_url: null blank_referrers: false cost: 0.54 cost_type: cost_per_click created: 2026-09-20T19:51:26Z domain_id: 49735 exclude_countries: - NG filter_abuser: nothing filter_anon: flag filter_bot: flag filter_server: flag filter_spider: flag filter_user: flag has_split_urls: false id: 1731254 include_countries: [] ios_url: null last_click: 2026-09-20T20:51:26Z last_reset: 2026-10-10T15:17:50Z link_group: 27395 link_name: Callaway Golf Bags link_slug: golfbags link_subgroup: null max_clicks: null mobile_url: null notes: null password: null pixels: null primary_url: https://example.com public_stats_url: https://www.clickmagick.com/share/002f6ed01a6ab6 repeat_primary_url: false repeat_url: null split_type: epc status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links/{link_id}: delete: tags: - Smart Links summary: Delete a Smart Link description: | Permanently delete a Smart Link and all of its associated clicks. operationId: deleteLink x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/1731254" parameters: - name: link_id in: path description: | The ID of the Link to delete. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Smart Links summary: Edit a Smart Link description: | Edit an existing Smart Link. operationId: updateLink x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/12345" -d "link_name=Example Test" parameters: - name: link_id in: path description: | The ID of the Link to update. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: properties: primary_url: maxLength: 2048 type: string description: | The primary URL to deliver clicks to. It cannot be cleared. link_slug: maxLength: 20 minLength: 4 type: string description: > A unique identifier used as part of the Smart Link, e.g., `https://clkmg.com//`. Pass it empty, e.g., `link_slug=&...`, to replace the current slug with a random one like `1pk3wb`. We recommend using a human-readable value such as `golfbags`. Letters, numbers, and hyphens are allowed, but no spaces. link_name: maxLength: 32 minLength: 4 type: string description: > The unique "friendly name" of this link. In the UI, if this is not specified, the `link_slug` is displayed instead. To unset this value, set it to nothing, e.g., `link_name=&...`. Link names cannot include these special characters: : & | ; $ % @ " ' < > ( ) + , \ domain_id: minimum: 0 type: integer description: > If you have any custom tracking domains set up to use with your Smart Links, you can use any of those domains at any time with any of your Smart Links. This `domain_id` setting simply specifies your _preferred_ domain for this particular Smart Link. This is useful in the UI, for example, when ClickMagick needs to copy a Smart Link to the clipboard. It will use this domain in the Smart Link rather than another domain that you might have set up. format: int32 default: 0 link_group: minimum: 0 type: integer description: > The ID of the group to organize this link under. If you specify `link_group`, you must also specify `link_subgroup`. If you don't want the link associated with any group, set `link_group` to 0, or set it to nothing, e.g., `link_group=&...`. format: int32 default: 0 link_subgroup: minimum: 0 type: integer description: > The ID of the subgroup to organize this link under. If you specify `link_subgroup`, you must also specify `link_group`. If you don't want the link in a subgroup, set `link_subgroup` to 0, or set it to nothing, e.g., `link_subgroup=&...`. format: int32 default: 0 archived: type: boolean description: > Indicates if this link is archived. You can still send traffic to this link, but the link won't show up with other links in the UI unless you're viewing the "Archived Links" view. default: false pixels: maxLength: 2560 type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To unset this value, set it to nothing, e.g., `pixels=&...`. cost: type: number description: > The cost of your clicks, if known in advance. Must be greater than 0 if `cost_type` is set to anything other than `no_cost_type`. To unset this value, set it to nothing, e.g., `cost=&...` and set `cost_type` to `no_cost_type`. format: float default: 0 cost_type: type: string description: > The type of cost for this Smart Link. `cost` and `cost_type` must be sent together. enum: - no_cost_type - one_time_cost - cost_per_click - daily - monthly backup_url: maxLength: 2048 type: string description: > The URL that clicks will be redirected to if they can't be redirected to any other URL in the link settings. For example, if the `max_clicks` setting for this link has been reached, or you have geotargetting set up and the setting doesn't match the click. To unset this value, set it to nothing, e.g., `backup_url=&...`. mobile_url: maxLength: 2048 type: string description: > The URL that clicks from mobile devices will be redirected to instead of to the `primary_url`. If you don't want clicks from iOS devices to go to this URL, then specify an `ios_url`. To unset this value, set it to nothing, e.g., `mobile_url=&...`. ios_url: maxLength: 2048 type: string description: > If the click is from an iOS device, clicks will be redirected to this URL instead of to the `primary_url`. Clicks from iOS devices will automatically be redirected to the URL in the `mobile_url` setting if `ios_url` is not specified. To set `ios_url`, you must set the `mobile_url` to redirect to non-iOS mobile devices. To unset this value, set it to nothing, e.g., `ios_url=&...`. repeat_url: maxLength: 2048 type: string description: > Repeat clicks from the same visitor will be redirected to this URL. To unset this value, set it to nothing, e.g., `repeat_url=&...`. repeat_on_primary_url: type: boolean description: > Redirect visitors to the `repeat_url` if the visitor has ever been redirected to the same `primary_url` even if it was from a different Smart Link. default: false include_country: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this link, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). exclude_country: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this link, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: type: string description: > An "abuser" is a user who exhibits abnormal and suspicious click patterns, such as clicking the same Smart Link 30 times in one minute or clicking 30 different Smart Links within one minute. Setting this to `flag` will send these clicks through to your Smart Link but their click counts will be separated from your main stats. Setting this to `block` will send the click to a generic error page. Setting this to `nothing` will treat these clicks as real clicks. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing max_clicks: type: integer format: int32 minimum: 1 maximum: 999999 description: > If specified, this is the maximum number of clicks to redirect through the Smart Link. All additional clicks will then be redirected through the `backup_url`. If you set `max_clicks`, you must also set `backup_url`. To unset this value, set it to nothing, e.g., `max_clicks=&...`. blank_referrer: type: string description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. default: false password: maxLength: 20 type: string description: > Setting a password will display a generic login page that the user must enter the password to continue. To unset this value, set it to nothing, e.g., `password=&...`. notes: maxLength: 1024 type: string description: > Notes that you would like to track for this link. To unset this value, set it to nothing, e.g., `notes=&...`. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /links/stats: post: tags: - Smart Links summary: Create a stats report for one or more Smart Links description: > Create a stats report for one or more Smart Links by Smart Link ID. This call returns a report `id` and `url`; poll that url with `GET /links/stats/reports/{report_id}` until the report has been generated. operationId: getTrackingLinkStats x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/stats" -d "id=1731254&id=1731255" requestBody: content: application/x-www-form-urlencoded: schema: required: - id properties: id: type: array items: type: integer format: int32 description: > Pass in one or more Smart Link IDs, up to a maximum of 20. For example: id=12345&id=12346&id=12347 start_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. end_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /links/stats/reports/{report_id}: get: tags: - Smart Links summary: Poll for the specified Smart Links stats report description: > Poll for the specified links stats report. If the report is still being generated, a `202` status will be returned with the progress of how much of the report has been generated. Once the report has been generated, a `200` status will be returned with the stats. Most reports are ready in well under a second. Poll on this schedule: 1. Wait 250 milliseconds after creating the report, then check it. 2. If it isn't ready, wait 500 milliseconds and check again. 3. After that, check once a second. 4. If it still isn't ready after 30 seconds, check every 5 seconds. operationId: getLinksStatsReport x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/stats/reports/3752921" parameters: - $ref: '#/components/parameters/report_id' responses: '200': description: Report is ready content: application/json: schema: $ref: '#/components/schemas/LinkStatsReport' '202': $ref: '#/components/responses/GetReportProgress' '429': $ref: '#/components/responses/429' /links/subids/stats: post: tags: - Smart Links summary: Generate a Sub-ID stats report for one or more Smart Links description: > Generate a report of stats grouped by a Sub-ID (`s1`–`s5`) across one or more Smart Links. Stats are aggregated across all the links you pass in, returning one row per distinct Sub-ID value with total clicks, unique clicks, revenue, and EPC. This is an asynchronous report. This call returns a report `id` and `url`; poll that url with `GET /links/subids/stats/reports/{report_id}` until the report has been generated. operationId: getLinkSubIdStats x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/subids/stats" -d "id=1731254&id=1731255&subid=1" requestBody: content: application/x-www-form-urlencoded: schema: required: - id - subid properties: id: type: array items: type: integer format: int32 maxItems: 20 description: > Pass in one or more Smart Link IDs, up to a maximum of 20. For example: id=12345&id=12346&id=12347. Stats are aggregated across all the links you pass in. subid: type: integer enum: - 1 - 2 - 3 - 4 - 5 description: > Which Sub-ID position to group the stats by — `1` through `5`. start_time: type: string format: date-time description: > The ISO-8601 timestamp `YYYY-MM-DDTHH:MM:SSZ` for the starting date and time of the time range. Must be used in conjunction with `end_time`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. end_time: type: string format: date-time description: > The ISO-8601 timestamp `YYYY-MM-DDTHH:MM:SSZ` for the ending date and time of the time range. Must be used in conjunction with `start_time`. The `HH:MM:SS` for an `end_time` is normally `23:59:59`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /links/subids/stats/reports/{report_id}: get: tags: - Smart Links summary: Poll for the specified Smart Link Sub-ID stats report description: > Poll for the specified Sub-ID stats report. If the report is still being generated, a `202` status will be returned with the progress of how much of the report has been generated. Once the report has been generated, a `200` status will be returned with the stats. Most reports are ready in well under a second. Poll on this schedule: 1. Wait 250 milliseconds after creating the report, then check it. 2. If it isn't ready, wait 500 milliseconds and check again. 3. After that, check once a second. 4. If it still isn't ready after 30 seconds, check every 5 seconds. operationId: getLinkSubIdStatsReport x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/links/subids/stats/reports/3752921" parameters: - $ref: '#/components/parameters/report_id' responses: '200': description: Report is ready content: application/json: schema: $ref: '#/components/schemas/SubIdStatsReport' '202': $ref: '#/components/responses/GetReportProgress' '429': $ref: '#/components/responses/429' /rotators: get: tags: - Rotators summary: Get a List of Rotators description: | Get a list of your rotators. For more information on rotators, please see the [knowledgebase](https://www.clickmagick.com/kb/?cat=104). operationId: getRotators x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators?limit=1" parameters: - $ref: '#/components/parameters/limit' - name: group_id in: query description: > If you provide a `group_id`, then only rotators in that group are returned. schema: type: integer format: int32 - $ref: '#/components/parameters/cursor' - name: sort_direction in: query description: > 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. schema: type: string format: string default: newest_first enum: - alpha - newest_first - oldest_first - name: search in: query description: > Only include rotators where their `rotator_name` includes this string. For rotators with no `rotator_name`, the `rotator_slug` is searched instead. schema: type: string format: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorList' example: rotators: - id: 128364 rotator_mode: spillover rotator_name: Health-related Traffic rotator_slug: healthtraffic cursor: next: ZBDkPOxCKRi prev: ODM3MjYyMTE status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Rotators summary: Create a New Rotator description: | Create a new rotator. For more information on rotators, please see the [knowledgebase](https://www.clickmagick.com/kb/?cat=104). operationId: createRotator x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators" -d "rotator_slug=healthtraffic&rotator_mode=spillover&backup_url=https://www.example.com/backup" requestBody: content: application/x-www-form-urlencoded: schema: required: - rotator_slug - rotator_mode - backup_url properties: rotator_slug: maxLength: 20 minLength: 4 type: string description: > A unique identifier used as part of the Rotator link, e.g., `https://clkmr.com//`. We recommend using a human-readable value such as `healthtraffic`. Letters, numbers, and dashes are allowed, but no spaces. rotator_name: maxLength: 32 minLength: 4 type: string description: > 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: minimum: 0 type: integer description: > 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. format: int32 default: 0 rotator_group: minimum: 0 type: integer format: int32 description: > The ID of the group to organize this Rotator under. If not specified, the 'All' group will be used. rotator_mode: type: string enum: - fulfillment - spillover - random - sequential description: > 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?](https://www.clickmagick.com/kb/?article=28) random_repeat_clicks: type: string enum: - same_url - random_url description: > Where repeat clicks should be redirected when they come in for a `random` Rotator. Defaults to `same_url`. This can only be set for `random` Rotators. sequential_repeat_clicks: type: string enum: - same_url - next_url description: > Where repeat clicks should be redirected when they come in for a `sequential` Rotator. Defaults to `same_url`. This can only be set for `sequential` Rotators. spillover_repeat_clicks: type: string enum: - backup_url - last_url - top_of_rotator description: > Where repeat clicks should be redirected when they come in for a `spillover` Rotator. Defaults to `backup_url`. This can only be set for `spillover` Rotators. spillover_randomize: type: integer format: int32 description: > If set, this is the number of minutes that ClickMagick should wait before randomly shuffling all of the Rotator's URLs. This random shuffling is useful at times because clicks are always delivered starting with the Rotator URL that's in the first position, and then down from there. Shuffling causes the URLs to get different priorities after they have been shuffled. If you don't specify anything for this setting, no shuffling occurs. This can only be set for `spillover` Rotators. spillover_randomize_last_url: type: boolean default: true description: > If `spillover_randomize` is set so that the URLs are shuffled regularly, this setting tells ClickMagick whether to include the very last Rotator URL in the shuffling process. You would want to set this to `false` if you don't want the last URL to be shuffled. Typically, this would be the case where the last URL is a "catch all" URL that processes the click specially if it wasn't possible to deliver the click to any of the other URLs. This can only be set for `spillover` Rotators. backup_url: type: string description: > 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: maxLength: 2048 type: string description: > 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: maxLength: 2048 type: string description: > 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: maxLength: 2560 type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. email_start_subject: type: string description: > The subject of the notification email when delivery starts for a Rotator URL. For more information on notification emails, please visit the [knowledgebase](https://www.clickmagick.com/kb/?answer=672&tab=emails). email_start: type: string description: | The body of the starting email, in plain text or HTML. email_finish_subject: type: string description: > The subject of the notification email when all clicks have been delivered. email_finish: type: string description: | The body of the finish email, in plain text or HTML. email_reply_to: type: string description: > The Reply-To email address for both the starting and finish email messages. include_country: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this Rotator, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this Rotator, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: type: string description: > 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. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing blank_referrer: type: boolean description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. default: false notes: maxLength: 1024 type: string description: | Notes that you would like to keep for this Rotator. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/IdResponse' example: id: 128364 status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/settings: get: tags: - Rotators summary: Get the settings for one or more Rotators description: | Get the settings for one or more Rotators by ID. operationId: getRotatorSettings x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/settings?id=128364&id=128365" parameters: - name: id in: query description: > To get the settings of one or more Rotators, pass in a single `id` value, or multiple `id` values. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorSettings' example: rotators: - backup_url: backup.example.com blank_referrer: false created: 2026-09-20T19:51:26Z domain_id: 0 email_finish: null email_finish_subject: null email_reply_to: null email_start: null email_start_subject: null exclude_countries: - NG filter_abuser: nothing filter_anon: flag filter_bot: flag filter_server: flag filter_spider: flag filter_user: flag id: 128364 include_countries: [] ios_url: null last_reset: 2026-10-10T15:17:50Z mobile_url: null notes: null pixels: null random_repeat_clicks: null rotator_group: 0 rotator_mode: spillover rotator_name: Health-related Traffic rotator_slug: healthtraffic sequential_repeat_clicks: null spillover_randomize: 0 spillover_randomize_last_url: false spillover_repeat_clicks: top_of_rotator status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/{rotator_id}: delete: tags: - Rotators summary: Delete a Rotator description: | Permanently delete a Rotator and all of its associated clicks. operationId: deleteRotator x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/12345" parameters: - name: rotator_id in: path description: | The ID of the Rotator to delete. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Rotators summary: Edit a Rotator description: | Update an existing Rotator. operationId: updateRotator x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/12345" -d "rotator_name=test2" parameters: - name: rotator_id in: path description: | The ID of the Rotator to update. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: properties: rotator_slug: maxLength: 20 minLength: 4 type: string description: > A unique identifier used as part of the Rotator link, e.g., `https://clkmr.com//`. It cannot be cleared. We recommend using a human-readable value such as `healthtraffic`. Letters, numbers, and dashes are allowed, but no spaces. rotator_name: maxLength: 32 minLength: 4 type: string description: > 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: minimum: 0 type: integer description: > 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=&...`. format: int32 default: 0 rotator_group: minimum: 0 type: integer format: int32 description: > 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: type: string enum: - fulfillment - spillover - random - sequential description: > 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?](https://www.clickmagick.com/kb/?article=28) random_repeat_clicks: type: string enum: - same_url - random_url description: > Where repeat clicks should be redirected when they come in for a `random` Rotator. This can only be set for `random` Rotators. sequential_repeat_clicks: type: string enum: - same_url - next_url description: > Where repeat clicks should be redirected when they come in for a `sequential` Rotator. This can only be set for `sequential` Rotators. spillover_repeat_clicks: type: string enum: - backup_url - last_url - top_of_rotator description: > Where repeat clicks should be redirected when they come in for a `spillover` Rotator. This can only be set for `spillover` Rotators. spillover_randomize: type: integer format: int32 description: > If set, this is the number of minutes that ClickMagick should wait before randomly shuffling all of the Rotator's URLs. This random shuffling is useful at times because clicks are always delivered starting with the Rotator URL that's in the first position, and then down from there. Shuffling causes the URLs to get different priorities after they have been shuffled. To turn off shuffling, set it to nothing, e.g., `spillover_randomize=&...`. This can only be set for `spillover` Rotators. spillover_randomize_last_url: type: boolean default: true description: > If `spillover_randomize` is set so that the URLs are shuffled regularly, this setting tells ClickMagick whether to include the very last Rotator URL in the shuffling process. You would want to set this to `false` if you don't want the last URL to be shuffled. Typically, this would be the case where the last URL is a "catch all" URL that processes the click specially if it wasn't possible to deliver the click to any of the other URLs. This can only be set for `spillover` Rotators. backup_url: type: string description: > 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: maxLength: 2048 type: string description: > 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: maxLength: 2048 type: string description: > 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: maxLength: 2560 type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To unset this value, set it to nothing, e.g., `pixels=&...`. email_start_subject: type: string description: > 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](https://www.clickmagick.com/kb/?answer=672&tab=emails). email_start: type: string description: > 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: type: string description: > 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: type: string description: > 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: type: string description: > 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: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this Rotator, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this Rotator, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `backup_url`. To turn off geotargetting altogether, unset both `include_country` and `exclude_country` simultaneously, e.g., `include_country=&exclude_country=&...`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: type: string description: > 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. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing blank_referrer: type: boolean description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. default: false notes: maxLength: 1024 type: string description: | Notes that you would like to keep for this Rotator. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/{rotator_id}/urls: get: tags: - Rotator URLs summary: Get a list of Rotator URLs and their IDs description: | Get the list of Rotator URLs and IDs for a specific Rotator. operationId: getRotatorUrls x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls?limit=1" parameters: - name: rotator_id in: path description: | The ID of the parent Rotator of these Rotator URLs. required: true schema: minimum: 0 type: integer format: int32 - $ref: '#/components/parameters/limit' - name: cursor in: query description: > 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. schema: type: string format: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorURLList' example: rotator_urls: - id: 358792 name: Terry Jones 500C status: active cursor: next: ZBDkPOxCKRi prev: null errors: [] status: OK warnings: [] '429': $ref: '#/components/responses/429' post: tags: - Rotator URLs summary: Create a new Rotator URL description: | Create a new Rotator URL. operationId: createRotatorUrl x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls" -d "name=Terry Jones 500C&url=https://www.example.com/salespage" parameters: - name: rotator_id in: path description: | The ID of the Rotator to create a URL for. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: required: - name - url properties: name: type: string description: | The name of this Rotator URL. status: type: string enum: - active - paused - archived default: active description: > 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: type: string description: | The URL to deliver clicks to. position: type: integer format: int32 minimum: 1 maximum: 9999 description: > The position in the Rotator. If the position is not specified, it will be added to the last position in the Rotator. weight: type: integer format: int32 maximum: 10 minimum: 1 default: 1 description: > When using a Sequential Rotator, this allows you to specify at what speed the URL should get traffic. For example, a weight of 2 means that this URL will get twice the traffic during the same period of time as compared to URLs that have the default weight of 1. If you set this to 3, traffic will be delivered 3 times faster. This can only be set for URLs in `sequential` Rotators. max_clicks: type: integer format: int32 minimum: 1 maximum: 999999 default: null description: > The maximum number of unique clicks to send to this Rotator. If not specified, it defaults to "unlimited". max_clicks_daily: minimum: 1 maximum: 9999 type: integer format: int32 description: > The maximum number of unique clicks to send to this Rotator per day. If not specified, it defaults to "unlimited". bonus: type: integer format: int32 minimum: 0 maximum: 99 default: 0 description: | The percentage of max_clicks to over-deliver. min_t1: type: integer format: int32 minimum: 0 maximum: 100 default: 0 description: > 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: type: integer format: int32 minimum: 0 maximum: 100 default: 100 description: > 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: type: integer format: int32 minimum: 0 maximum: 100 default: 0 description: > 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: minimum: 0 maximum: 100 type: integer format: int32 description: > The maximum amount of mobile traffic this URL will receive on a percentage basis. If you set `max_mobile`, you must also set `min_mobile` at the same time. If not specified, it defaults to "unlimited". pixels: type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. start_time: type: string description: > The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to start sending traffic to this Rotator URL. format: date-time end_time: type: string description: > The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to stop sending traffic to this Rotator URL. format: date-time include_country: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this Rotator URL, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this Rotator URL, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string description: > The email address to use when sending start and finish notification messages. send_start_email: type: string enum: - on_add - on_first_click description: >- 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: type: boolean default: false description: > If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered. This only works if `max_clicks` is set. If `max_clicks` has no value, `send_finish_email` is set to `false`. notes: type: string description: | Notes that you would like to track for this link. required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorURLResponse' example: errors: [] id: 358792 public_stats_url: https://www.clickmagick.com/share/002f6ed001f56c0057988 status: OK warnings: [] '429': $ref: '#/components/responses/429' /rotators/urls/settings: get: tags: - Rotator URLs summary: Get the settings for one or more Rotator URLs description: | Get the settings for one or more Rotator URLs by ID. operationId: getRotatorUrlSettings x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/settings?id=358792&id=358793" parameters: - name: id in: query description: > To get the settings of one or more Rotator URLs, pass in a single `id` value, or multiple `id` values. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RotatorURLSettings' example: rotator_urls: - id: 358792 public_stats_url: https://www.clickmagick.com/share/002f6ed001f56c0057988 rotator_id: 128364 name: Terry Jones 500C status: active url: https://www.example.com/salespage position: 1 weight: 1 max_clicks: 500 max_clicks_daily: 25 bonus: 0 min_t1: 60 max_t1: null min_mobile: null max_mobile: null pixels: null start_time: null end_time: null include_countries: [] exclude_countries: - NG email: terry@example.com send_start_email: on_first_click send_finish_email: true notes: null last_reset: 2026-10-10T15:17:50Z created: 2026-09-20T19:51:26Z status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/stats: post: tags: - Rotators summary: Create a stats report for one or more Rotators description: > Create a stats report for one or more Rotators by Rotator ID. This call returns a report `id` and `url`; poll that url with `GET /rotators/stats/reports/{report_id}` until the report has been generated. operationId: getRotatorStats x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/stats" -d "id=128364&id=128365" requestBody: content: application/x-www-form-urlencoded: schema: required: - id properties: id: type: array items: type: integer format: int32 description: > Pass in one or more Rotator IDs. `&id=128364&id=128365` start_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. end_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /rotators/stats/reports/{report_id}: get: tags: - Rotators summary: Poll for the specified Rotators stats report description: > Poll for the specified Rotators stats report. If the report is still being generated, a `202` status will be returned with the progress of how much of the report has been generated. Once the report has been generated, a `200` status will be returned with the stats. Most reports are ready in well under a second. Poll on this schedule: 1. Wait 250 milliseconds after creating the report, then check it. 2. If it isn't ready, wait 500 milliseconds and check again. 3. After that, check once a second. 4. If it still isn't ready after 30 seconds, check every 5 seconds. operationId: getRotatorStatsReport x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/stats/reports/3752921" parameters: - $ref: '#/components/parameters/report_id' responses: '200': description: Report is ready content: application/json: schema: $ref: '#/components/schemas/RotatorStatsReport' '202': $ref: '#/components/responses/GetReportProgress' '429': $ref: '#/components/responses/429' /rotators/{rotator_id}/urls/{url_id}: delete: tags: - Rotator URLs summary: Delete a Rotator URL description: | Permanently delete a Rotator URL and all of its associated clicks. operationId: deleteRotatorUrl x-codeSamples: - lang: curl source: >- curl -X DELETE -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls/358792" parameters: - name: rotator_id in: path description: | The ID of the parent Rotator of these Rotator URLs. required: true schema: minimum: 0 type: integer format: int32 - name: url_id in: path description: | The ID of the Rotator URL to delete. required: true schema: minimum: 0 type: integer format: int32 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' patch: tags: - Rotator URLs summary: Edit a Rotator URL description: | Update a Rotator URL. operationId: updateRotatorUrl x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/128364/urls/358792" -d "url=https://www.example.com/offer" parameters: - name: rotator_id in: path description: | The ID of the parent Rotator of these Rotator URLs. required: true schema: minimum: 0 type: integer format: int32 - name: url_id in: path description: | The ID of the URL to edit. required: true schema: minimum: 0 type: integer format: int32 requestBody: content: application/x-www-form-urlencoded: schema: properties: name: type: string description: | The name of this Rotator URL. status: type: string enum: - active - paused - archived description: > 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: type: string description: | The URL to deliver clicks to. position: type: integer format: int32 minimum: 1 maximum: 9999 description: > The position in the Rotator. To move the URL to the last position, set it to nothing, e.g., `position=&...`. weight: type: integer format: int32 maximum: 10 minimum: 1 default: 1 description: > When using a Sequential Rotator, this allows you to specify at what speed the URL should get traffic. For example, a weight of 2 means that this URL will get twice the traffic during the same period of time as compared to URLs that have the default weight of 1. If you set this to 3, traffic will be delivered 3 times faster. This can only be set for URLs in `sequential` Rotators. max_clicks: type: integer format: int32 minimum: 1 maximum: 999999 default: null description: > 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: minimum: 1 maximum: 9999 type: integer format: int32 description: > 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: type: integer format: int32 minimum: 0 maximum: 99 default: 0 description: | The percentage of max_clicks to over-deliver. min_t1: type: integer format: int32 minimum: 0 maximum: 100 default: 0 description: > 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: type: integer format: int32 minimum: 0 maximum: 100 default: 100 description: > 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: type: integer format: int32 minimum: 0 maximum: 100 default: 0 description: > 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: minimum: 0 maximum: 100 type: integer format: int32 description: > 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: type: string description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. To clear `pixels` if it already has a value, set it to nothing, e.g., `pixels=&...`. start_time: type: string description: > 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=&...`. format: date-time end_time: type: string description: > 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=&...`. format: date-time include_country: type: string default: all countries description: > If you want clicks only from specific countries to be delivered to this Rotator URL, use the `include_country` parameter. (Sometimes it's more convenient to exclude countries—see the `exclude_country` parameter for that.) For each country that you want to allow clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to include the United States, Mexico, and Canada, and to exclude all others, pass: `include_country=US&include_country=MX&include_country=CA` You can also include Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. If you use this parameter, all clicks from countries that are not explicitly included will be redirected through the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string default: no countries description: > If you want to exclude clicks from specific countries from being delivered to this Rotator URL, use the `exclude_country` parameter. (Sometimes it's more convenient to include countries—see the `include_country` parameter for that.) For each country that you want to exclude clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to exclude clicks from North America use: `exclude_country=US&exclude_country=MX&exclude_country=CA` You can also exclude Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). 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: type: string description: > 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: type: string enum: - on_add - on_first_click description: >- 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: type: boolean default: false description: > If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered. This only works if `max_clicks` is set. If `max_clicks` has no value, `send_finish_email` is set to `false`. notes: type: string description: > 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: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: status: OK errors: [] warnings: [] '429': $ref: '#/components/responses/429' /rotators/urls/stats: post: tags: - Rotator URLs summary: Create a stats report for one or more Rotator URLs description: > Create a stats report for one or more Rotator URLs by Rotator URL ID. This call returns a report `id` and `url`; poll that url with `GET /rotators/urls/stats/reports/{report_id}` until the report has been generated. operationId: getRotatorURLStats x-codeSamples: - lang: curl source: >- curl -X POST -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/stats" -d "rotator_id=128364&id=358792" requestBody: content: application/x-www-form-urlencoded: schema: required: - id - rotator_id properties: id: type: array items: type: integer format: int32 description: > Pass in one or more Rotator URL IDs. For example: id=12345&id=12346&id=12347 rotator_id: type: integer format: int32 description: | The ID of the Rotator that the URL IDs belong to. start_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. end_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. time_zone: type: string description: > 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`. If you don't pass in this time zone, the time zone in the User Settings of the ClickMagick account will be used. responses: '200': $ref: '#/components/responses/CreateReport' '429': $ref: '#/components/responses/429' /rotators/urls/stats/reports/{report_id}: get: tags: - Rotator URLs summary: Poll for the specified Rotator URLs stats report description: > Poll for the specified Rotator URLs stats report. If the report is still being generated, a `202` status will be returned with the progress of how much of the report has been generated. Once the report has been generated, a `200` status will be returned with the stats. Most reports are ready in well under a second. Poll on this schedule: 1. Wait 250 milliseconds after creating the report, then check it. 2. If it isn't ready, wait 500 milliseconds and check again. 3. After that, check once a second. 4. If it still isn't ready after 30 seconds, check every 5 seconds. operationId: getRotatorURLsStatsReport x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/rotators/urls/stats/reports/3752921" parameters: - $ref: '#/components/parameters/report_id' responses: '200': description: Report is ready content: application/json: schema: $ref: '#/components/schemas/RotatorURLStatsReport' '202': $ref: '#/components/responses/GetReportProgress' '429': $ref: '#/components/responses/429' /user/settings: get: operationId: getUserSettings tags: - User Settings summary: Get account settings description: | Returns the settings for your account. x-codeSamples: - lang: curl source: >- curl -X GET -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/user/settings" responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UserSettings' example: errors: [] settings: affiliate_username: null blocked_country: - NG blocked_countries_url: https://www.example.com/blocked copy_to_clipboard: true currency: USD custom_logo_image_url: null custom_logo_link_url: null date_range: today error_url: https://www.example.com/error filter_abuser: block filter_anon: nothing filter_bot: flag filter_server: flag filter_spider: flag filter_user: flag invalid_click_threshold: 10 notify_conversions: true public_logo_type: clickmagick_logo show_subgroup_links: true tablet: desktop time_zone: Australia/Sydney status: OK warnings: [] '429': $ref: '#/components/responses/429' patch: operationId: updateUserSettings tags: - User Settings summary: Edit account settings description: | Allows you to update your account settings. x-codeSamples: - lang: curl source: >- curl -X PATCH -H "X-APIKEY: YOURAPIKEY" "https://api.clickmagick.com/v1/user/settings" -d "time_zone=Australia/Sydney&date_range=last_7_days" requestBody: content: application/x-www-form-urlencoded: schema: properties: affiliate_username: type: string description: > Is this user also an affiliate marketer for ClickMagick? This is their username if so. blocked_country: type: string default: no countries description: > If you want to block clicks from specific countries from ever being delivered to any Smart Link or Rotator, use the `blocked_country` parameter. For each country that you want to block clicks from, set this parameter to its standard two-letter country abbreviation, such as `US` for the United States. For multiple countries, pass this parameter for each country. For example, to block all clicks from North America use: `blocked_country=US&blocked_country=MX&blocked_country=CA` You can also block Tier 1, Tier 2, and Tier 3 countries with a single setting: `T1`, `T2`, or `T3`. To specify the European Union, pass `EU`. Clicks from these countries are redirected to the `blocked_countries_url`, if one is set. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). blocked_countries_url: type: string format: uri description: | If set, blocked country clicks are redirected to this URL. copy_to_clipboard: type: boolean description: > 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: type: string minLength: 3 maxLength: 3 default: USD description: > 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](https://www.iban.com/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: type: string format: uri default: null description: > The URL of your custom logo image. This only applies when `public_logo_type` is `custom_logo`, so to set or change this URL, include `public_logo_type=custom_logo` in the same request. custom_logo_link_url: type: string format: uri default: null description: > If the custom logo is clicked on, the browser will be redirected to this URL. Optional, and it has no effect unless your logo type is `custom_logo`. Pass an empty value to remove it. date_range: type: string enum: - today - last_7_days - last_30_days - this_month - this_year - all_time description: > This is the default date range whenever you first log in to ClickMagick. error_url: type: string format: uri description: > 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: type: string description: > 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. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_apply: type: boolean description: > If set to `true`, apply these filter settings to all existing Smart Links and Rotators. default: false filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing invalid_click_threshold: type: integer default: 10 description: > 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: type: string enum: - clickmagick_logo - custom_logo - no_logo default: clickmagick_logo description: > The logo shown on your shared stats pages. Send this parameter to change the logo. notify_conversions: type: boolean description: | Receive a notification by email each time you make a sale. default: false show_subgroup_links: type: boolean description: >- 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: type: string description: > Treat traffic from tablet devices as either `mobile` or `desktop` traffic. enum: - desktop - mobile default: desktop time_zone: type: string description: > 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StatusResponse' example: errors: [] status: OK warnings: [] '429': $ref: '#/components/responses/429' components: securitySchemes: apikey: type: apiKey description: The API key issued to you by ClickMagick. name: x-apikey in: header schemas: CampaignProjectIDs: title: Project ID type: object properties: id: type: integer format: int32 name: type: string CampaignProjectList: title: Project List type: object properties: projects: type: array items: $ref: '#/components/schemas/CampaignProjectIDs' status: type: string errors: type: array items: type: string warnings: type: array items: type: string retry_after: type: integer format: int32 minimum: 1 example: 3600 description: | How many seconds the caller should wait before retrying the request. TooManyRequestsResponse: title: Too Many Requests Response description: > A response indicating that the caller's requests are now being rate limited. See also: * [429 Too Many Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429). type: object required: - errors - retry_after - status properties: errors: type: array items: type: string example: - foo bar description: The errors for this request, if any. retry_after: $ref: '#/components/schemas/retry_after' status: type: string enum: - Error example: Error description: Whether the request was successful or not. warnings: type: array items: type: string example: [] description: The warnings for this request, if any. Id: type: integer format: int32 minimum: 0 description: The resource id. example: 48024 ResponseStatusEnum: type: string description: Whether the request was successful or not. enum: - Error - OK example: OK StatusResponse: title: API Response description: An API response with a status indicator. type: object required: - status properties: errors: type: array items: type: string description: The errors for this request, if any. status: $ref: '#/components/schemas/ResponseStatusEnum' warnings: type: array items: type: string description: The warnings for this request, if any. IdResponse: allOf: - title: A response with a resource id. description: A response with a resource id. type: object required: - id properties: id: $ref: '#/components/schemas/Id' - $ref: '#/components/schemas/StatusResponse' CampaignProjectObject: title: Campaign Project type: object properties: id: type: integer format: int32 name: type: string time_zone: type: string description: > 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) currency: type: string description: > This is the 3-letter ISO Currency Code that Project stats are displayed in. When cost data is imported in a different currency, the cost values will be converted to the project's currency. You can find a list of the currency codes in this article: [ISO Currency Codes](https://en.wikipedia.org/wiki/ISO_4217) project_domain: type: string description: > 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. use_cogs: type: boolean description: > Set to `true` if Cost Of Goods Sold (COGS) values should be used in computing stats for this project. attribution_window: type: integer description: > 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. created: type: string format: datetime CampaignProjectSettings: title: Campaign Project Settings type: object properties: projects: type: array items: $ref: '#/components/schemas/CampaignProjectObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string CampaignProjectUtms: title: Campagin Project Used UTM Values type: object properties: status: type: string utm: type: object properties: source: type: array items: type: string medium: type: array items: type: string campaign: type: array items: type: string term: type: array items: type: string content: type: array items: type: string CreateReportResponse: allOf: - title: Create Report Response description: The response from creating a report. type: object required: - report properties: report: type: object required: - id - url properties: id: type: integer format: int32 minimum: 1 description: The report id. example: 3752921 url: type: string description: The location of the report. example: >- https://api.clickmagick.com/v1/foo/bar/reports/3752921 - $ref: '#/components/schemas/StatusResponse' example: report: id: 3752921 url: https://api.clickmagick.com/v1/foo/bar/reports/3752921 status: OK AttributionModel: type: string enum: - first_click - last_click - linear - pos_based - time_decay CPC: type: number format: float description: Cost Per Click example: 1.88 EPC: type: number format: float description: Earnings Per Click example: 34.54 LTV: type: number format: float description: Earnings Per Sale, also known as Lifetime Value example: 67.34 Profit: type: number format: float description: Profit example: 42976.65 Revenue: type: number format: float description: The total amount of revenue during this period. example: 45453.75 ROI: type: number format: float description: Return on Investment example: 1735 Sales: type: integer format: int32 description: The number of initial and backend sales that were tracked. example: 675 SCR: type: number format: float description: Sales Conversion Rate example: 51.3 UniqueClicks: type: integer format: int32 description: The number of unique clicks. example: 134 CampaignProjectStatsObject: title: Campaign Project stats type: object required: - acr - actions - ad_cost - ad_spend - aov - cac - cogs - cost - cpa - cpc - cpe - cps - currency_symbol - customers - customers_new - customers_repeat - ecr - engagements - epa - epc - epe - ltv - profit - project_id - refunds - refunds_cogs - revenue - revenue_backend - revenue_initial - revenue_recurring - revenue_upsells - roas - roas_24h - roi - sales - scr - unique_clicks properties: acr: type: number format: float description: Action Conversion Rate actions: type: integer format: int32 description: The number of actions. ad_cost: type: number format: float description: > Your total ad costs. Unlike the total `cost` stat, this never includes COGS. ad_spend: type: number format: float deprecated: true description: > This field returns the same value as the total `cost` stat, not your ad costs alone. Use `cost` if you want that total, or `ad_cost` if you want your ad costs by themselves. aov: type: number format: float description: Average Order Value cac: type: number format: float description: Customer Acquisition Cost cogs: type: number format: float description: > The total Cost of Goods Sold minus the COGS from refunded sales. The refunded-sales COGS is left in, rather than subtracted, when the "Include COGS from refunded sales" project setting is enabled. cost: type: number format: float description: > The total cost for the period selected. This is your ad costs, and may also include COGS depending on your project settings. cpa: type: number format: float description: Cost Per Action cpc: $ref: '#/components/schemas/CPC' cpe: type: number format: float description: Cost Per Engagement cps: type: number format: float description: Cost Per Sale currency_symbol: type: string description: > The currency symbol set for this project. This project setting is returned here because it is often needed for displaying stats. customers: type: integer format: int32 description: > The total number of customers who generated revenue during this period. customers_new: type: integer format: int32 description: > The number of new customers who generated revenue during this period. customers_repeat: type: integer format: int32 description: > The number of repeat customers who generated revenue during this period. ecr: type: number format: float description: Engagement Conversion Rate engagements: type: integer format: int32 description: The number of engagements. epa: type: number format: float description: Earnings Per Action epc: $ref: '#/components/schemas/EPC' epe: type: number format: float description: Earnings Per Engagement ltv: $ref: '#/components/schemas/LTV' profit: $ref: '#/components/schemas/Profit' project_id: type: integer format: int32 description: The project id. refunds: type: number format: float description: The total amount of refunds during this period. refunds_cogs: type: number format: float description: | The Cost of Goods Sold from refunded sales during this period. revenue: $ref: '#/components/schemas/Revenue' revenue_backend: type: number format: float description: > The amount of revenue generated from backend sales or repeat customers during this period. revenue_initial: type: number format: float description: > The amount of revenue generated from initial frontend sales during this period. revenue_recurring: type: number format: float description: > The amount of revenue generated from recurring subscriptions during this period. revenue_upsells: type: number format: float description: | The amount of revenue generated from upsells during this period. roas: type: number format: float description: Return on Ad Spend roas_24h: type: number format: float description: 24 Hour Return on Ad Spend roi: $ref: '#/components/schemas/ROI' sales: $ref: '#/components/schemas/Sales' scr: $ref: '#/components/schemas/SCR' unique_clicks: $ref: '#/components/schemas/UniqueClicks' ProgressObject: title: Progress Object description: Progress information for an activity. type: object required: - completed - percentage_completed properties: completed: type: boolean default: false percentage_completed: type: integer format: int32 default: 0 minimum: 0 maximum: 100 description: | Percentage of the activity that has been completed. example: 47 example: completed: false percentage_completed: 47 GetReportProgressResponse: allOf: - title: Get Report Progress Response description: The response from getting report progress. type: object required: - progress properties: progress: $ref: '#/components/schemas/ProgressObject' - $ref: '#/components/schemas/StatusResponse' CampaignProjectStatsReport: allOf: - title: Campaign Project Stats Report description: A report containing relevant campaign project statistics. type: object required: - last_updated - stats - total_seconds properties: last_updated: type: string format: date-time description: > The ISO-8601 timestamp indicating when this report was last updated. example: 2026-10-17T19:37:02Z stats: $ref: '#/components/schemas/CampaignProjectStatsObject' total_seconds: type: integer format: int32 minimum: 0 description: The number of seconds it took to generate this report. example: 39 - $ref: '#/components/schemas/GetReportProgressResponse' example: last_updated: 2026-10-17T19:37:02Z progress: completed: true percentage_completed: 100 stats: acr: 69.7 actions: 3374 ad_cost: 6498 ad_spend: 7098 aov: 62.11 cac: 35.49 cogs: 600 cost: 7098 cpa: 1.93 cpc: 1.34 cpe: 2.67 cps: 7.39 currency_symbol: £ customers: 243 customers_new: 200 customers_repeat: 43 ecr: 50.2 engagements: 2432 epa: 19.89 epc: 13.86 epe: 27.6 ltv: 335.56 profit: 59902 project_id: 29583 refunds: 111.02 refunds_cogs: 91.02 revenue: 67111.02 revenue_backend: 7383.98 revenue_initial: 9931.75 revenue_recurring: 7483.56 revenue_upsells: 5854.61 roas: 10.33 roas_24h: 2.74 roi: 844 sales: 960 scr: 4.1 unique_clicks: 4843 status: OK total_seconds: 39 CursorObject: title: Page Cursor type: object required: - next - prev description: > This cursor object contains a cursor for the next page and the previous page. You can use the cursor parameter in some API endpoints to iterate through the data from that endpoint. If you wish to iterate through all of the data, you would make your first call into the endpoint. That will return you the first page of data. After that you will continue to call the endpoint, setting the `cursor` parameter to the last response's `cursor.next` value. When the `cursor.next` value in a response is `null`, that indicates that there are no more pages of data remaining. properties: next: type: string nullable: true description: The cursor for the next page. example: ZBDkPOxCKRi prev: type: string nullable: true description: The cursor for the previous page. example: ODM3MjYyMTE VisitorObject: title: Visitor description: A visitor's identity and lifetime summary. type: object required: - visitor_id - first_name - last_name - email - phone - mobile - total_orders - lifetime_value - currency properties: visitor_id: type: string description: The visitor's ClickMagick Visitor ID. example: cmc2516938438 first_name: type: string nullable: true description: The visitor's first name. example: John last_name: type: string nullable: true description: The visitor's last name. example: Doe email: type: string nullable: true description: The visitor's email. example: john.doe@example.com phone: type: string nullable: true description: The visitor's phone number. example: 111-222-4444 mobile: type: string nullable: true description: The visitor's mobile phone number. total_orders: type: integer format: int32 description: > The number of sales (orders) recorded for this visitor. A sale that was later refunded is still counted. example: 3 lifetime_value: type: number format: float description: > The visitor's net revenue — the sum of their sales minus any refunds. example: 292.56 currency: type: string nullable: true description: > The 3-letter currency code for `lifetime_value`. Null when the visitor has no sales. example: USD VisitorEventObject: title: Visitor Event description: A single click or conversion in a visitor's timeline. type: object required: - type - click_type - cmc_project - project_id - utm_source - utm_medium - utm_campaign - utm_term - utm_content - cmc_ref - cmc_amt - currency - device - ip - shopify_order_id - timestamp properties: type: type: string enum: - click - action - engagement - sale - refund description: The kind of event. example: sale click_type: type: string nullable: true enum: - unique - repeat - flagged description: > For `click` events, the click subtype. Null for all non-click events. cmc_project: type: string description: The project's name. example: Bigfoot Surfboards project_id: type: integer format: int32 nullable: true description: The project's internal id. example: 29583 utm_source: type: string description: The utm_source. An empty string when not set. utm_medium: type: string description: The utm_medium. An empty string when not set. utm_campaign: type: string description: The utm_campaign. An empty string when not set. utm_term: type: string description: The utm_term. An empty string when not set. utm_content: type: string description: The utm_content. An empty string when not set. cmc_ref: type: string description: An optional reference value. An empty string when not set. cmc_amt: type: number format: float nullable: true description: > For `sale` and `refund` events, the amount (negative for a refund). Null for all other event types. example: 97.52 currency: type: string nullable: true description: > The 3-letter currency code for `cmc_amt`. Null for non-monetary events. example: USD device: type: string enum: - desktop - mobile - tablet - unknown description: > The visitor's device type for this event. `unknown` when it could not be determined. example: desktop ip: type: string nullable: true description: The visitor's IP address for this event. example: 192.0.2.1 shopify_order_id: type: string nullable: true description: > The Shopify order id for `sale` and `refund` events, if any. Null otherwise. example: '#1001' timestamp: type: string description: The event timestamp in ISO-8601 format (UTC). example: 2026-10-17T19:37:02Z VisitorProfileResponse: allOf: - title: Visitor Profile description: A visitor's profile plus a page of their event log. type: object required: - cursor - visitor - events properties: cursor: $ref: '#/components/schemas/CursorObject' visitor: $ref: '#/components/schemas/VisitorObject' events: type: array description: A page of the visitor's clicks and conversions. items: $ref: '#/components/schemas/VisitorEventObject' - $ref: '#/components/schemas/StatusResponse' example: status: OK cursor: next: ZBDkPOxCKRi prev: null visitor: visitor_id: cmc2516938438 first_name: John last_name: Doe email: john.doe@example.com phone: 111-222-4444 mobile: null total_orders: 3 lifetime_value: 292.56 currency: USD events: - type: sale click_type: null cmc_project: Bigfoot Surfboards project_id: 29583 utm_source: google utm_medium: cpc utm_campaign: end+of+season utm_term: '' utm_content: '' cmc_ref: purchase cmc_amt: 97.52 currency: USD device: desktop ip: 192.0.2.1 shopify_order_id: '#1001' timestamp: 2026-10-17T19:37:02Z - type: click click_type: unique cmc_project: Bigfoot Surfboards project_id: 29583 utm_source: google utm_medium: cpc utm_campaign: end+of+season utm_term: '' utm_content: '' cmc_ref: '' cmc_amt: null currency: null device: mobile ip: 192.0.2.1 shopify_order_id: null timestamp: 2026-10-16T10:44:14Z CampaignGoalObject: title: Campaign Goal description: A base definition of a campaign goal object. type: object required: - city - cmc_project - cmc_ref - cmc_tid - country - date_of_birth - device - email - fbclid - first_name - gclid - gender - id - ip - last_name - mobile - msclkid - phone - postal_code - project_id - state - timestamp - utm_campaign - utm_content - utm_medium - utm_source - utm_term - visitor_id properties: city: type: string nullable: true description: The visitor's city. example: Phoenix cmc_project: type: string description: The project's name. example: Bigfoot Surfboards cmc_ref: type: string nullable: true description: An optional reference value. example: golfpkg1 cmc_tid: type: string nullable: true description: Custom postback tracking id passed into ClickMagick. country: type: string description: The visitor's country as detected by ClickMagick. example: US date_of_birth: type: string nullable: true description: The visitor's date of birth. example: Jan 15, 1995 device: type: string enum: - desktop - mobile - tablet description: The visitor's device type. example: mobile email: type: string nullable: true description: The visitor's email. example: john.doe@example.com fbclid: type: string nullable: true description: Facebook Ad's click id. first_name: type: string nullable: true description: The visitor's first name. example: John gclid: type: string nullable: true description: Google Ad's click id. gender: type: string nullable: true description: The visitor's gender. id: type: integer format: int32 description: The internal goal id. example: 3956114 ip: type: string description: The visitor's ip address. example: 192.0.2.1 last_name: type: string nullable: true description: The visitor's last name. example: Doe msclkid: type: string nullable: true description: Microsoft Ad's click id. mobile: type: string nullable: true description: The visitor's mobile phone number. example: 111.222.3333 phone: type: string nullable: true description: The visitor's phone number. example: 111-222-4444 postal_code: type: string nullable: true description: The visitor's postal code. example: '85007' project_id: type: integer format: int32 description: The project's internal id. example: 29583 state: type: string nullable: true description: The visitor's state, province, or region. example: AZ timestamp: type: string description: The timestamp of the goal in ISO-8601 format. example: 2026-10-16T10:44:14Z utm_source: type: string nullable: true description: The UTM parameter which identifies which site sent this goal. example: google utm_medium: type: string nullable: true description: > The UTM parameter which identifies what type of link was used. For example, cost per click or email. example: cpc utm_campaign: type: string nullable: true description: > The UTM parameter which identifies the specific product, promotion, or strategic campaign. example: holiday+sale utm_term: type: string nullable: true description: The UTM parameter which identifies which search term was used. example: golf+clubs utm_content: type: string nullable: true description: | The UTM parameter which identifies what was specifically clicked. example: lighweight+golf+clubs visitor_id: type: string description: The visitor id. example: cmc2516938438 CampaignActionObject: allOf: - title: Campaign Action Goal description: A campaign action goal. type: object - $ref: '#/components/schemas/CampaignGoalObject' PagedResponse: allOf: - title: Paged Response description: A page of results. type: object required: - cursor properties: cursor: $ref: '#/components/schemas/CursorObject' - $ref: '#/components/schemas/StatusResponse' CampaignActions: allOf: - title: Campaign Action Goals description: A page of campaign action goals. type: object required: - actions properties: actions: type: array description: The list of campaign actions. items: $ref: '#/components/schemas/CampaignActionObject' - $ref: '#/components/schemas/PagedResponse' example: cursor: next: ZBDkPOxCKRi prev: null actions: - cmc_project: Bigfoot Surfboards cmc_ref: salespage cmc_tid: null country: US device: desktop fbclid: null gclid: null id: 3956114 ip: 192.0.2.1 msclkid: null project_id: 29583 timestamp: 2026-10-17T19:37:02Z utm_content: best+surfboard utm_medium: cpc utm_source: google utm_term: Hang+Ten visitor_id: cmc2516938438 status: OK CampaignEngageObject: allOf: - title: Campaign Engagement Goal description: A campaign engagement goal. type: object - $ref: '#/components/schemas/CampaignGoalObject' CampaignEngages: allOf: - title: Campaign Engagement Goals description: A page of campaign engagement goals. type: object required: - engagements properties: engagements: type: array description: The list of campaign engagements. items: $ref: '#/components/schemas/CampaignEngageObject' - $ref: '#/components/schemas/PagedResponse' example: cursor: next: ZBDkPOxCKRi prev: null sales: - cmc_amt: 97.52 cmc_project: Bigfoot Surfboards cmc_ref: checkoutpage cmc_tid: null country: US device: desktop fbclid: null gclid: null id: 809274 ip: 192.0.2.1 msclkid: null project_id: 29583 timestamp: 2026-10-17T19:37:02Z utm_campaign: end+of+season utm_content: best+surfboard utm_medium: cpc utm_source: google utm_term: Hang+Ten visitor_id: cmc2516938438 status: OK CampaignSaleObject: allOf: - title: Campaign Sale Goal description: A campaign sale goal. type: object required: - cmc_amt properties: cmc_amt: type: number format: float description: The amount of this sale. shopify_order_id: type: string nullable: true description: | The Shopify order id, if any. Only available in the 'last_click' attribution model. - $ref: '#/components/schemas/CampaignGoalObject' CampaignSales: allOf: - title: Campaign Sale Goals description: A page of campaign sale goals. type: object required: - sales properties: sales: type: array description: The list of campaign sales. items: $ref: '#/components/schemas/CampaignSaleObject' - $ref: '#/components/schemas/PagedResponse' example: cursor: next: ZBDkPOxCKRi prev: null sales: - cmc_amt: 97.52 cmc_project: Bigfoot Surfboards cmc_ref: salespage cmc_tid: null country: US device: desktop fbclid: null gclid: null id: 910176 ip: 192.0.2.1 msclkid: null project_id: 29583 shopify_order_id: '#000-10' timestamp: 2026-10-17T19:37:02Z utm_campaign: end+of+season utm_content: best+surfboard utm_medium: cpc utm_source: google utm_term: Hang+Ten visitor_id: cmc2516938438 status: OK CampaignUrlObject: title: Campaign URL type: object properties: notes: type: string nullable: true url: type: string CampaignUrls: title: Campaign URLs type: object properties: urls: type: array items: $ref: '#/components/schemas/CampaignUrlObject' cursor: $ref: '#/components/schemas/CursorObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string DomainObject: title: Domain type: object properties: id: type: integer format: int32 domain: type: string type: type: string enum: - link - rotator description: Is this domain for Smart Links, or for Rotators? setup: type: string enum: - cname - forwarding description: > Is the domain set up using CNAME DNS (or "A") records, or using the now deprecated "script forwarding" setup? error_url: type: string nullable: true description: > If this domain is used with a link or Rotator slug that does not exist, clicks to it must redirected to a different URL. If `error_url` is set, the click will be redirected to this URL, otherwise it will be redirected to the `error_url` in the User Settings. Domains: title: Domain required: - status - errors - warnings type: object properties: domains: type: array items: $ref: '#/components/schemas/DomainObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string DomainCreated: title: Domain Created required: - status - errors - warnings type: object properties: id: type: integer description: The ID of the domain just created. status: type: string errors: type: array items: type: string warnings: type: array items: type: string LinkGroupObject: title: Group type: object properties: name: type: string id: type: integer subgroups: type: array items: properties: name: type: string id: type: integer LinkGroups: title: Groups required: - groups - status - errors - warnings type: object properties: groups: type: array items: $ref: '#/components/schemas/LinkGroupObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string RotatorGroupObject: title: Group type: object properties: name: type: string id: type: integer RotatorGroups: title: Groups required: - groups - status - errors - warnings type: object properties: groups: type: array items: $ref: '#/components/schemas/RotatorGroupObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string LinkIDs: title: Link ID type: object properties: archived: type: boolean group_id: type: integer format: int32 description: >- If this Smart Link is part of a group this property will have its number, otherwise it will be null. id: type: integer format: int32 link_name: type: string link_slug: type: string subgroup_id: type: integer format: int32 description: >- If this Smart Link is part of a subgroup this property will have its number, otherwise it will be null. LinksList: title: Links List required: - cursor - links - status type: object properties: cursor: $ref: '#/components/schemas/CursorObject' errors: type: array items: type: string links: type: array items: $ref: '#/components/schemas/LinkIDs' status: type: string warnings: type: array items: type: string PublicStatsUrlLink: type: string description: The url for the shareable public stats. example: https://www.clickmagick.com/share/002f6ed01a6ab6 LinkResponse: allOf: - title: A response returning core Smart Link information. description: A response returning core Smart Link information. type: object required: - public_stats_url properties: public_stats_url: $ref: '#/components/schemas/PublicStatsUrlLink' - $ref: '#/components/schemas/IdResponse' Filter: title: Filter type: string description: > Describes how a click filter ought to behave. The `block` value will send filtered clicks to a generic error page. The `flag` value will send filtered clicks through to your link or Rotator but their click counts will be separated from your main stats. The `nothing` value will treat filtered clicks as real clicks. enum: - block - flag - nothing LinkObject: title: Link type: object properties: id: type: integer format: int32 primary_url: type: string description: | The primary URL that clicks will be redirected to. public_stats_url: $ref: '#/components/schemas/PublicStatsUrlLink' link_slug: type: string description: > A unique identifier used as part of the Smart Link, e.g., `https://clkmg.com//`. link_name: type: string nullable: true description: > The unique "friendly name" of this link. In the UI, if this is not specified, the `link_slug` is displayed instead. domain_id: type: integer description: > If you have any custom tracking domains set up to use with your Smart Links, you can use any of those domains at any time with any of your Smart Links. This `domain_id` setting simply specifies your _preferred_ domain for this particular Smart Link. This is useful in the UI, for example, when ClickMagick needs to copy a Smart Link to the clipboard. It will use this domain in the Smart Link rather than another domain that you might have set up. link_group: type: integer nullable: true description: | The ID of the group to organize this link under. link_subgroup: type: integer nullable: true description: | The ID of the subgroup to organize this link under. has_split_urls: type: boolean description: | Does this link have split urls configured under it. archived: type: boolean description: > Indicates if this link is archived. You can still send traffic to this link, but the link won't show up with other links in the UI unless you're viewing the "Archived Links" view. pixels: maxLength: 2560 type: string nullable: true description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. cost: type: number nullable: true description: > The cost of the click, if known in advance. If set, you must set `cost_type` as well. cost_type: type: string enum: - no_cost_type - one_time_cost - cost_per_click - daily - monthly description: | The type of cost for this Smart Link. backup_url: type: string nullable: true description: > The URL that clicks will be redirected to if they can't be redirected to any other URL in the link settings. For example, if the `max_clicks` setting for this link has been reached, or you have geotargetting set up and the setting doesn't match the click. mobile_url: type: string nullable: true description: > The URL that clicks from mobile devices will be redirected to instead of to the `primary_url`. Clicks from iOS devices will be redirected to this URL as well, unless `ios_url` is set. ios_url: type: string nullable: true description: > If the click is from an iOS device, clicks will be redirected to this URL instead of to the `primary_url`. Clicks from iOS devices will automatically be rediredted to the URL in the `mobile_url` setting if `ios_url` is not specified. repeat_url: type: string nullable: true description: | Repeat clicks from the same visitor will be redirected to this URL. repeat_primary_url: type: boolean description: > Use the `repeat_url` if the visitor has ever clicked on any link in the user's account with the same `primary_url`. include_countries: type: array items: type: string nullable: true description: > This is an array of two-letter country codes (`US` for the United States, 'MX' for Mexico, and so on). If this array has any values, it means that the link is set up to only accept clicks from those countries. Clicks from any countries not in the list will be redirected to the link's `backup_url`. A null value indicates all countries are accepted. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). exclude_countries: type: array items: type: string default: [] description: > This is an array of two-letter country codes (`CA` for Canada, 'AU' for Australia, and so on). If this array has any values, it means that the link is set up to reject clicks from those countries. Any click from countries in the list will be redirected to the link's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: $ref: '#/components/schemas/Filter' filter_anon: $ref: '#/components/schemas/Filter' filter_bot: $ref: '#/components/schemas/Filter' filter_server: $ref: '#/components/schemas/Filter' filter_spider: $ref: '#/components/schemas/Filter' filter_user: $ref: '#/components/schemas/Filter' max_clicks: type: integer nullable: true description: > If specified, this is the maximum number of clicks to redirect through the Smart Link. All additional clicks will then be redirected through the `backup_url`. blank_referrers: type: boolean description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. password: type: string nullable: true description: > If set, the Smart Link will display a generic login page that the user must enter the password to continue. notes: type: string nullable: true description: | Notes that you would like to track for this link. split_type: type: string enum: - epc description: > If you have a split test set up for this Smart Link, What are you're trying to optimize for? created: type: string format: datetime description: The UTC 0 timestamp of when the Smart Link was created. last_click: type: string description: >- The UTC 0 timestamp of the most recent click processed for this Smart Link. last_reset: type: string description: The UTC 0 timestamp of when this Smart Link was last reset. LinkSettings: title: Link Settings type: object properties: links: type: array items: $ref: '#/components/schemas/LinkObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string LinkStatsObject: title: Smart Link Project stats type: object properties: link_id: type: integer format: int32 example: 1731254 total_clicks: type: integer format: int32 example: 1447 unique_clicks: $ref: '#/components/schemas/UniqueClicks' flagged_clicks: type: integer format: int32 example: 4 cost: type: number format: float example: 2477.1 cpc: $ref: '#/components/schemas/CPC' revenue: $ref: '#/components/schemas/Revenue' profit: $ref: '#/components/schemas/Profit' epc: $ref: '#/components/schemas/EPC' roi: $ref: '#/components/schemas/ROI' LinkStatsReport: allOf: - title: Smart Link Stats Report description: A report containing relevant Smart Link statistics. type: object required: - last_updated - stats - total_seconds properties: last_updated: type: string format: date-time description: > The ISO-8601 timestamp indicating when this report was last updated. example: 2026-10-17T19:37:02Z stats: type: array items: $ref: '#/components/schemas/LinkStatsObject' total_seconds: type: integer format: int32 minimum: 0 description: The number of seconds it took to generate this report. example: 39 - $ref: '#/components/schemas/GetReportProgressResponse' SubIdStatsObject: title: Smart Link Sub-ID stats type: object properties: subid: type: string description: > The Sub-ID value these stats are for. An empty string represents clicks that had no value in this Sub-ID position. example: affiliate-42 total_clicks: type: integer format: int32 example: 1200 unique_clicks: $ref: '#/components/schemas/UniqueClicks' revenue: $ref: '#/components/schemas/Revenue' epc: $ref: '#/components/schemas/EPC' SubIdStatsReport: allOf: - title: Smart Link Sub-ID Stats Report description: A report containing Sub-ID statistics for one or more Smart Links. type: object required: - last_updated - stats - total_seconds properties: last_updated: type: string format: date-time description: > The ISO-8601 timestamp indicating when this report was last updated. example: 2026-10-17T19:37:02Z stats: type: array items: $ref: '#/components/schemas/SubIdStatsObject' truncated: type: boolean description: > Present and `true` only when the number of distinct Sub-ID values exceeded the 1,000-row limit and the result was truncated. The rows returned are the 1,000 with the most total clicks. example: false total_seconds: type: integer format: int32 minimum: 0 description: The number of seconds it took to generate this report. example: 2 - $ref: '#/components/schemas/GetReportProgressResponse' RotatorIDs: title: Rotator ID type: object properties: id: type: integer format: int32 rotator_name: type: string rotator_slug: type: string rotator_mode: type: string enum: - fulfillment - spillover - random - sequential description: > 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?](https://www.clickmagick.com/kb/?article=28) RotatorList: title: Rotator List required: - rotators - cursor - status - errors - warnings type: object properties: rotators: type: array items: $ref: '#/components/schemas/RotatorIDs' cursor: $ref: '#/components/schemas/CursorObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string RotatorObject: title: Rotator type: object properties: id: type: integer format: int32 rotator_slug: type: string description: > A unique identifier used as part of the Rotator link, e.g., `https://clkmr.com//`. rotator_name: type: string description: > The unique "friendly name" of this Rotator. In the UI, if this is not specified, the `rotator_slug` is displayed instead. domain_id: minimum: 0 type: integer description: > 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. format: int32 default: 0 rotator_group: type: integer format: int32 description: > The ID of the group to organize this Rotator under. If not specified, the 'All' group will be used. rotator_mode: type: string enum: - fulfillment - spillover - random - sequential description: > 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?](https://www.clickmagick.com/kb/?article=28) random_repeat_clicks: type: string nullable: true enum: - same_url - random_url description: > When repeat clicks come in for the `random` Rotator, where should they be redirected to. sequential_repeat_clicks: type: string nullable: true enum: - same_url - next_url description: > When repeat clicks come in for the `sequential` Rotator, where should they be redirected to. spillover_repeat_clicks: type: string nullable: true enum: - backup_url - last_url - top_of_rotator description: > When repeat clicks come in for the `spillover` Rotator, where should they be redirected to. spillover_randomize: type: integer nullable: true format: int32 description: > 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: type: boolean nullable: true default: true description: > 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: type: string description: > 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: type: string nullable: true description: > 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: type: string nullable: true description: > 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. pixels: type: string nullable: true description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. email_start_subject: type: string nullable: true description: > The subject of the notification email when delivery starts for a Rotator URL. For more information on notification emails, please visit the [knowledgebase](https://www.clickmagick.com/kb/?answer=672&tab=emails). email_start: type: string nullable: true description: | The body of the starting email, in plain text or HTML. email_finish_subject: type: string nullable: true description: > The subject of the notification email when all clicks have been delivered. email_finish: type: string nullable: true description: | The body of the finish email, in plain text or HTML. email_reply_to: type: string nullable: true description: > The Reply-To email address for both the starting and finish email messages. include_countries: type: array items: type: string nullable: true description: > This is an array of two-letter country codes (`US` for the United States, 'MX' for Mexico, and so on). If this array has any values, it means that the Rotator is set up to only accept clicks from those countries. Clicks from any countries not in the list will be redirected to the Rotator's `backup_url`. A null value indicates all countries are accepted. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). exclude_countries: type: array items: type: string default: [] description: > This is an array of two-letter country codes (`CA` for Canada, 'AU' for Australia, and so on). If this array has any values, it means that the Rotator is set up to reject clicks from those countries. Any click from countries in the list will be redirected to the Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). filter_abuser: type: string description: > 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. default: nothing enum: - block - flag - nothing filter_anon: type: string description: > 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`. default: nothing enum: - block - flag - nothing filter_bot: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_server: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_spider: type: string description: > 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`. default: flag enum: - block - flag - nothing filter_user: type: string description: > 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`. default: flag enum: - block - flag - nothing blank_referrer: type: boolean description: > Blank the referrer when redirecting clicks so that the site you're sending traffic to can't tell where it's coming from. default: false notes: type: string nullable: true description: | Notes that you would like to keep for this Rotator. created: type: string format: datetime description: The UTC 0 timestamp of when the Rotator was created. last_reset: type: string format: datetime description: The UTC 0 timestamp of when this Rotator was last reset. RotatorSettings: title: Rotator Settings type: object properties: rotators: type: array items: $ref: '#/components/schemas/RotatorObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string RotatorURLIDs: title: Rotator URL IDs type: object properties: id: type: integer format: int32 name: type: string position: type: integer format: int32 status: type: string enum: - active - paused - archived status_paused_reason: type: string enum: - user_paused - max_clicks - max_clicks_daily - start_time - end_time description: > If `status` is `paused`, this explains the reason why the rotator URL has been paused. `user_paused` means that the URL was explicitly paused by the user and that no traffic will ever be delivered to this URL until it has been reset to the `active` state. All other paused states are temporary until another condition has changed. `max_clicks` means that all clicks have been delivered to this URL based on the `max_clicks` setting. `max_daily_clicks` means that all clicks for today have been delivered and traffic will resume tomorrow. `start_time` means that traffic is scheduled to start being delivered at a later, pre-set time, and `end_time` means that the `end_time` delivery time has already passed. RotatorURLList: title: Rotator URL Lists type: object properties: rotator_urls: type: array items: $ref: '#/components/schemas/RotatorURLIDs' cursor: $ref: '#/components/schemas/CursorObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string PublicStatsUrlRotatorUrl: type: string description: The url for the shareable public stats. example: https://www.clickmagick.com/share/002f6ed001f56c0057988 RotatorURLResponse: allOf: - title: A response returning core rotator url information. description: A response returning core rotator url information. type: object required: - public_stats_url properties: public_stats_url: $ref: '#/components/schemas/PublicStatsUrlRotatorUrl' - $ref: '#/components/schemas/IdResponse' RotatorURLObject: title: Rotator URL Object type: object properties: id: type: integer format: int32 public_stats_url: $ref: '#/components/schemas/PublicStatsUrlRotatorUrl' rotator_id: type: integer format: int32 description: | Rotator ID this URL belongs to. name: type: string nullable: true description: | The unique "friendly name" of this URL. status: type: string nullable: true enum: - active - paused - archived description: > If the Rotator URL is `active`, it is currently delivering clicks. If it is `paused`, there are many reasons for this. See the `status_paused_reason` value. status_paused_reason: type: string enum: - user_paused - max_clicks - max_clicks_daily - start_time - end_time description: > If `status` is `paused`, this explains the reason why the rotator URL has been paused. `user_paused` means that the URL was explicitly paused by the user and that no traffic will ever be delivered to this URL until it has been reset to the `active` state. All other paused states are temporary until another condition has changed. `max_clicks` means that all clicks have been delivered to this URL based on the `max_clicks` setting. `max_daily_clicks` means that all clicks for today have been delivered and traffic will resume tomorrow. `start_time` means that traffic is scheduled to start being delivered at a later, pre-set time, and `end_time` means that the `end_time` delivery time has already passed. url: type: string description: | The URL to deliver clicks to. position: type: integer nullable: true format: int32 minimum: 1 description: > The position in the Rotator. If the position is not specified, it will be added to the last position in the Rotator. weight: type: integer nullable: true format: int32 minimum: 1 description: > When using a Sequential Rotator, this allows you to specify 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 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: type: integer nullable: true format: int32 minimum: 1 maximum: 999999 description: > The maximum number of unique clicks to send to this Rotator. If not specified, it defaults to "unlimited". max_clicks_daily: type: integer nullable: true format: int32 minimum: 1 maximum: 9999 description: > The maximum number of unique clicks to send to this Rotator per day. If not specified, it defaults to "unlimited". bonus: type: integer nullable: true format: int32 default: 0 minimum: 0 maximum: 99 description: | The percentage of `max_clicks` to over-deliver. min_t1: type: integer nullable: true format: int32 description: > The minimum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. max_t1: type: integer nullable: true format: int32 description: > The maximum amount of Tier 1 Traffic that's allowed for this URL on a percentage basis. min_mobile: type: integer nullable: true format: int32 description: > The minimum amount of mobile traffic this URL will receive on a percentage basis. max_mobile: type: integer nullable: true format: int32 description: > The maximum amount of mobile traffic this URL will receive on a percentage basis pixels: type: string nullable: true description: > 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 `` pixels here, or JavaScript code, as long as the JavaScript is wrapped with `<script>` .. `</script>` tags. start_time: type: string nullable: true format: datetime description: > The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to start sending traffic to this Rotator URL. end_time: type: string nullable: true format: datetime description: > The ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ) to stop sending traffic to this Rotator URL. include_countries: type: array items: type: string nullable: true description: > This is an array of two-letter country codes (`US` for the United States, 'MX' for Mexico, and so on). If this array has any values, it means that the Rotator URL is set up to only accept clicks from those countries. Clicks from any countries not in the list will be redirected to the parent Rotator's `backup_url`. A null value indicates all countries are accepted. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). exclude_countries: type: array items: type: string default: [] description: > This is an array of two-letter country codes (`CA` for Canada, 'AU' for Australia, and so on). If this array has any values, it means that the Rotator URL is set up to reject clicks from those countries. Any click from countries in the list will be redirected to the parent Rotator's `backup_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). email: type: string nullable: true description: > The email address to use when sending start and finish notification messages. send_start_email: type: string nullable: true enum: - on_add - on_first_click description: >- 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: type: boolean nullable: true description: > If the parent Rotator has a "finish" email set up, send that email when all clicks to this URL have been delivered. notes: description: | Notes that you would like to track for this link. last_reset: type: string description: The UTC 0 timestamp of when this Rotator URL was last reset. created: type: string description: The UTC 0 timestamp of when the Rotator URL was created. RotatorURLSettings: title: Rotator URL Settings type: object properties: rotator_urls: type: array items: $ref: '#/components/schemas/RotatorURLObject' status: type: string errors: type: array items: type: string warnings: type: array items: type: string RotatorStatsObject: title: Rotator Stat type: object properties: rotator_id: type: integer format: int32 example: 128364 active_urls: type: integer format: int32 example: 10 paused_urls: type: integer format: int32 example: 4 archived_urls: type: integer format: int32 total_clicks: type: integer format: int32 example: 507 unique_clicks: $ref: '#/components/schemas/UniqueClicks' flagged_clicks: type: integer format: int32 example: 5 RotatorStatsReport: allOf: - title: Rotator Stats Report description: A report containing relevant rotator statistics. type: object required: - last_updated - stats - total_seconds properties: last_updated: type: string format: date-time description: > The ISO-8601 timestamp indicating when this report was last updated. example: 2026-10-17T19:37:02Z stats: type: array items: $ref: '#/components/schemas/RotatorStatsObject' total_seconds: type: integer format: int32 minimum: 0 description: The number of seconds it took to generate this report. example: 39 - $ref: '#/components/schemas/GetReportProgressResponse' RotatorURLStatsObject: title: Rotator URL Stat type: object properties: url_id: type: integer format: int32 example: 358792 rotator_id: type: integer format: int32 example: 128364 total_clicks: type: integer format: int32 example: 193 unique_clicks: type: object properties: delivered: type: integer format: int32 example: 186 description: > Number of clicks that have been delivered. Clicks will stopped being delivered to this URL once the total number of `max_clicks` and `bonus_clicks` have been sent. max_clicks: type: integer nullable: true format: int32 example: 200 description: >- The total number of regular clicks to be sent, or null if no limit is set. bonus_clicks: type: integer nullable: true format: int32 example: 10 description: >- The number of additional bonus clicks, if applicable, or null if no limit is set. flagged_clicks: type: integer format: int32 example: 5 clicks_today: type: object properties: delivered: type: integer format: int32 example: 10 description: > Number of unique clicks that have been delivered today. "Today" is based on the time zone setting of the ClickMagick account. max_clicks_daily: type: integer nullable: true format: int32 example: 15 description: The maximum number of clicks that will be delivered in one day. status: type: string enum: - active - paused - archived example: paused description: > Is the rotator URL actively receiving clicks, or has it been paused or archived? status_paused_reason: type: string enum: - user_paused - max_clicks - max_clicks_daily - start_time - end_time example: user_paused description: > If `status` is `paused`, this explains the reason why the rotator URL has been paused. `user_paused` means that the URL was explicitly paused by the user and that no traffic will ever be delivered to this URL until it has been reset to the `active` state. All other paused states are temporary until another condition has changed. `max_clicks` means that all clicks have been delivered to this URL based on the `max_clicks` setting. `max_daily_clicks` means that all clicks for today have been delivered and traffic will resume tomorrow. `start_time` means that traffic is scheduled to start being delivered at a later, pre-set time, and `end_time` means that the `end_time` delivery time has already passed. RotatorURLStatsReport: allOf: - title: Rotator URLs Stats Report description: A report containing relevant rotator url statistics. type: object required: - last_updated - stats - total_seconds properties: last_updated: type: string format: date-time description: > The ISO-8601 timestamp indicating when this report was last updated. example: 2026-10-17T19:37:02Z stats: type: array items: $ref: '#/components/schemas/RotatorURLStatsObject' total_seconds: type: integer format: int32 minimum: 0 description: The number of seconds it took to generate this report. example: 39 - $ref: '#/components/schemas/GetReportProgressResponse' UserSettings: title: User Settings type: object properties: settings: type: object properties: date_range: type: string enum: - today - last_7_days - last_30_days - this_month - this_year - all_time description: > This is the default date range whenever you first log in to ClickMagick. time_zone: type: string description: > 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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) currency: type: string minLength: 3 maxLength: 3 default: USD description: > 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](https://www.iban.com/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. copy_to_clipboard: type: boolean description: > 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. show_subgroup_links: type: boolean description: >- 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. filter_abuser: $ref: '#/components/schemas/Filter' filter_anon: $ref: '#/components/schemas/Filter' filter_bot: $ref: '#/components/schemas/Filter' filter_server: $ref: '#/components/schemas/Filter' filter_spider: $ref: '#/components/schemas/Filter' filter_user: $ref: '#/components/schemas/Filter' tablet: type: string enum: - desktop - mobile description: > Treat traffic from tablet devices as either `mobile` or `desktop` traffic. default: desktop error_url: type: string nullable: true description: >- 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. blocked_country: type: array items: type: string default: [] description: > This is an array of two-letter country codes (`US` for United States, 'CA' for Canada, and so on). If this array has any values, it means that ClickMagick is set up to block clicks from those countries. Any click from countries in the list will be redirected to the URL set in `blocked_countries_url`. You can find a full list of two-letter country codes in the [International Banking (IBAN) Country Code List](https://www.iban.com/country-codes). blocked_countries_url: type: string nullable: true description: | If set, blocked country clicks are redirected to this URL. affiliate_username: type: string nullable: true description: > Is this user also an affiliate marketer for ClickMagick? This is their username if so. public_logo_type: type: string enum: - clickmagick_logo - custom_logo - no_logo custom_logo_image_url: type: string nullable: true description: >- The URL to the custom logo if the `public_logo_type` is set to `custom_logo`. custom_logo_link_url: type: string nullable: true description: >- If the custom logo is clicked on, the browser will be redirected to this URL. notify_conversions: type: boolean description: | Receive a notification by email each time you make a sale. invalid_click_threshold: type: integer description: > 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. status: type: string errors: type: array items: type: string warnings: type: array items: type: string headers: Retry-After: description: | How many seconds the caller should wait before retrying the request. schema: $ref: '#/components/schemas/retry_after' responses: '429': description: Too Many Requests headers: Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' example: errors: - too many requests retry_after: 3600 status: Error CreateReport: description: Create Report content: application/json: schema: $ref: '#/components/schemas/CreateReportResponse' GetReportProgress: description: Report generating content: application/json: schema: $ref: '#/components/schemas/GetReportProgressResponse' parameters: project_id: name: project_id in: path schema: type: integer format: int32 minimum: 1 required: true description: The project id for this request. example: 29583 attribution_model: name: attribution_model in: path schema: $ref: '#/components/schemas/AttributionModel' required: true description: The source data model to use for this report. report_id: name: report_id in: path schema: type: integer format: int32 minimum: 1 required: true description: The report id for this request. example: 3752921 cursor: name: cursor in: query schema: type: string description: | The cursor representing your current place in the results. example: ZBDkPOxCKRi limit: name: limit in: query schema: type: integer format: int32 minimum: 1 maximum: 100 default: 100 description: Maximum number of items to fetch for this page. example: 10 start_time: name: start_time in: query schema: type: string format: date-time description: > 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](https://en.wikipedia.org/wiki/ISO_8601). example: 2026-10-16T10:44:14Z end_time: name: end_time in: query schema: type: string format: date-time description: > 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](https://en.wikipedia.org/wiki/ISO_8601). example: 2026-10-17T19:37:02Z utm_source: name: utm_source in: query schema: type: string description: Only match results with this utm_source value. example: google utm_medium: name: utm_medium in: query schema: type: string description: Only match results with this utm_medium value. example: cpc utm_campaign: name: utm_campaign in: query schema: type: string description: Only match results with this utm_campaign value. example: end+of+season utm_term: name: utm_term in: query schema: type: string description: Only match results with this utm_term value. example: Hang+Ten utm_content: name: utm_content in: query schema: type: string description: Only match results with this utm_content value. example: best+surfboard requestBodies: getCampaignStatsByModel: description: A request to generate a campaign project stats report. content: application/x-www-form-urlencoded: schema: properties: start_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also [ISO-8601 in Wikipedia](https://en.wikipedia.org/wiki/ISO_8601). end_time: type: string format: date-time description: > 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`. Optional. If you omit both `start_time` and `end_time`, the report covers all time. Avoid this: always send both, and request only the date range you need. All-time reports are the slowest to generate, and requesting them repeatedly can quickly get you rate limited. See also [ISO-8601 in Wikipedia](https://en.wikipedia.org/wiki/ISO_8601). utm_source: type: string description: Only match results with this utm_source value. utm_medium: type: string description: Only match results with this utm_medium value. utm_campaign: type: string description: Only match results with this utm_campaign value. utm_term: type: string description: Only match results with this utm_term value. utm_content: type: string description: Only match results with this utm_content value. refresh: type: boolean default: false description: > 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. required: true