Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview

Create a Campaign Plan

Creates a Campaign Plan. A Campaign Plan is the AdCrunch planning document. It is not a provider campaign. For provider campaigns, see the entities in the Observe API.

Only a name, a description and a currency are necessary. You write the window, the budget envelope and the Brand one part at a time. Write each amount in whole units of the currency: 40.5 is €40.50.

The new plan starts in draft. The answer is 409 if the slug already exists in your organization.

POST/context/campaign-plans
Authorization
AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>.

Use an API key (acr_…), from the AdCrunch console under Settings → API keys.

The credential names the organization, and no operation takes an organization parameter.

See https://docs.adcrunch.dev/api/authentication.

Request body
requiredapplication/json
brand_namestring

The Brand's slug. Optional and re-pointable — a Campaign Plan may precede its brand or cover a portfolio. Addressed by slug because that is the handle every Context surface uses; the Campaign Plan stores the id.

currencystringrequired

ISO 4217. Editable while no Line Item carries a budget, frozen thereafter.

min length 3 · max length 3
descriptionstringrequired

One-line summary — what a reader picks this Campaign Plan by.

min length 1 · max length 500
end_datestring

Omit for an always-on plan. Line Items inherit this.

matches ^\d{4}-\d{2}-\d{2}$
measurementstring

How success will be judged (markdown).

min length 1
namestringrequired

Display name.

min length 1 · max length 120
rationalestring

The argument for the split — what a reviewer approves (markdown).

min length 1
slugstring

Optional explicit slug handle; normalized to kebab-case. Defaults to one derived from the name.

max length 120
start_datestring
matches ^\d{4}-\d{2}-\d{2}$
total_budgetnumber

The envelope: what we have. Omit for "no declared constraint" — which is not the same as zero.

min 0
Responses
201

The Campaign Plan as created, in draft, at revision 1, with no rows. allocation.allocated is 0 and unallocated is the whole envelope.

allocationobjectrequired

Derived on every read. Never stored.

Show properties
allocatednumber | nullrequired

The sum of the Line Item budgets. null when the lines mix units, because that sum would be meaningless.

comparablebooleanrequired

False when the lines mix totals and daily rates. A surface must then print "not comparable" rather than a plausible-looking wrong total.

unallocatednumber | nullrequired

The envelope less the allocated, where both are known.

unitstring | nullrequired

The shared unit, when the lines agree on one.

Allowed:totaldaily
brandIdstring | nullrequired

Nullable and mutable: a plan may precede its brand, cover a portfolio, or be re-pointed. Deleting a Brand leaves its plans standing.

createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

createdBystringrequired
currencystringrequired

Editable until the first Line Item budget, and frozen thereafter.

descriptionstringrequired
endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

idstringrequired
lineItemsobject[]required
Show properties
Array of object
advertiserIdstring | nullrequired
ageMaxnumber | nullrequired
ageMinnumber | nullrequired

Each bound is independently optional, so "35+" is expressible.

budgetnumber | nullrequired

Whole units of the plan’s currency.

campaignPlanIdstringrequired
channelstringrequired

The planner’s word for what is being bought, not a provider name. A plan may name a channel we cannot execute.

Allowed:metatiktoksnapchatgoogle_searchgoogle_pmaxgoogle_displayyoutubeprogrammatic_displaylinkedinx
countriesstring[]required
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

createdBystringrequired
effectiveEndDatestring | nullrequired

The line’s own bound where it has one, else the plan’s.

effectiveStartDatestring | nullrequired

A calendar date, YYYY-MM-DD.

endDatestring | nullrequired

A calendar date, YYYY-MM-DD.

executablebooleanrequired

Whether this channel could be executed at all today. Derived from our capabilities, never a promise that it will be.

executionsobject[]required

What this line has spawned. Never a claim that it is finished — nobody declared how many objects a line should produce.

Show properties
Array of object
advertiserIdstringrequired
createdAtnumberrequired

Milliseconds since the Unix epoch, UTC.

entityIdstringrequired

The provider’s own id, unprefixed, so it joins to entities.

entityTypestringrequired

The provider’s word for the level — campaign, adset, ad.

idstringrequired
mutationWorkflowIdstring | nullrequired

The durable execution that performed the write, when known.

providerstringrequired
genderstring | nullrequired
Allowed:allmenwomen
idstringrequired
objectivestringrequired
Allowed:awarenessengagementleadssalestrafficapp_promotion
personaIdstring | nullrequired

Explains the targeting; never supplies its values.

providerstring | nullrequired

Who sells this channel, or null when nobody we integrate with does.

revisionnumberrequired

Increments on every write. Send it back as base_revision to edit; a stale one answers 409.

startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired

validated is the gate on execution.

Allowed:draftvalidated
unitstringrequired

How budget reads, derived from the effective end date. Present → a total for the period; absent → a daily rate. A surface must print this beside the amount.

Allowed:totaldaily
updatedAtnumber | nullrequired

Milliseconds since the Unix epoch, UTC.

measurementstring | nullrequired
namestringrequired
rationalestring | nullrequired
revisionnumberrequired

Increments on every write. Send it back as base_revision to edit; a stale one answers 409.

slugstringrequired
startDatestring | nullrequired

A calendar date, YYYY-MM-DD.

statusstringrequired

The only two stored states. active, closed and "executed" are derived, never stored.

Allowed:draftapproved
totalBudgetnumber | nullrequired
updatedAtnumber | nullrequired

Milliseconds since the Unix epoch, UTC.

400

The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. error is invalid_request, and issues names each field. Nothing was changed.

issuesobject[]required

One entry for each field that does not match.

Show properties
Array of object
instringrequired

The part of the request that holds the field.

Allowed:bodycookieheadersparamsquery
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

pathstringrequired

A JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:invalid_request
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

401

No API key, or one that does not resolve. See the security scheme. error is unauthorized.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:unauthorized
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

403

The caller does not hold campaign_plan:write. error is forbidden.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:forbidden
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

404

brand_name names no Brand in this organization. error is not_found. Despite its name the field takes a Brand slug.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

409

Another Campaign Plan already holds that slug. error is slug_conflict.

slugstringrequired

The slug that is already taken.

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

Allowed:slug_conflict
messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

422

Four codes share this status. invalid_slug; invalid_currency (it must be a three-letter ISO 4217 code); invalid_amount (an amount has no more decimals than its currency, and is never negative); invalid_window (the end precedes the start).

errorstringrequired

A stable code for the failure. This is the field to branch on. It does not change for a given failure.

messagestringrequired

A sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.

Request
curl -X POST "https://api.pr-701.adcrunch.dev/context/campaign-plans" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "brand_name": "acme",
  "currency": "EUR",
  "description": "The spring sale of Acme, on Meta, in France and Belgium.",
  "end_date": "2026-05-31",
  "measurement": "Revenue in the window, against the spring of 2025.",
  "name": "Spring Sale 2026",
  "rationale": "Meta carries the reach. One line keeps the budget in one place.",
  "slug": "spring-sale",
  "start_date": "2026-03-01",
  "total_budget": 5000
}'
Response
{
  "allocation": {
    "allocated": 0,
    "comparable": true,
    "unallocated": 5000,
    "unit": null
  },
  "brandId": "brd_6a9c33",
  "createdAt": 1768435200000,
  "createdBy": "usr_5d2b71",
  "currency": "EUR",
  "description": "The spring sale of Acme, on Meta, in France and Belgium.",
  "endDate": "2026-05-31",
  "id": "cpl_4e1a08",
  "lineItems": [],
  "measurement": "Revenue in the window, against the spring of 2025.",
  "name": "Spring Sale 2026",
  "rationale": "Meta carries the reach. One line keeps the budget in one place.",
  "revision": 1,
  "slug": "spring-sale",
  "startDate": "2026-03-01",
  "status": "draft",
  "totalBudget": 5000,
  "updatedAt": null
}