--- title: "Create a paused Meta app-install campaign" method: POST path: "/api/v1/tools/meta_create_app_install_campaign/execute" tags: ["Meta Ads"] --- # Create a paused Meta app-install campaign `POST /api/v1/tools/meta_create_app_install_campaign/execute` ## Request - Base URL: `https://adako.ai` - URL: `https://adako.ai/api/v1/tools/meta_create_app_install_campaign/execute` - Auth: HTTP bearer Builds a complete app-install campaign: campaign, one ad set pointed at the right operating system, the image upload, the creative and one ad. The campaign is created PAUSED and its ad set and ad ACTIVE inside it, so nothing spends until the campaign is turned on, and turning it on launches the ad. Say that the campaign is paused when you report the result, with the two links the result gives (Ads Manager and the campaign's page in Adako), and offer "enable all": one meta_resume_entity call on the campaign, listed in the result as go_live.enable_all, one approval. Use when: the user wants installs for an app that is already registered to their business — get the application_id and store URL from meta_list_promotable_apps first. Do not use for a website or a lead form; that is meta_create_image_campaign. One campaign promotes one app on one operating system, because the store URL decides the OS. Do not pass free text for locations or interests; use meta_search_targeting. Returns the new ids and reads the statuses back so you can confirm the campaign is paused (the ad set and ad read ACTIVE, held by the campaign). iOS install reporting is limited by Apple's tracking rules unless the app uses the Meta SDK with SKAdNetwork — say so when reporting iOS results rather than treating low numbers as poor performance. ## Headers - `Idempotency-Key` string ## Request body - object - `arguments` object, required - `ad_account_id` string: Meta ad account id such as act_1234567890. Omit it to use the primary account; if several accounts are active and none is primary the call fails and lists the valid ids. - `campaign_name` string, required: Name shown in Ads Manager. - `application_id` string, required: The app to promote, from meta_list_promotable_apps. - `object_store_url` string, uri, required: The store listing URL. apps.apple.com means an iOS campaign, play.google.com an Android one — the tool targets the matching operating system automatically. - `daily_budget` number: Daily budget as a decimal in the account currency (25 means 25 dollars, not 2500 cents). One of daily_budget or lifetime_budget is required. - `lifetime_budget` number: Total budget for the whole flight, decimal in the account currency. Requires end_time. - `budget_level` 'ad_set' | 'campaign': Which level holds the budget. "ad_set" (the default) gives this ad set its own budget, so every ad set is funded separately. "campaign" is Meta's campaign budget optimisation (Advantage campaign budget): the campaign holds one budget and Meta decides how much each ad set gets — ad sets added later must then carry no budget of their own. Only "campaign" can be edited with meta_update_campaign_budget. - `start_time` string: When delivery may start: YYYY-MM-DD (00:00 in the ad account's time zone) or an ISO timestamp with a UTC offset, e.g. 2026-10-01T09:00:00+02:00. Not in the past; today or omitted means as soon as the user activates it. - `end_time` string: When delivery must stop: YYYY-MM-DD (runs to 23:59:59 in the ad account's time zone) or an ISO timestamp with a UTC offset. Required with lifetime_budget. - `optimization_goal` string: Override what the ad set optimises for. Leave empty to use the objective default. LEAD_GENERATION (instant forms) is not supported; PAGE_LIKES promotes the Page. - `billing_event` string: What Meta charges for. Leave empty to use IMPRESSIONS. - `countries` string[]: ISO 3166-1 two-letter country codes from meta_search_targeting: GB, not UK; GR, not EL. - `region_keys` string[]: Region keys from meta_search_targeting (never region names). Checked with Meta first. - `city_keys` string[]: City keys from meta_search_targeting (never city names, postcodes or media markets). Each city is targeted with a 25 km radius. - `age_min` integer: Youngest age to target. Minimum 18. - `age_max` integer: Oldest age to target. 65 means 65 and over. - `genders` 'all' | 'men' | 'women': Restrict by gender. Defaults to all — narrow only when the user asks. - `interest_ids` string[]: Interest ids from meta_search_targeting or meta_browse_targeting. Never free text. - `behavior_ids` string[]: Behaviour ids from meta_search_targeting or meta_browse_targeting. Never free text. - `custom_audience_ids` string[]: Custom audience ids from meta_list_custom_audiences. - `excluded_custom_audience_ids` string[]: Custom audiences to exclude, e.g. existing customers. - `advantage_audience` boolean: Let Meta deliver beyond the listed interests. Defaults to off so the targeting the user asked for is the targeting they get. - `dsa_beneficiary` string: Who benefits from the ad. Required whenever the targeting reaches the EU or EEA — a country, or a region or city inside one, including territories such as Réunion. - `dsa_payor` string: Who pays for the ad. Required whenever the targeting reaches the EU or EEA — a country, or a region or city inside one. - `ad_set_name` string: Ad set name. Defaults to the campaign name plus a suffix. - `ad_name` string: Ad name. Defaults to the campaign name plus a suffix. - `facebook_page_id` string: Page the ad runs from, from meta_list_pages. - `instagram_account_id` string: Instagram account to run the ad from. - `image_url` string, uri, required: The image the app-install ad will show. Adako hosts no files: the platform downloads this URL itself, from its own servers and often hours later, so it must be a public link straight to the file — not a file on the computer, not a Drive, Dropbox or design-tool share page, not a link that expires or asks for a login. Call check_media first: it repairs the usual share links, checks the file against this platform, and says where to put a file that has no link yet. - `primary_text` string, required: Main ad copy. - `headline` string: Headline under the image. - `description` string: Description line. - `call_to_action` 'INSTALL_MOBILE_APP' | 'USE_APP' | 'PLAY_GAME' | 'SHOP_NOW' | 'BOOK_NOW' | 'DOWNLOAD': Button label. Defaults to INSTALL_MOBILE_APP. - `idempotency_key` string: Optional caller-supplied key; identical keys never execute twice. - `raw_data` boolean: Return compact JSON only (no markdown). Use when you will compute on the result. ## Response `200` The tool ran. A write returns proposal_id and approve_url while the change waits for approval. - SuccessEnvelope - `success` unknown, required - `tool` string, required - `data` object, required: Machine-readable result. - `markdown` string, required: The same result written for a person or a model. - `quota` Quota: Task usage for the current billing period. - `plan` string - `used` integer - `limit` integer - `period_end` string - `upgrade_url` string - `proposal_id` string: Present for writes. Nothing changes on the ad platform until it is approved. - `approve_url` string: Where a person approves the proposal. - `request_id` string, required ## Other responses - `400`: Invalid arguments, or the ad account could not be resolved. - `401`: Missing, invalid, revoked or expired API key. - `402`: Monthly task quota used up, or the plan does not include this tool. - `403`: The connected ad account lacks the access level this tool needs. - `404`: Unknown tool name. - `409`: Not connected, reconnect needed, confirmation required, a proposal already pending or no longer pending, an identical create that failed earlier today (proposal_failed_before), a create that duplicates an approved one (duplicate_create), the ad-account limit of the plan reached (account_limit), or an Idempotency-Key reused with different arguments. - `429`: Rate limited by Adako or by the ad platform. See Retry-After. - `500`: Unexpected error inside Adako. - `502`: The ad platform returned an error. --- [API](https://skmtc.dev/adako/apis/adako-rest-api.md) · [All operations](https://skmtc.dev/adako/apis/adako-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adako/apis/adako-rest-api/revisions/59ee60d48a56?raw)