Skip to main content
POST
Boost an existing Facebook post to create an ad. This endpoint allows you to convert your organic posts into paid advertisements with custom targeting, budget, and scheduling parameters.
  • Budget and bid amounts are in the ad account’s currency. Use up to two decimal places, or whole numbers for the currencies Meta takes in whole units: CLP, COP, CRC, HUF, IDR, ISK, JPY, KRW, PYG, TWD and VND.
  • The ad must run for at least 30 hours to address the Facebook requirement.
  • You can use the interests endpoint to find interest IDs for targeting.
  • Facebook may take up to 24 hours to review and approve boosted posts.
  • If using fbPostId directly (instead of Ayrshare postId), ensure it’s a valid Facebook post ID.
  • If a boost fails after Facebook has created its campaign (at the creative, ad set or ad step), we try to delete that campaign. If the delete also fails, the empty campaign stays in your ad account. You can find and delete it in Ads Manager.
Meta refuses the ad until both of these are in place:
  • A payment method on the ad account. Add one in Meta’s Billing & payments and attach it to the ad account you send as accountId. A payment method saved only on the business portfolio is not enough.
  • Personalized ads turned on (EU, EEA and Switzerland). If the owner of the Facebook or Instagram account linked to your Facebook Page chose to see less-personalized ads, or subscribed to use Meta without ads, Meta does not let that account or the Page run ads. The owner can switch back to personalized ads, or cancel the subscription, in Accounts Center → Ad preferences → Ad experience. Learn more.

​
Ad Goals

Each ad must have a goal. The goal determines how the ad will be optimized for display.
  • engagement: This goal seeks to increase engagement while ensuring that the ad reaches the maximum number of unique users. It balances visibility with engagement, showing the ad to as many different people as possible who may interact with it.
  • interactions: Designed to boost interactions, such as likes, comments, and shares, on the ad. Facebook prioritizes showing the ad to users most likely to engage with it.
  • awareness_views: Focuses on increasing brand awareness by maximizing the number of times the ad is displayed. It prioritizes showing the ad as many times as possible within the budget, regardless of unique reach.
  • awareness_audience: Aims to enhance brand awareness by maximizing the number of unique people who see the ad. It ensures that the ad reaches as many different users as possible and maximizes the unique audience size rather than showing it multiple times to the same audience.
  • traffic: Sends people off Facebook to a destination you choose, such as your website, a landing page, or a job posting. Facebook optimizes for link clicks rather than on-platform engagement. This is the only goal that supports a callToAction button that opens a link.
Learn more about integrating the Facebook Marketing API with Ayrshare in our Facebook Marketing API Integration Guide.

​
Header Parameters

​
Body Parameters

​
string
A unique, non-empty key for this boost request. Retry the same payload with the same key to avoid creating a duplicate ad. Reusing the key with a different payload, or for an Instagram boost, returns HTTP 409. On any other platform, the same key starts a separate boost. A request still in progress also returns 409; an unavailable reservation returns 503 without creating an ad.
​
string
required
The ID of the Facebook ad account to boost the post on. The account ID can be retrieved from the ad accounts endpoint.
​
string
required
Name for your ad (appears in Facebook Ad Manager) with the format {adName} - {postId or fbPostId} - {current date}. If you send an idempotencyKey, the name also ends in - {request reference}, a short reference that stays the same for that key.
​
number
required
Maximum bid amount in the ad account’s currency, as a positive amount.
​
number
required
Daily budget in the ad account’s currency, as a positive amount. Meta may enforce minimums for your account and goal.
​
string
required
The Facebook social post ID of the post to boost, which allows you to create an ad from a post created directly on Facebook. This is the ID of the post on Facebook, not Ayrshare. Required if postId is not set.
​
string
default:"engagement"
required
The goal of the ad. Values: engagement, interactions, awareness_views, awareness_audience, and traffic. See ad goals details above for more information.
​
object
Target ad locations with an object of arrays: countries, regions, cities. An object that names no country, region or city, such as {}, is refused with code 101; leave locations out to target the US.
​
string
required
The Ayrshare post ID of the post to boost. Required if fbPostId is not set.
​
string
default:"active"
required
The status of the ad. Values: active and paused.You can later change the status of the ad using the update ad endpoint.
​
boolean
default:false
Controls Meta’s campaign-level ad set budget sharing. Meta now requires this wire field on every campaign created without a campaign-level budget, so Ayrshare always sends it — defaulting to false for backward compatibility.Set to true to let Meta share up to ~20% of an ad set’s budget across other ad sets in the same campaign to optimize overall performance. See Meta’s ad campaign group reference for details.
​
object
Add a call-to-action button, such as Apply Now or Shop Now, to the boosted post. The button opens the URL you supply in link, or, with destination, a Messenger, WhatsApp or Instagram Direct chat instead (see Open a Conversation Instead of a Link).
A callToAction that opens a link is only supported with the traffic ad goal. A button with destination uses engagement or interactions instead, as described in Open a Conversation Instead of a Link. Sending a link button with engagement, interactions, awareness_views, or awareness_audience returns a 400 with code: 101 naming the compatible goals. Previously the value was accepted on any goal and then silently ignored, producing an ad with no button.
callToAction.link supplies the destination URL. When Meta renders the call to action as a button on the existing post, urlTags append to that button link. goal: "traffic" without a callToAction is allowed and creates a traffic ad with no button.The callToAction you send is echoed back in the boost response with type upper-cased — see the Post Boosted with a Call to Action example — and is also returned on the ad afterwards by Get Boosted Ads.To open a Messenger, WhatsApp or Instagram Direct chat instead of a link, see Open a Conversation Instead of a Link.
​
object
Track the ad using a Facebook Pixel.
​
array
Add UTM tags to the ad URL.
For example if the linking URL is https://www.mysite.com/my-post and the URL tags added are:utm_source=ayrshare, utm_medium=social, and utm_campaign=ayrshare-social.The ad URL will be: https://www.mysite.com/my-post?utm_source=ayrshare&utm_medium=social&utm_campaign=ayrshare-social.
​
array
Meta requires advertisers in special ad categories to must self-identify their campaign category.If your business is in one of these categories, you must select the appropriate category when boosting your post.The following values are supported:
  • housing: Ads that promote or directly link to a housing opportunity or related service, including but not limited to listings for the sale or rental of a home or apartment, homeowners insurance, mortgage insurance, mortgage loans, housing repairs and home equity or appraisal services.
  • financial_product_services: Ads that promote or directly link to a financial products and services offer, including credit. financial_products_services is accepted as an equivalent spelling, and credit is accepted as Meta’s former name for this category — all three reach Meta as the same category, so send whichever you already have.
  • employment: Ads that promote or directly link to an employment opportunity, including but not limited to part- or full-time jobs, internships or professional certification programs. Related ads that fall within this category include promotions for job boards or fairs, aggregation services or ads detailing perks a company may provide, regardless of a specific job offer.
  • none: The default. Declares that the campaign is not in any special ad category. Sending it explicitly is equivalent to omitting specialAdCategories altogether, and is accepted so a caller that always sends the field can say “no category” without special-casing it.
  • issues_elections_politics: Ads made by, on behalf of, or about a candidate for public office, a political figure, a political party or advocating for the outcome of an election to public office. This also includes ads about any election, referendum or ballot initiative, including “Go out and vote” election campaigns. Ads regulated as political advertising or about social issues in any place where the ad is being placed. If selecting issues, elections, or politics, you must select the country in which you want to run these ads. You are required to be authorized to run ads about social issues, elections, or politics in the specified country.
Values are case-insensitive. An unrecognized value is rejected with a 400 and code: 101 listing the accepted values. Previously an unrecognized value was silently dropped and the campaign was created as uncategorized, so a typo left a regulated ad running with no category declared.The accepted-values list in that error message is written in Meta’s upper-case form and also names the alternative spellings above, so it reads NONE, HOUSING, FINANCIAL_PRODUCTS_SERVICES, EMPLOYMENT, ISSUES_ELECTIONS_POLITICS, FINANCIAL_PRODUCT_SERVICES, CREDIT. Those are the same five categories listed here — FINANCIAL_PRODUCT_SERVICES and CREDIT are the equivalents of financial_product_services, not extra categories. The identical message is returned by the interests endpoint.Repeating a category, or sending two spellings of the same one such as ["credit", "financial_product_services"], is accepted and collapses to a single category before it reaches Meta. An empty value is rejected with a 400 and code: 101.To find interest IDs that Meta allows for one of these categories, pass the same value to the interests endpoint.Meta also needs the countries a special category ad runs in. Ayrshare takes them from locations: the countries you list, plus the country of each region and city. So a housing boost that targets a city in the UK is set up for the UK, with nothing extra in your request. Without locations the ad runs in the US, and the campaign is set up for the US.Meta also sets a minimum radius around each city for these categories. A UK city with a 17 kilometer radius was rejected with #2909039, which asks for at least 25 kilometers (15 miles), so use 25 kilometers or more.
Meta requires advertisers who have self-identified their campaign category. Meta uses human reviewers and machine-learning to identify these kinds of ads. If you send us an incorrect specialAdCategory, there is a risk your ads will be paused until the campaign is adjusted.
​
string
End date and time in ISO 8601 format (must be at least 30 hours after start), for example 2025-03-01T00:00:00Z.If not set, the ad will run indefinitely and have end date of ongoing.
​
object
Exclude locations using an object with arrays of countries, regions, and cities.
​
string
default:"all"
The gender of the audience. Values: all, male, female.
​
array
The target interests of the ad as an array of Facebook interest ids.
​
number
default:65
Maximum age for targeting the ad (default: 65).
​
number
default:18
Minimum age for targeting the ad (default: 18).
​
string
Start date and time in ISO 8601 format, for example 2025-03-01T00:00:00Z.If not set, the ad will start immediately.
​
string
The beneficiary of the ad for Digital Services Act (DSA) compliance for EU countries. Must be set together with dsaPayor if either is provided. Please refer to our DSA guide for more information.
​
string
The payor of the ad for Digital Services Act (DSA) compliance for EU countries. Must be set together with dsaBeneficiary if either is provided.

​
Lifetime Budgets

The body above sets a daily budget on the ad set. For a lifetime budget, send the nested form of the boost body instead. In the nested form, accountId, postId (or socialPostId in place of fbPostId), goal, status and callToAction stay at the top level. Three objects replace the flat budget, date and targeting fields: budget, schedule (start, end) and targeting (locations, excludedLocations, ageMin, ageMax, genders, interests). The remaining fields, adName, bidAmount, specialAdCategories, adSetBudgetSharingEnabled, link, tracking, urlTags, dsaBeneficiary and dsaPayor, move under platformOptions.facebook.
  • budget.type: daily (the default) or lifetime. A lifetime budget is spent between the start and end dates, so it needs schedule.end. Without one the request is rejected with a 400 and code: 101. Meta’s ad set budget sharing works with daily budgets only, so a lifetime budget with adSetBudgetSharingEnabled: true is also rejected with code: 101.
The response adds budgetType: "lifetime" for a lifetime budget. A daily budget does not return budgetType, so treat a missing field as daily.

​
Campaign Budgets

To hold the budget on the campaign instead of the ad set, send budget.level: "campaign" in the nested form shown above. The ad set then has no budget of its own. It works with daily and lifetime budgets.
  • budget.level: adSet (the default) or campaign. A campaign budget cannot be combined with adSetBudgetSharingEnabled. Sending both is rejected with a 400 and code: 101.
  • The response adds budgetLevel: "campaign" for a campaign budget. An ad set budget does not return budgetLevel, so treat a missing field as adSet.
  • In History, budgetDaily shows the campaign’s daily budget for an ad with a daily campaign budget. If several ads share one campaign budget, each shows the whole campaign budget, not its share. History does not show lifetime budgets, on the campaign or the ad set. Once a lifetime campaign budget is spent, every ad in that campaign shows deliveryStatus: "COMPLETED" after the next nightly update, including an ad that is scheduled or in review. A rejected ad stays REJECTED.

​
Boost into an Existing Campaign or Ad Set

By default every boost creates its own campaign, ad set and ad. To add the boost to a campaign or ad set you already run in Meta, send the nested form with attachTo.
  • attachTo.campaignId: the boost creates a new ad set and ad inside that campaign. Send budget, targeting and bidAmount as usual: they apply to the new ad set.
  • attachTo.adSetId: the boost creates only the ad, inside that ad set. Also send attachTo.campaignId, the campaign the ad set belongs to. Leave out budget, targeting and platformOptions.facebook.bidAmount: the ad set keeps its own. Sending any of them returns a 400 with code: 101.
  • The campaign or ad set must be in the ad account named by accountId, and must not belong to another user’s boosts. Otherwise the request returns a 400. A Facebook boost also cannot attach to a campaign an Instagram boost created, and the reverse.
  • attachTo cannot be combined with budget.level: "campaign", specialAdCategories or adSetBudgetSharingEnabled, which are set on a new campaign. Sending them returns code: 101.
  • Pausing or activating the boost changes only what the boost created: the ad, and the ad set when the boost created it. The campaign or ad set you named in attachTo keeps its own status. The ad runs only while the campaign and ad set above it are active. This also applies when Ayrshare pauses your ads, for example when a profile is deleted.
  • If the boost fails, the campaign or ad set named in attachTo is never deleted.
  • If the ad set you attach to sits in a campaign that holds the budget (a campaign budget), History reports the boost like any ad with a campaign budget: budgetDaily shows the whole campaign budget, not the boost’s share, and once a lifetime campaign budget is spent, every ad Ayrshare tracks in that campaign shows deliveryStatus: "COMPLETED" after the next nightly update, including an ad that is scheduled or in review. A rejected ad stays REJECTED.

​
Open a Conversation Instead of a Link

A boost’s button can open a chat with your business instead of a web page. Send the nested form with callToAction.destination, and leave out callToAction.link.
  • Use the engagement or interactions ad goal. The ad is then optimized for conversations: Meta shows it to people likely to start a chat. Other goals return a 400 with code: 101.
  • callToAction.type must match the destination, as in the table. Any casing is accepted.
  • callToAction.link and callToAction.linkTitle cannot be sent with destination, because the button opens a chat, not a page. Without destination, link is still required.
  • People message the account linked to your profile. For whatsapp, its Facebook Page must have a WhatsApp Business number connected in Meta.
  • destination cannot be combined with attachTo.adSetId: the existing ad set keeps the destination it already has. With attachTo.campaignId, the campaign must have Meta’s OUTCOME_ENGAGEMENT objective; otherwise the request returns a 400 with code: 101.
  • The response, and Get Boosted Ads, return callToAction with its destination.