Creating Campaigns
When creating new campaigns, the best starting point is what we call the consolidated create API
POST /api/campaigns/consolidated/create
Several naviga clients are using this API endpoint today, in addition to the Propel team using it to import ads into the system from Propel. The goal of this was to consolidate, clean up and simplify getting orders into the system. This API will bring in the Campaign header and also line items (both print and/or digital), all in one API.
Once created, the system will pass back to you the following information:
{
"NewCampaignID": "string",
"NewLines": [
{
"ID": "string",
"ThirdPartyLineID": "string",
"MaterialIDs": [
"string"
],
"ProductID": "string",
"AdTypeID": "string",
"IsPrintProduct": true,
"Amount": 0,
"TaxAmount": 0,
"TotalWithTax": 0
}
]
}This API does not do all the same validation that an ad created internally would do, so please do use caution when using this. If you create a line with an AdType that isn't allowed for the product, or an invalid ratecard ID, etc, it will still create a campaign and an order line, but there will be missing data if it isn't correct for the line, so a user opening that line later, may see error messages or the campaign may re-rate if something else is edited and the line resaved, so please use this cautiously and test thoroughly before going live with something new.
CampaignID
This can be left off for Naviga to assign the next sequential campaign ID, or it can be set to "NEW" To add additional order lines to an existing campaign, use the existing campaign ID here. Campaign level details are NOT updated with this API.
No
AdvertiserID
ID for the advertiser on the Campaign
Yes
BrandID
ID for the Brand (of the above advertiser) for this campaign
Yes
ProductGroupID
ID for the assigned product for this campaign
Yes
CampaignType
Options here are Flexible or Performance
Yes
AgencyID
If this is to be billed to an agency, then the agency ID is required
No
AgencyCommissionPercent
If there is an agency present and if that agency should get a commission, enter the commission percent here. (enter 15 for 15% commission). It will not look up the commission amount from the brand, so this is required to receive a commission, but is not a requirement to successfully import a campaign.
No
StartDate
This is the start date of the campaign - it needs to be equal to or sooner than the earliest start date of a line item.
Yes
EndDate
This is the end date of the campaign. It needs to equal to or after the furthest end date of a line item
Yes
CampaignStatusID
These would be the ID of the Campaign Status. Common options include Q1, Q2, Q3, R1, R2, R3, CO
Yes
PONumber
Optional PO number on the campaign. The import does not check for PO Required settings on the payor.
No
Description
This is the campaign description
No
ExternalID
Unique identifier from an external system (for example the iPublish ID, or other 3rd party provider.)
No
CurrencyID
Leave blank for the default system currency or enter a currency ID for a foreign currency
No
OverrideSalesRepID
Enter a REP ID here and it will set this user as the Original Rep and the Order Rep on a new campaign
No
ExternalSystemID
This relates to External ID above. When using multiple 3rd party systems, you may set up External SystemID's in Setup -> System Tables Setup -> External System ID Codes
No
IsPrePaid
true / false are the valid choices.
If true, there will be an InvoiceID of IMPORT auto-created on the Invoices and payments tab in Naviga Ad, which will prevent this campaign from billing from the Naviga Ad system. For a flexible campaign, a billing schedule will be created and the invoice will be set to "IMPORT". This doesn't create an invoice in Naviga, but tells the system that it was already invoiced elsewhere and thus prevents Naviga from creating a duplicate of that invoice.
If you want Naviga Ad to generate an invoice for this item for revenue recognition purposes, then this should be set to false. If it was prepaid in the other system, but you want Naviga to record the payment for G/L purposes and so the client gets a zero balance invoice, use this API to attach the prepayment record to the campaign:
POST /api/campaigns/{campaignId}/prepayments
No
DigitalLines [ ]
If there are digital lines on this campaign, this array will repeat for each digital line.
AutoAllocationMonthlyLines
If this is set to True, then you do not need the DigitalMonths array. (described a little later in this table) With this set to True, the setting MonthlyDistributionType should also be filled in so that the system knows how to distribute the numbers.
If this is set to false, then the system will be expecting the import to tell it what amounts are expected in each month. So in an example campaign running from Jan 1 to March 31, the digital months array will be repeated 3x, once for each month, with the monthly quantity and amount provided to it.
Yes
StartDate
Start Date of this Line
Yes
EndDate
End Date of this Line
Yes
ID
For a new line, this is not needed and should be omitted. Use an existing line ID here to REPLACE an existing campaign line. Couple of caveats to be aware of here:
If you use this field, then the Month Unique Ids must also be a passed in (this is a unique id for each month / issue).
The API will prevent changes if:
Any of the original months have been billed and now changed (changes to the date / quantity / amount). Error message returned is “cannot change billed month”
Any of the original months were billed and now removed. Error message returned is “cannot removed billed order”
The API does not do this check if the original order was imported and marked as already billed. It only does it if there is a real, Naviga-created InvoiceID present.
No
ProductID
This is the ID of the product from Naviga product setup.
Yes
AdTypeID
This is the ID from AdType Setup (Setup -> Advertising Setup -> Ad Types)
Yes
ContractID
If the customer has a contract and you wish to have the campaign count towards that contract, enter the ID.
No
RatecardID
This is the Ratecard ID from Ratecard setup (In Setup -> Product Setup). The import will error if this is missing - it isn't validating that it is CORRECT, but it is looking for it to be present, so use caution.
Yes
RateLineID
This is the Ratecard Line ID from Ratecard setup (In Setup -> Product Setup). The import will error if this is missing - it isn't validating that it is CORRECT, but it is looking for it to be present, so use caution.
Yes
SectionID
This is the section ID from Product setup. If this is set on the Ratecard and UseRatecardLineSettings is set to true, this can be skipped and the information will be pulled from the ratecard.
No
PositionID
This is the position ID from Product setup. If this is set on the Ratecard and UseRatecardLineSettings is set to true, this can be skipped and the information will be pulled from the ratecard.
No
MaterialStatusID
These are found under Setup -> Production Workflow Setup. Select a product from the dropdown and the Stage number is considered to be the ID.
No
ThirdPartyLineID
This will populate the 3rd Party Line ID field on the campaign line (Other tab)
No
PONumber
This is the PO number for the line (if different from the campaign header)
No
Description
This is the line item description. This is not required, but not pulling from the Ratecard line settings. So enter something here if you don't want it to be blank on import.
No
UseRatecardLineSettings
For some items in Ratecard setup, setting this to true will tell the API to set it from the rate card settings instead of needing to enter it explicitly here. A true here will set the following from Ratecard Setup: Section ID Position ID Google Targeting Ratecard Rate Discount Rate Expected sizes Master Sizes Size Counts Creative Type If set to false, these will not be set based on ratecard setup
yes
Materials [ ]
If material are to be linked to this order, enter the material IDs here (the materials can be created with the Material Creation API) For multiple materials, repeat this array as many times as you need to for each material
No
ID
This is the ID of the material
No
StartDate
this is the date when the material will begin to serve on this campaign line If not provided, the start/end dates will be the line start and end.
No
EndDate
this is the date when the material will stop serving on this campaign line
No
RatecardRate
Enter the ratecard price
If using the setting below is set to true, then this field can be omitted and the ratecard settings will be used.
(This field requires 26.1 and later to support omitting and using RatecardLineSettings)
Yes
DiscountRate
If there is no discount, the ratecard price will be repeated. If this is being charged a premium or discount, enter the adjusted rate here. The system will automatically add the adjustment line for the difference between the rate and the discount. So if the rate is $10 CPM, and there is no discount, enter $10 for both the Ratecard rate and the discount rate. If using the setting below is set to true, then this field can be omitted and the ratecard settings will be used.
(This field requires 2026.1 and later to support omitting and using RatecardLineSettings)
Yes
Qty
Enter the quantity here. For Flat Fee, this can just be 1.
Yes
AdserverOverrideQty
This will set an override quantity for sending to GAM.
No
OrderTotal
This should be set as the total of the Rate*Qty.
If using the setting below is set to true, then this field can be omitted and the ratecard settings will be used.
(This field requires 26.1 and later to support omitting and using RatecardLineSettings)
Yes
CostRateOverride
If using Cost Rates on Rate Card setup this can be used to override the cost rate
No
MonthlyDistributionType
Options here are "Days" or "Evenly" If nothing is sent, Days will be used.
No
DigitalMonths [ ]
This group (from ID to Invoice ID) are required only if the setting above "AutoAllocationMonthlyLines" is set to false. If AutoAllocationMonthlyLines is TRUE, you do not need this section.
see description
ID
This is the ID for the digital month. For a new digital month, this can be omitted or "NEW" can be used to tell the API it is a new month
No
StartDate
Start date of the month (for example, January would be 2026-01-01 here for the full month). If this is the first month of a multi-month line, the start date might not be the first of the month.
Yes
EndDate
End date of the month (for example, January would be 2026-01-31 here for the full month). If it is the last month of the line, this might end before the last of the month.
Yes
Qty
The expected quantity for the month
Yes
Amount
The expected amount for the month
Yes
InvoiceID
The invoice ID for the month (only if invoiced)
No
GoogleTargeting
This section will set some google targets. This was added for the Naviga Propel team to be able to import some basic Geo and AdUnit targeting for customer self-service orders. Some others may find it helpful as well.
No
PlacementIDs
These placement IDs are the GAM Id's which can be found in GAM or in Ad Server Integration Setup inside Naviga ad. If these are set on the RateCard Line, and you wish to ignore what is on the RateCard line and instead import as a blank, then import "**" and we will interpret that as a null. (Even if UseRatecardLineSettings is set to true, putting ** here will override this GAM targeting to null.)
No
IncludedAdUnitIDs
These Ad Unit IDs are the GAM Id's which can be found in GAM or in Ad Server Integration Setup inside Naviga ad. If these are set on the RateCard Line, and you wish to ignore what is on the RateCard line and instead import as a blank, then import "**" and we will interpret that as a null. (Even if UseRatecardLineSettings is set to true, putting ** here will override this GAM targeting to null.)
No
ExcludedAdUnitIDs
Same as above, but this will exclude those ID's
No
GeoTargets
No
ID
These GeoTarget IDs are the GAM Id's which can be found in GAM or in Ad Server Integration Setup inside Naviga ad. If these are set on the RateCard Line, and you wish to ignore what is on the RateCard line and instead import as a blank, then import "**" and we will interpret that as a null. (Even if UseRatecardLineSettings is set to true, putting ** here will override this GAM targeting to null.)
No
IncludeOrExclude
Use the letter I for "Include" to Include the geo and E for "Exclude" to exclude it.
No
NewProductionNote
This string field will pass in a production note on a campaign line (will be time stamped automatically and the user name will be the API User.)
No
ExistingProductionNote
You cannot update or "create" an existing Production Note. This array can be ignored on the initial create, but it will be passed back to you in a "GET" when Editing/Updating Campaign lines. For new notes, use the NewProductionNote above
No
PrintLines [ ]
If only digital lines are on the campaign, this entire section can be omitted.
No, unless it is a print order
ID
For a new line, this is not needed and should be omitted. Use an existing line ID here to REPLACE an existing campaign line. Couple of caveats to be aware of here:
The API will prevent changes if:
Any of the original issues have been billed and now changed (changes to the date / quantity / amount). Error message returned is “cannot change billed month”
Any of the original issues were billed and now removed. Error message returned is “cannot removed billed order”
The API does not do this check if the original order was imported and marked as already billed. It only does it if there is a real, Naviga-created InvoiceID present.
ProductID
This is the ID of the product from Naviga product setup.
Yes
AdTypeID
This is the ID from AdType Setup (Setup -> Advertising Setup -> Ad Types)
Yes
ContractID
If the customer has a contract and you wish to have the campaign count towards that contract, enter the ID.
No
RatecardID
This is the Ratecard ID from Ratecard setup (In Setup -> Product Setup). The import will error if this is missing - it isn't validating that it is CORRECT, but it is looking for it to be present, so use caution.
Yes
RatecardLineID
This is the Ratecard Line ID from Ratecard setup (In Setup -> Product Setup). The import will error if this is missing - it isn't validating that it is CORRECT, but it is looking for it to be present, so use caution.
Yes
SectionID
This is the section ID from Product setup. If this is set on the Ratecard and UseRatecardLineSettings is set to true, this can be skipped and the information will be pulled from the ratecard.
No
PositionID
This is the position ID from Product setup. If this is set on the Ratecard and UseRatecardLineSettings is set to true, this can be skipped and the information will be pulled from the ratecard.
No
Materials [ ]
MaterialID
Pass in Material ID here, if a material ID already exists and you wish to reference it in a pickup. If left blank and the Auto Create Material flag is yes on the product, then a new material ID will be set upon import. If left blank and the Auto Create Material flag is no on the product, then the line will be created with no material. See also Material Creation API. Material can be created first and then used here when the Auto Create Flag is set to No on the product and the desire is to create a material for new order lines upon import.
No
PONumber
This is the line item PO number, which may be different from the campaign PO number
No
LineDescription
This is the line item description. While not required, it is often displayed on a confirmation/Invoice/Statement so may be important.
No
EditionID
If using Zones/Editions, this may be important.
No
Columns
If using a non-modular size, this will be important for determining the size of the ad.
No
Depth
If using a non-modular size, this will be important for determining the size of the ad.
No
LineCount
If using modular size this will be important for determining the page equivalency. Not technically required for the import to work, but likely required for some reporting if you are tracking Page eq
No
UseRatecardLineSettings
For some items in Ratecard setup, setting this to true will tell the API to set it from the rate card settings instead of needing to enter it explicitly here. A true here will set the following from Ratecard Setup: Ratecard Rate Discount Rate Section Position Dimensions Color Code A false he will require these fields to be set in the import data
Yes
RatecardRate
If UseRateCardSettings (above) is set to true, and this line is to use the ratecard rate, then this may be omitted. If using a custom rate, then this should be entered here and UseRateCardSettings should say false.
(This field requires 26.1 and later to support omitting and using RatecardLineSettings)
Yes/No (depending on UseRateCardSettings)
DiscountRate
If there is to be a discount, this will be the rate after discounts (the system will calculate the adjustment as the difference between this amount and the ratecard rate above).
If using the setting below is set to true, and there is no discount needed, then this field can be omitted and the ratecard settings will be used.
(This field requires 26.1 and later to support omitting and using RatecardLineSettings)
Yes/No (depending on UseRateCardSettings)
Qty
not typically needed for a standard print ad, but could be needed if it is an issue based ad using a cost per unit price.
No
OrderTotal
Only necessary if UseRateCardSettings is false
(This field requires 26.1 and later to support omitting and using RatecardLineSettings)
No
IssueDates [ ]
ID
Not necessary on a post. the ID under the issue date would only be relevant if you were updating the data. Then it would be formatted as the line ID (dot) issue number (so 12345.1 for the first issue of order 12345).
No
Date
Date of the issue. Formatted as yyyy-mm-dd
No
Qty
not needed unless this was a CPU type buy. Most print ads wouldn't need a quantity.
No
Amount
This should reflect the amount that should be on the issue date. (So if this is a discounted amount, this should be net of any adjustments.)
Yes
MaterialID
Materials could change per issue, so if there is more than one material in the Material ID array above, then this will tell the system which material is to be used for which insertion date. If this is blank, and the product is set to auto-create materials, then a material ID will be created here. If this is blank and the product is set to NOT auto-create materials, then the issue date will not have a material applied and it can be updated later to include the material.
No
MaterialProductionStatusID
These are found under Setup -> Production Workflow Setup. Select a product from the dropdown and the Stage number is considered to be the ID.
No
InvoiceID
The invoice ID for the month (only if invoiced)
No
CategoryTreeID
If this is a classified type ad, then enter the ID for the category tree here. This can be found in Setup -> Classified Category Tree Setup
No
CategoryID
If this is a classified type ad, then enter the ID for the category here This can be found in Setup -> Classified Category Tree Setup. Select the tree and then Click on a subcategory to see the ID
No
BasePrice
If this is an ad type with "is listing" flag set, then it is available for Ratecards which are rated with Base prices and overage prices. This is for the Base Price of that type of ad.
No
BaseQty
If this is an ad type with "is listing" flag set, then it is available for Ratecards which are rated with Base prices and overage prices. This is for the Base Quantity of that type of ad.
No
OverageRate
If this is an ad type with "is listing" flag set, then it is available for Ratecards which are rated with Base prices and overage prices. This is for the Overage Price of that type of ad.
No
OverageQty
If this is an ad type with "is listing" flag set, then it is available for Ratecards which are rated with Base prices and overage prices. This is for the Overage Quantity of that type of ad.
No
NewProductionNote
This string field will pass in a production note on a campaign line (will be time stamped automatically and the user name will be the API User.)
No
ExistingProductionNote
You cannot update or "create" an existing Production Note. This array can be ignored on the initial create, but it will be passed back in a "GET" when Editing/Updating Campaign lines. For new notes, use the NewProductionNote above
No
Was this helpful?