v1

latestOpenAPI 3.1.02026-07-2616636641.7 KB

Create Flight

This API call adds a new flight to a campaign.

post/v1/flight

Request body

Namestring required

The flight name. Max length is 300 characters.

StartDateISOstring required

UTC start date in ISO 8601 format: YYYY-MM-DDTHH:MM:SS.SSSSSSS. This can also be sent in the format of YYYY-MM-DD.

CampaignIdinteger required

The ID of the campaign.

PriorityIdinteger required

The ID of the Priority. Here are the Priority API endpoints.

GoalTypeinteger required

This is the metric that Kevel uses to pace the ads so it hits the desired goal by the end date. Key follows: 1 = Impressions 2 = Percentage 3 = Click 7 = Conversion 8 = Revenue 9 = Daily Revenue 10 = Monthly Revenue. Instructions are here

Impressionsinteger required

The goal amount - specifies the number of GoalTypes to aim for during the life of the campaign. For Revenue, Daily Revenue and Monthly Revenue Goal Types the maximum Goal Amount is 500000000. For all other GoalTypes the maximum Goal Amount is 2147483647. Instructions are here. Note: the field is named Impressions even if Goal Type is not set to Impressions.

IsActiveboolean required

Specifies whether campaigns should be active or inactive. Defaults to false.

RateTypeinteger required

The Rate value - instructions here. Key: 1 = Flat 2 = CPM 3 = CPC 4 = CPA View 5 = CPA Click 6 = CPA View & Click.

EndDateISOstring

UTC end date in ISO 8601 format: ``YYYY-MM-DDTHH:MM:SS.SSSSSSS. You can also send in a standard date of YYYY-MM-DD. **Required** if GoalTypeis not2, 9or10`.

IsDeletedboolean

Specifies whether flight should be deleted. Do not use when creating a flight. Defaults to false.

Pricenumber float

The Price value - instructions here.

CapTypeinteger

The cap type metric. Instructions here. Key: 1 = Impressions 2 = Clicks 3 = Conversions 4 = Revenue. Do not set to 0 - if removing, set to null.

DailyCapAmountinteger

The maximum # of CapType per day. Instructions here.

LifetimeCapAmountinteger

The maximum # of CapType per lifetime. Instructions here.

Keywordsstring

Keywords used for targeting. Instructions here.

CustomTargetingstring

Zerkel string for Custom targeting. Instructions here. The maximum string length for CustomTargeting is 1000 characters.

CustomFieldsJSONstring

Sets the value of custom fields based on a custom fields schema. Must contact support before use. More info here.

IsFreqCapboolean

Set to true if doing capping. If false or null, then the other Freq fields are ignored. Learn more about FC here. If not already enabled, you'll need your account manager to enable it.

FreqCapinteger

The number of times the frequency cap should occur. Cannot be 0 unless FreqCapType is None (0).

FreqCapDurationinteger

Specifies how often the frequency cap should occur. Cannot be 0 unless FreqCapType is None (0).

FreqCapTypeinteger

Specifies which unit of time you would like frequency capping to occur. Key: 1 = Hour 2 = Day 3 = Minute.

DontAffectParentFreqCapboolean

If true, opts-it out of frequency cap settings imposed at advertiser or campaign level.

IsCompanionboolean

If true, enables companion ads. IsCompanion must be set to false when IsNoDuplicates is true, and vice versa. Learn more here.

isNoDuplicatesboolean

If true, enables no duplicates. IsCompanion must be set to false when IsNoDuplicates is true, and vice versa.

DuplicateModeinteger

Indicates which level no duplicates should be enforced on. Key follows: 1: Flight 2: Campaign 3: Advertiser 4: Creative.

DeliveryStatusinteger

Read-only. Status of the flight. The mapping of the status against the UI are in brackets. Key: 0 = Pending (blue) 1 = Healthy (green) 2 = BorderLine (amber) 3 = InDanger (red) 5 = Underdelivered (amber).

IsTrackingConversionsboolean

If true, enables conversion tracking endpoints/pixels.

CanPassbackboolean

Sets whether a flight in an adChained-enabled priority can pass back to the next flight in the adChain.

PassbackSortOrderinteger

Sets the order of a flight in the adChain. PassbackSortOrder is a transient value that can be modified by internal processes in the UI. Although the value may change, the actual sort order of flights in the adChain will remain consistent. Setting two flights to the same PassbackSortOrder will cause the flights to be chosen randomly. Setting PassbackSortOrder to 0 will cause the flight to appear as "--" in the UI, but the flight will still be part of the adChain. This is not recommended.

IsECPMOptimizedboolean

Specifies whether ECPM Optimization is enabled.

ECPMOptimizePeriodinteger

Timeframe to optimize for [1 - 90 days].

ECPMMultipliernumber float

The final eCPM will be multiplied by this amount. Must be at least 0.01.

FloorECPMnumber float

Minimum eCPM. Must be at least 0.01.

CeilingECPMnumber float

Maximum eCPM. Must be at least 0.01.

DefaultECPMnumber float

This is the eCPM that will be used while the Flight is in burn-in mode. Must be at least 0.01.

ECPMBurnInImpressionsinteger

Impressions per creative to show before using the calculated eCPM over the default eCPM [1 - 2147483648].

EffectiveCPMOverridenumber float

Sets a manual override to a flight's CPM, e.g. so a Flat Rate flight can compete in an auction priority.

DatePartingStartTimeISOstring

Targets the flight to certain hours within a day. Use ISO 8601 format: HH:MM:SS. (This parameter is part of Kevel's legacy day parting features. It is still supported, but will be ignored if a Flight has one or more new day parts. Learn more about new day parting features here and about legacy day parts here.)

DatePartingEndTimeISOstring

IsSundayboolean

If true, targets this day. Defaults to false if you have filled in the DateParting fields. (This parameter is part of Kevel's legacy day parting features. It is still supported, but will be ignored if a Flight has one or more new day parts. Learn more about new day parting features here and about legacy day parts here.)

IsMondayboolean

IsTuesdayboolean

IsWednesdayboolean

IsThursdayboolean

IsFridayboolean

IsSaturdayboolean

IsArchivedboolean

Specifies whether flight is archived.

RequireStrictLocationboolean

If true, the ad request needs exact longitude and latitude in order to use GeoDistance targeting settings.

TimeZonestring

Sets a supported IANA time zone string to be used for the flight's daily caps, daily goals, and day parting. Note that even if a non-UTC TimeZone is set, start and end dates will still be in UTC.

IsTargetingOptimizationboolean

Legacy parameter

TargetingOptimizationTypeinteger

Legacy parameter

TargetingOptimizationTargetTypeinteger

Legacy parameter

TargetingOptimizationTargetnumber float

Legacy parameter

TargetingOptimizationBurnIninteger

Legacy parameter

TargetingOptimizationCanMissboolean

Legacy parameter

TargetROASnumber float

For CPC/CPA/CPM auctions, a target return can be selected on ad spend (ROAS) goal and the decision engine will automatically adjust the CPC/CPA/CPM bid to try to achieve the goal set. Acceptable values are expressed as a decimal between 0.01–99.99. This is equivalent to 1%–9,999%.

Response

200

Idinteger

StartDateISOstring

EndDateISOstring

NoEndDateboolean

Priceinteger

Impressionsinteger

IsNoDuplicatesboolean

IsCompanionboolean

Keywordsstring

Namestring

IsFreqCapboolean

CampaignIdinteger

PriorityIdinteger

DeliveryStatusinteger

IsDeletedboolean

IsActiveboolean

{"stackTrail":"paths:/v1/flight:post:responses:200:content:application/json:schema:properties:CustomTargeting","oasType":"schema","type":"unknown"}

GoalTypeinteger

RateTypeinteger

IsECPMOptimizedboolean

ECPMOptimizePeriodinteger

ECPMMultipliernumber

FloorECPMnumber

CeilingECPMnumber

DefaultECPMnumber

ECPMBurnInImpressionsinteger

EffectiveCPMOverridenumber

{"stackTrail":"paths:/v1/flight:post:responses:200:content:application/json:schema:properties:DatePartingStartTimeISO","oasType":"schema","type":"unknown"}

{"stackTrail":"paths:/v1/flight:post:responses:200:content:application/json:schema:properties:DatePartingEndTimeISO","oasType":"schema","type":"unknown"}

IsSundayboolean

IsMondayboolean

IsTuesdayboolean

IsWednesdayboolean

IsThursdayboolean

IsFridayboolean

IsSaturdayboolean

TimeZonestring

FreqCapinteger

FreqCapDurationinteger

FreqCapTypeinteger

CapTypeinteger

DailyCapAmountinteger

LifetimeCapAmountinteger

{"stackTrail":"paths:/v1/flight:post:responses:200:content:application/json:schema:properties:CustomFieldsJson","oasType":"schema","type":"unknown"}

{"stackTrail":"paths:/v1/flight:post:responses:200:content:application/json:schema:properties:IsArchived","oasType":"schema","type":"unknown"}

IsTrackingConversionsboolean

RequireStrictLocationboolean

CanPassbackboolean

PassbackSortOrderinteger

Example response

{
  "Id": 1234,
  "StartDateISO": "2017-05-01T00:00:00.0000000",
  "EndDateISO": "2017-12-31T00:00:00.0000000",
  "Price": 5,
  "Impressions": 10000,
  "IsCompanion": true,
  "Keywords": "exercise",
  "Name": "Basic Flight",
  "IsFreqCap": true,
  "CampaignId": 1234,
  "PriorityId": 1234,
  "IsActive": true,
  "GeoTargeting": [
    {
      "CountryCode": "US",
      "Region": "NC",
      "MetroCode": 560
    }
  ],
  "SiteZoneTargeting": [
    {
      "SiteId": 123,
      "ZoneId": 321
    }
  ],
  "GoalType": 1,
  "RateType": 2,
  "IsECPMOptimized": true,
  "ECPMOptimizePeriod": 30,
  "ECPMMultiplier": 1.25,
  "FloorECPM": 0.15,
  "CeilingECPM": 0.35,
  "DefaultECPM": 0.28,
  "ECPMBurnInImpressions": 1000,
  "IsSunday": true,
  "IsSaturday": true,
  "TimeZone": "America/New_York",
  "FreqCap": 2,
  "FreqCapDuration": 10,
  "FreqCapType": 1,
  "CapType": 1,
  "DailyCapAmount": 5000,
  "LifetimeCapAmount": 50000,
  "BehavioralTargeting": {
    "onClick": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    },
    "onConvert": {
      "stopShowingAdsFromFlight": true,
      "stopShowingAdsFromAdvertiser": true,
      "storeCategoriesFromFlightAsInterest": true
    }
  },
  "IsTrackingConversions": true,
  "CanPassback": true,
  "PassbackSortOrder": 1
}