Start a mutation

Starts a change on a live ad account and returns immediately.

The change does not happen during this request. The response carries a workflowId; poll GET /mutations/{id} with it to find out whether the change succeeded. A Mutation is durable, so the id stays valid across retries and restarts.

A request that is refused here starts nothing. A malformed body, an ad account that is not yours, and an ad account connected without write access are all rejected before any Mutation is created, so a failed call leaves no row in the history.

Every create action produces a paused object. This API cannot create anything that spends money on creation, and it cannot delete: meta_set_status with ARCHIVED is how an object is retired.

POST/mutations

Authorization

AuthorizationBearer token · headerrequired

Send Authorization: Bearer <credential>. Two credentials work.

An API key (acr_…) is what a server integration uses. Create one in the AdCrunch console under Settings → API keys — see https://docs.adcrunch.dev/account/api-keys. A key is bound to the organization that was active when you created it, and it keeps acting on that organization whatever you do later. It carries the permissions of the member who created it.

A session issued by the AdCrunch sign-in flow also works, which is how the console calls this service from the browser.

Either way the organization comes from the credential. There is no organization parameter.

Request body

requiredapplication/json

actionobjectrequired

What to do. The kind field selects the action, and each kind takes its own fields.

Show properties

One of:

object

idstringrequired

The Meta id of the object to change. It is the native id, not an AdCrunch id.

kindstringrequired

Allowed:meta_set_status

levelstringrequired

Which object the id refers to.

Allowed:campaignadsetad

statusstringrequired

The status to set. ACTIVE starts delivery and starts spend. PAUSED stops delivery and can be reversed. ARCHIVED retires the object, and on Meta it is close to one-way: you cannot make an archived object active again from this API. Archive is the only way to retire an object, because this API never deletes one.

Allowed:ACTIVEPAUSEDARCHIVED

object

dailyBudgetinteger

The amount to spend each day. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. Give a daily budget or a lifetime budget, not both.

max 9007199254740991

idstringrequired

The Meta id of the campaign or ad set to change. It is the native id, not an AdCrunch id.

kindstringrequired

Allowed:meta_update_budget

levelstringrequired

Which object the id refers to. An ad has no budget of its own.

Allowed:campaignadset

lifetimeBudgetinteger

The amount to spend across the whole schedule. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. A lifetime budget needs an end time on the ad set.

max 9007199254740991

object

dailyBudgetinteger

The amount the campaign spends each day, shared across its ad sets. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. Give one of the two budgets. Meta refuses a campaign with neither, and AdCrunch cannot yet create a campaign whose ad sets carry their own budgets.

max 9007199254740991

kindstringrequired

Allowed:meta_create_campaign

lifetimeBudgetinteger

The amount the campaign spends across its whole schedule, shared across its ad sets. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. Give one of the two budgets. Meta refuses a campaign with neither, and AdCrunch cannot yet create a campaign whose ad sets carry their own budgets.

max 9007199254740991

namestringrequired

The campaign name. It is visible in Meta Ads Manager.

min length 1

objectivestringrequired

The result the campaign optimizes for. It cannot be changed after the campaign is created, and it limits which optimization goals the ad sets below it can use.

Allowed:OUTCOME_AWARENESSOUTCOME_ENGAGEMENTOUTCOME_LEADSOUTCOME_SALESOUTCOME_TRAFFICOUTCOME_APP_PROMOTION

specialAdCategoriesstring[]required

Declare a regulated category when the campaign advertises one: EMPLOYMENT, HOUSING, CREDIT, ISSUES_ELECTIONS_POLITICS, ONLINE_GAMBLING_AND_GAMING, or FINANCIAL_PRODUCTS_SERVICES. Meta restricts targeting for each of them, and a wrong declaration breaks the advertiser policy agreement. Send an empty array or NONE when none applies. Do not guess: ask the advertiser.

default: []

object

ageMaxinteger

The oldest age to target, from 13 to 65. Omit it to target every age above the minimum. 65 and above is one group on Meta.

min 13 · max 65

ageMinintegerrequired

The youngest age to target, from 13 to 65. This field is required, and it is the one targeting field with no default. Many advertisers must not show ads to people under 18, and a default would spend their money on an audience they cannot legally address. State the age deliberately: send 18 to exclude minors.

min 13 · max 65

campaignIdstringrequired

The Meta id of the campaign this ad set belongs to. Create the campaign first and use the id it returns.

countriesstring[]required

The countries to target, as two-letter ISO 3166-1 alpha-2 codes, for example US or GB. Give at least one.

min items 1

customEventTypestring

The conversion the pixel reports, for example PURCHASE. Required with a conversion optimization goal, and it must be sent together with pixelId.

Allowed:PURCHASELEADCOMPLETE_REGISTRATIONADD_TO_CARTINITIATED_CHECKOUTADD_PAYMENT_INFOVIEW_CONTENTSEARCHSUBSCRIBESTART_TRIALCONTACTOTHER

dailyBudgetinteger

The amount this ad set spends each day. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. Omit both budgets when the campaign carries one, which is the usual case: a campaign created here always carries a budget, and it is shared across its ad sets.

max 9007199254740991

endTimestring

When delivery stops, as an ISO 8601 timestamp. Required with a lifetime budget.

gendersstringrequired

Which genders to target. The default targets everybody.

default: "all"

Allowed:allmenwomen

kindstringrequired

Allowed:meta_create_adset

lifetimeBudgetinteger

The amount this ad set spends across its whole schedule. The amount is in the minor unit of the ad account currency. 1000 is 10.00 in an account that uses dollars or euros. It needs an end time.

max 9007199254740991

namestringrequired

The ad set name. It is visible in Meta Ads Manager.

min length 1

optimizationGoalstringrequired

What Meta optimizes delivery for. The campaign objective limits which goals are valid. A conversion goal also needs pixelId and customEventType. The billing event follows from this goal, so there is no separate field for it.

Allowed:IMPRESSIONSREACHLINK_CLICKSLANDING_PAGE_VIEWSOFFSITE_CONVERSIONSPOST_ENGAGEMENTTHRUPLAYLEAD_GENERATIONVALUE

pixelIdstring

The Meta pixel that reports conversions. Required with a conversion optimization goal. AdCrunch can list the pixels this ad account can use.

startTimestring

When delivery starts, as an ISO 8601 timestamp. Omit it to start when the ad set becomes active. The ad set is created paused either way.

object

adsetIdstringrequired

The Meta id of the ad set this ad runs in. Create the ad set first and use the id it returns.

creativeIdstringrequired

The Meta id of the creative this ad shows. Create the creative first with meta_create_creative and use the id it returns. One creative can be used by more than one ad.

kindstringrequired

Allowed:meta_create_ad

namestringrequired

The ad name. It is visible in Meta Ads Manager.

min length 1

object

assetIdstringrequired

The AdCrunch Asset to build the creative from, as the ast_ id that Asset registration returned. The Asset must already be registered to this advertiser. Do not send a Meta image hash or video id. Whether the creative becomes an image or a video follows from the Asset.

matches ^ast_[\s\S]{0,}$

callToActionstringrequired

The label on the button, for example SHOP_NOW.

Allowed:LEARN_MORESHOP_NOWSIGN_UPBOOK_TRAVELDOWNLOADGET_OFFERGET_QUOTECONTACT_USSUBSCRIBEAPPLY_NOWNO_BUTTON

descriptionstring

The text below the headline. Meta can truncate it.

headlinestringrequired

The short bold line next to the button.

min length 1

kindstringrequired

Allowed:meta_create_creative

linkstring<uri>required

The page the ad opens when somebody clicks it.

messagestringrequired

The main body text, shown above the media.

min length 1

namestringrequired

The creative name. It is visible in Meta Ads Manager, and it is not shown to a person who sees the ad.

min length 1

pageIdstringrequired

The Facebook Page the ad is published from. AdCrunch can list the Pages this ad account can publish from.

advertiserIdstringrequired

The ad account to act on, as an AdCrunch acc_ id. It must belong to your organization and be connected with write access.

matches ^(acc_)[\s\S]{0,}$

Responses

200

The Mutation started. Poll it for the outcome.

workflowIdstringrequired

The id of the Mutation. Poll GET /mutations/{id} with it to find out whether the change succeeded.

400

The body does not match the schema. error is invalid_request. Nothing was started.

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 credential, or one that does not resolve. Send an API key or a session. 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 mutation:write, or the ad account is connected without write access. In the second case error is missing_write_access and message says how to fix it. Nothing was started.

Any of:

object

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.

object

errorstringrequired

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

Allowed:missing_write_access

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

The ad account does not exist, or it belongs to another organization. Both answer the same way on purpose, so a caller cannot learn which. error is not_found. Nothing was started.

errorstringrequired

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

Allowed:not_found

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.adcrunch.dev/mutations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": {
    "id": "string",
    "kind": "meta_set_status",
    "level": "campaign",
    "status": "ACTIVE"
  },
  "advertiserId": "string"
}'

const response = await fetch("https://api.adcrunch.dev/mutations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"action\": {\n    \"id\": \"string\",\n    \"kind\": \"meta_set_status\",\n    \"level\": \"campaign\",\n    \"status\": \"ACTIVE\"\n  },\n  \"advertiserId\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://api.adcrunch.dev/mutations",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"action\": {\n    \"id\": \"string\",\n    \"kind\": \"meta_set_status\",\n    \"level\": \"campaign\",\n    \"status\": \"ACTIVE\"\n  },\n  \"advertiserId\": \"string\"\n}",
)

Response

{
  "workflowId": "string"
}

{
  "error": "invalid_request",
  "message": "string"
}

{
  "error": "unauthorized",
  "message": "string"
}

{
  "error": "forbidden",
  "message": "string"
}

{
  "error": "not_found",
  "message": "string"
}