---
updatedAt: 2026-10-09T14:15:13.000Z
agentTools:
  projectIndex: https://dev.kevel.com/llms.txt
---

# Create Ads

## Why Create an Ad?

An ad is an important part of a flight and campaign, and can help in driving traffic to a website or domain. To create an ad, simply upload the creative associated with the ad to the system using the [Create Creative](https://dev.kevel.com/reference/create-creative) API call. After the creative is uploaded, pass the `CreativeID` as the `id` for the creative object.

An ad will be created, and the unique Ad ID returned may then be used to update or delete ads.

> 📘 Creating product-based ads?
>
> If you're using Kevel [Catalog](https://dev.kevel.com/docs/catalog), create ads directly from product data using the asynchronous [create ads from products](https://dev.kevel.com/reference/submit-jobs) Jobs endpoint.

## API Syntax

When using the Create Ads API call, it is important to understand the syntax required to make the request. There is a specific request format that must be followed to ensure the endpoint can process the request. The format is:

`POST https://api.kevel.co/v1/flight/{FlightID}/creative`

Where:

* `POST` - the type of API request being made.
* `https://api.kevel.co` - the URL for the request.
* `v1` - the API version.
* `flight` - the API endpoint being called.
* `FlightID` - the ID associated with the Flight.
* `creative` - indicates that we're mapping a Creative to the Flight.

## Additional Parameters

In addition to the parameters already listed above that can be passed as part of this request, there are a few additional parameters you can pass to further refine the ad being created. These parameters are listed in the table below.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Property
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `IsNetworkAd`
        (boolean)
      </td>

      <td>
        Indicates that ad comes from a 3rd party (i.e. uses 3rd party ad tags) - for use with Click Bucketing. If `true` = multiple clicks from the same IP address count as Unique Clicks
      </td>
    </tr>

    <tr>
      <td>
        `DontAffectParentFreqCap`\
        (boolean)
      </td>

      <td>
        "Opts-out" of frequency cap settings imposed on it by above
      </td>
    </tr>

    <tr>
      <td>
        `FreqCap`\
        (integer)
      </td>

      <td>
        The cap of the frequency cap. Instructions [here](https://dev.kevel.com/docs/ad-frequency-capping)
      </td>
    </tr>

    <tr>
      <td>
        `FreqCapDuration`\
        (integer)
      </td>

      <td>
        How long the frequency cap should apply. Instructions [here](https://dev.kevel.com/docs/ad-frequency-capping)
      </td>
    </tr>

    <tr>
      <td>
        `FreqCapType`\
        (integer)
      </td>

      <td>
        The unit for the frequency cap: `1 = Hour 2 = Day 3 = Minute`. Instructions [here](https://dev.kevel.com/docs/ad-frequency-capping)
      </td>
    </tr>
  </tbody>
</Table>

## Category Targeting

Use `CategoryTargeting` to set category rules on an Ad. It uses the same format as Flight [category targeting](https://dev.kevel.com/reference/create-flight#category-targeting): a list of rules, each with an `Id` and an `IsExclude` flag.

```json
"CategoryTargeting": [
  { "Id": "Electronics > Laptops", "IsExclude": false }
]
```

* An Ad with no explicit rules (`null` or an empty array) uses its Flight’s category rules.
* A non-empty list on the Ad replaces the Flight’s complete list. The two lists are not merged.
* Matching is exact and case-sensitive.

*Misc Notes*

**Goal**: If GoalType is 2 (Percentage), then a Goal of 100 represents a 100% goal. If GoalType is 1 (Impressions), then a Goal of 200000 represents a goal of 200,000 impressions. Note: when you GET a creative, you will see a value of "null" for Goal, and the goal should be represented as e.g. "Impressions": 200000 or "Percentage": 100. Our API does this conversion behind the scenes.

**IsGoalOverride**: You will see this `IsGoalOverride` field in the results of a GET request for an ad -- this indicates whether or not the flight-level goal is being overridden by an ad-level goal. When creating or updating an ad, however, you do not need to explicitly set `IsGoalOverride` -- it is set automatically based on whether or not you are supplying `GoalType` and `Goal`.

**IsStartEndDateOverride**: You will see `IsStartEndDateOverride` field in the results of a GET request for an ad -- this indicates whether or not the ad has its own start/end dates. When creating or updating an ad, however, you do not need to explicitly set `IsStartEndDateOverride` -- it is set automatically based on whether or not you are supplying `StartDateISO` and `EndDateISO`.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "adzerk-management-apis",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.kevel.co"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "X-Adzerk-ApiKey",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v1/flight/{FlightID}/creative": {
      "post": {
        "summary": "Create Ads",
        "description": "",
        "operationId": "create-ads",
        "parameters": [
          {
            "name": "FlightID",
            "in": "path",
            "description": "The ID of the Flight",
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "Creative"
                ],
                "properties": {
                  "Creative": {
                    "type": "object",
                    "description": "The `creativeID` you'll get when you create a creative, wrapped in an object, like `{\"Id\":12345}`. Or you may omit the `id` and specify a new Creative using the object structure described on [Create Creative](ref:create-creative).",
                    "required": [
                      "id"
                    ],
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "The ID of an existing Creative.",
                        "format": "int32"
                      }
                    }
                  },
                  "IsActive": {
                    "type": "boolean",
                    "description": "Whether ad should be eligible to serve. Defaults to `false`",
                    "default": false
                  },
                  "RtbCustomFields": {
                    "type": "string",
                    "description": "Required for RTB ads _only_. JSON Object in a String. It's JSON data provided by the RTB partner. Certain parameters in the object will be required per partner. If you aren't sure what is required, your account manager will supply you with the data for this property"
                  },
                  "ActiveKeywords": {
                    "type": "array",
                    "description": "For Keyword Targeting. Instructions [here](doc:enabling-keyword-targeting)",
                    "items": {
                      "type": "string"
                    }
                  },
                  "CustomTargeting": {
                    "type": "string",
                    "description": "Zerkel string for Custom targeting. Instructions [here](https://dev.kevel.com/docs/custom-targeting). The maximum string length for `CustomTargeting` is 1000 characters."
                  },
                  "SiteId": {
                    "type": "integer",
                    "description": "Site ID for Site Specific targeting",
                    "format": "int32"
                  },
                  "ZoneId": {
                    "type": "integer",
                    "description": "Zone ID for Zone Specific targeting",
                    "format": "int32"
                  },
                  "IsDeleted": {
                    "type": "boolean",
                    "description": "Whether it should be deleted"
                  },
                  "Iframe": {
                    "type": "boolean",
                    "description": "Whether Creative should use iFrame"
                  },
                  "SizeOverride": {
                    "type": "boolean",
                    "description": "Whether size needs to be overridden. Defaults to `false`",
                    "default": false
                  },
                  "IsStartEndDateOverride": {
                    "type": "boolean",
                    "description": "Whether you are overriding the start and end date"
                  },
                  "StartDateISO": {
                    "type": "string",
                    "description": "The start date for this ad in ISO 8601 format"
                  },
                  "EndDateISO": {
                    "type": "string",
                    "description": "The end date for this ad in ISO 8601 format"
                  },
                  "IsGoalOverride": {
                    "type": "boolean",
                    "description": "Whether you are overriding the goal on the ad"
                  },
                  "GoalType": {
                    "type": "integer",
                    "description": "If you are overriding the flight's goal, sets the target goal metric for ad. Key follows: `1 = Impressions` `2 = Percentage` `3 = Click` `7 = Any Conversions` `8 = Lifetime Revenue (integer)` `9 = Daily Revenue (integer)` `10 = Monthly Revenue (integer)`",
                    "format": "int32"
                  },
                  "Goal": {
                    "type": "integer",
                    "description": "The Goal Amount of `GoalType`",
                    "format": "int32"
                  },
                  "Price": {
                    "type": "number",
                    "description": "The Price value - instructions [here](https://dev.kevel.com/docs/ads#general-settings-of-an-ad)",
                    "format": "float"
                  },
                  "AttributionSettings": {
                    "type": "object",
                    "description": "Specify the products, categories, brands, and/or merchants that make a purchase eligible for attribution to this Ad. See [Attribution Overview](doc:attribution-overview) for more details.",
                    "properties": {
                      "AttributableItems": {
                        "type": "array",
                        "description": "The set of products, categories, and brands that may be attributed to this Ad. See [Kevel Attribution](doc:attribution-overview) for more details.",
                        "items": {
                          "properties": {
                            "MatchType": {
                              "type": "string",
                              "description": "The match type value determines the other keys included and corresponds to the Flight-level attribution setting for the specificity of the match.",
                              "enum": [
                                "SameProduct",
                                "SameCategoryBrand",
                                "SameBrand",
                                "SameMerchant"
                              ]
                            },
                            "ProductId": {
                              "type": "string",
                              "description": "The Product ID to use with the match. Use with `\"MatchType\": \"SameProduct\"` only."
                            },
                            "MerchantId": {
                              "type": "string",
                              "description": "The Merchant ID to use with the match. Use with `\"MatchType\": \"SameProduct\"` only."
                            },
                            "CategoryId": {
                              "type": "string",
                              "description": "The Category ID to use with the match. Use with `\"MatchType\": \"SameCategoryBrand\"` only."
                            },
                            "BrandId": {
                              "type": "string",
                              "description": "The Brand ID to use with the match. Use with `\"MatchType\": \"SameCategoryBrand\"` and `\"MatchType\": \"SameBrand\"`."
                            }
                          },
                          "type": "object"
                        }
                      }
                    }
                  },
                  "SearchTerms": {
                    "type": "object",
                    "description": "See [Search Term Targeting](doc:search-term-targeting).",
                    "properties": {
                      "Term": {
                        "type": "string",
                        "description": "The term to match against"
                      },
                      "IsExclude": {
                        "type": "boolean",
                        "description": "Indicate whether the term should positively (false) or negatively (true)",
                        "default": false
                      },
                      "MatchType": {
                        "type": "string",
                        "default": "\"Broad\"",
                        "enum": [
                          "\"Broad\"",
                          "\"Strict\"",
                          "\"Exact\""
                        ]
                      }
                    }
                  },
                  "CategoryTargeting": {
                    "type": "array",
                    "description": "The category targeting rules for the Ad, in the same format as on a Flight. An Ad that has category rules uses them instead of its Flight's rules, and the two lists are not merged. An Ad with no rules uses its Flight's rules. An Ad can hold up to 25 rules unless Kevel raises the limit for your network. A longer list returns a 400 with \"Your account has exceeded the limit for CategoryTargeting on this ad. Please contact support.\" Set the field to `null` or `[]` to remove the Ad's rules. If category targeting is not enabled for your network, Kevel ignores the field on writes and leaves it out of responses, and a malformed value still returns a 400. See [Set up category targeting](doc:set-up-category-targeting).",
                    "items": {
                      "type": "object",
                      "required": [
                        "Id",
                        "IsExclude"
                      ],
                      "properties": {
                        "Id": {
                          "type": "string",
                          "description": "The category to match, written exactly as your ad requests send it in `placements[].category`. Kevel trims spaces from the start and end when it saves the value, and matching is exact and case-sensitive. A parent category does not match its children. The value is a string of 1 to 200 characters."
                        },
                        "IsExclude": {
                          "type": "boolean",
                          "description": "`true` for an exclude rule, `false` for an include rule."
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "JSON": {
                  "value": {
                    "Creative": {
                      "Id": 12345
                    },
                    "FlightId": 1234,
                    "IsActive": true,
                    "StartDateISO": "2017-05-01T00:00:00.0000000",
                    "EndDateISO": "2017-12-05T00:00:00.0000000",
                    "ActiveKeywords": [
                      "kittens",
                      "cats"
                    ],
                    "CustomTargeting": "$keywords contains \"dean\"",
                    "SiteID": 1234,
                    "ZoneId": 12345,
                    "IsDeleted": false,
                    "Iframe": false,
                    "SizeOverride": false,
                    "FreqCap": 5,
                    "FreqCapDuration": 1,
                    "FreqCapType": 2,
                    "GoalType": 1,
                    "Goal": 200000,
                    "Price": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"IsActive\": true,\n  \"DontAffectParentFreqCap\": false,\n  \"Creative\": {\n    \"IsActive\": true,\n    \"ImageName\": \"\",\n    \"SaveEmptyCreative\": null,\n    \"Body\": \"\",\n    \"IsNetworkAd\": null,\n    \"Alt\": null,\n    \"Title\": \"Adzerk Creative\",\n    \"IsDeleted\": false,\n    \"IsSync\": null,\n    \"Url\": \"http://adzerk.com\",\n    \"IsIdOnly\": false,\n    \"IsNoTrack\": null,\n    \"TemplateValues\": null,\n    \"TemplateId\": null,\n    \"ImageLink\": \"http://s.zkcdn.net/Advertisers/\",\n    \"ScriptBody\": \"\",\n    \"AdvertiserId\": 123,\n    \"Metadata\": null,\n    \"AdTypeId\": 5,\n    \"IsHTMLJS\": false,\n    \"Id\": 12345\n  },\n  \"FreqCapType\": null,\n  \"EndDate\": null,\n  \"Iframe\": null,\n  \"ZoneId\": null,\n  \"IsDeleted\": false,\n  \"CustomTargeting\": \"$keywords contains \\\"dean\\\"\",\n  \"EndDateISO\": null,\n  \"RtbCustomFields\": null,\n  \"Impressions\": 100,\n  \"GoalType\": 1,\n  \"Goal\": 200000,\n  \"Price\": 1,\n  \"FreqCapDuration\": null,\n  \"Percentage\": 0,\n  \"FreqCap\": null,\n  \"IsStartEndDateOverride\": true,\n  \"CustomRelevancyScore\": null,\n  \"FlightId\": 7290072,\n  \"ActiveKeywords\": [\"kittens\", \"cats\"],\n  \"SiteId\": null,\n  \"CampaignId\": 123,\n  \"Id\": 12345,\n  \"IsGoalOverride\": true,\n  \"StartDateISO\": \"2017-05-01T12:00:00.0000000\",\n  \"EndDateISO\": \"2017-12-05T12:00:00.0000000\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "IsActive": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "DontAffectParentFreqCap": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "Creative": {
                      "type": "object",
                      "properties": {
                        "IsActive": {
                          "type": "boolean",
                          "example": true,
                          "default": true
                        },
                        "ImageName": {
                          "type": "string",
                          "example": ""
                        },
                        "SaveEmptyCreative": {},
                        "Body": {
                          "type": "string",
                          "example": ""
                        },
                        "IsNetworkAd": {},
                        "Alt": {},
                        "Title": {
                          "type": "string",
                          "example": "Adzerk Creative"
                        },
                        "IsDeleted": {
                          "type": "boolean",
                          "example": false,
                          "default": true
                        },
                        "IsSync": {},
                        "Url": {
                          "type": "string",
                          "example": "http://adzerk.com"
                        },
                        "IsIdOnly": {
                          "type": "boolean",
                          "example": false,
                          "default": true
                        },
                        "IsNoTrack": {},
                        "TemplateValues": {},
                        "TemplateId": {},
                        "ImageLink": {
                          "type": "string",
                          "example": "http://s.zkcdn.net/Advertisers/"
                        },
                        "ScriptBody": {
                          "type": "string",
                          "example": ""
                        },
                        "AdvertiserId": {
                          "type": "integer",
                          "example": 123,
                          "default": 0
                        },
                        "Metadata": {},
                        "AdTypeId": {
                          "type": "integer",
                          "example": 5,
                          "default": 0
                        },
                        "IsHTMLJS": {
                          "type": "boolean",
                          "example": false,
                          "default": true
                        },
                        "Id": {
                          "type": "integer",
                          "example": 12345,
                          "default": 0
                        }
                      }
                    },
                    "FreqCapType": {},
                    "EndDate": {},
                    "Iframe": {},
                    "ZoneId": {},
                    "IsDeleted": {
                      "type": "boolean",
                      "example": false,
                      "default": true
                    },
                    "CustomTargeting": {
                      "type": "string",
                      "example": "$keywords contains \"dean\""
                    },
                    "EndDateISO": {
                      "type": "string",
                      "example": "2017-12-05T12:00:00.0000000"
                    },
                    "RtbCustomFields": {},
                    "Impressions": {
                      "type": "integer",
                      "example": 100,
                      "default": 0
                    },
                    "GoalType": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "Goal": {
                      "type": "integer",
                      "example": 200000,
                      "default": 0
                    },
                    "Price": {
                      "type": "integer",
                      "example": 1,
                      "default": 0
                    },
                    "FreqCapDuration": {},
                    "Percentage": {
                      "type": "integer",
                      "example": 0,
                      "default": 0
                    },
                    "FreqCap": {},
                    "IsStartEndDateOverride": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "CustomRelevancyScore": {},
                    "FlightId": {
                      "type": "integer",
                      "example": 7290072,
                      "default": 0
                    },
                    "ActiveKeywords": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "kittens"
                      }
                    },
                    "SiteId": {},
                    "CampaignId": {
                      "type": "integer",
                      "example": 123,
                      "default": 0
                    },
                    "Id": {
                      "type": "integer",
                      "example": 12345,
                      "default": 0
                    },
                    "IsGoalOverride": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "StartDateISO": {
                      "type": "string",
                      "example": "2017-05-01T12:00:00.0000000"
                    },
                    "CategoryTargeting": {
                      "type": "array",
                      "description": "The category targeting rules saved on the Ad itself, each with an `Id` and `IsExclude`. An Ad with no rules of its own uses its Flight's rules, and they do not appear here. Left out when category targeting is not enabled for your network.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "Id": {
                            "type": "string",
                            "description": "The category the rule matches."
                          },
                          "IsExclude": {
                            "type": "boolean",
                            "description": "`true` for an exclude rule, `false` for an include rule."
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "## A minimally viable ad:\ncurl -X POST -H \"X-Adzerk-ApiKey:$ADZERK_API_KEY\" -H \"Content-Type:application/json\" \"https://api.kevel.co/v1/flight/12345/creative\" --data-binary '{\"Creative\":{\"Id\":12345},\"FlightId\":12345,\"IsActive\":true}'"
            },
            {
              "language": "javascript",
              "code": "const Adzerk = require('@adzerk/management-sdk');\nconst apiKey = process.env.ADZERK_API_KEY;\n\nasync function createAd() {\n  let specifications = await Adzerk.fetchSpecifications();\n  let client = await Adzerk.buildClient({apiKey, specifications});\n\n  let ad = await client.run('ad', 'create', {\n    creative: { id: 12345 },\n    flightId: 67890,\n    isActive: true,\n  });\n\n  console.log(ad);\n}\n\ncreateAd();"
            },
            {
              "language": "ruby",
              "code": "require \"adzerk\"\n\ndef create_ad()\n    client = Adzerk::Client.new(ENV[\"ADZERK_API_KEY\"])\n    creative = {\n        id: 12345\n    }\n    data = {\n        flight_id: 67890,\n        creative: creative \n    }\n    pp client.ads.create(data)\nend\ncreate_ad()"
            }
          ],
          "samples-languages": [
            "curl",
            "javascript",
            "ruby"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```