Google Search Campaigns

Create a Google Ads Search campaign with its budget, keywords, ad text and location targeting in one request

POST /ads/google/campaigns

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}'

200: Campaign Created

{
  "status": "success",
  "platform": "google",
  "campaignId": "21534567890",
  "adGroupId": "16812345678",
  "adId": "71234567890",
  "campaignStatus": "paused"
}

Create a Google Ads Search campaign in one request. Ayrshare builds the budget, the campaign, one ad group, your keywords, one responsive search ad, and the location targeting together. If Google refuses any part, nothing is created.

The request uses the shared Ad Campaigns shape. This page covers what is specific to Google.

• Google ads are turned on per account. Contact us to enable them.
• Link Google Ads from the Social Accounts page first. accountId is the 10-digit Google Ads customer id, with or without hyphens (123-456-7890).
• The Google user you link must have direct access to the ad account. Accounts you reach only through a manager account are not listed and cannot be used yet: add that user to the ad account itself. Manager accounts are not listed either: they cannot hold campaigns.
• New campaigns start paused unless you send status: "active".
• The budget is per day, in the ad account’s currency. Do not send budget.currency: it answers code: 101.
• Spend in another currency is converted to USD for billing at that day’s exchange rate from Open Exchange Rates. An account in a currency that cannot be converted answers code: 101 before anything is created.
• Ads show on Google Search only, not on search partners or the Display Network.

Conversion tracking. maximizeConversions only works when conversion tracking is set up in your Google Ads account. Ayrshare does not set it up for you. Without it, use maximizeClicks or manualCpc.

​

Header Parameters

Idempotency-Key · string · required

A new unique value, such as a UUID, for each new campaign. Repeating a request with the same key returns the first response and creates nothing new. When a create fails before Ayrshare sends the campaign to Google, the key is freed, so you can fix the request and retry with the same key. That covers a value Ayrshare refuses (such as an unsupported bidding strategy), an account in a currency that cannot be converted to USD, and any failure of the account check Ayrshare makes first, including Google refusing it. A create that fails once the campaign was sent to Google keeps its answer: retry it with a new key.

​

Body Parameters

The shared fields work as described on Ad Campaigns. On Google:

type · string · required

search.

bidding.strategy · string · required

maximizeClicks, manualCpc, or maximizeConversions. Any other answers code: 101.

euPoliticalAdvertising · boolean · required

Google requires this declaration on every campaign. While any campaign in an account is undeclared, Google rejects every change to that account’s campaigns.

schedule · object

Google schedules whole days in the ad account’s time zone. start begins at 00:00:00 on its day and end stops at 23:59:59 on its day; a time you send only picks the day. start can be today but not an earlier day. For a one-day campaign, send the same date for start and end. An end on an earlier day than start answers code: 101.

targeting · object

Google matches Search ads to people by the language of your ad text, so there is no language setting. Sending targeting.languages answers code: 101.

Show properties

locations · string[]

Google location ids, for example 2840 for the United States. Find ids in Google’s geo targets list. Leave it out to target every location.

platformOptions.google · object · required

Show properties

finalUrl · string · required

The http or https page the ad opens.

headlines · string[] · required

3 to 15 headlines, each up to 30 characters.

descriptions · string[] · required

2 to 4 descriptions, each up to 90 characters.

path1 · string

First part of the display path shown after the domain, up to 15 characters.

path2 · string

Second part of the display path, up to 15 characters. Needs path1.

keywords · object[] · required

At least one keyword: { "text": string, "matchType": "exact" | "phrase" | "broad" }. text is up to 80 characters and 10 words.

maxCpc · number

The most to pay per click, in the account currency. Required with manualCpc. With maximizeClicks it caps each bid. Not accepted with maximizeConversions.

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Fall sale",
  "type": "search",
  "budget": { "amount": 25, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "targeting": { "locations": ["2840"] },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/fall-sale",
      "headlines": ["Fall sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "path1": "shoes",
      "keywords": [
        { "text": "running shoes", "matchType": "phrase" },
        { "text": "trail running shoes", "matchType": "exact" }
      ]
    }
  }
}'

200: Campaign Created

{
  "status": "success",
  "platform": "google",
  "campaignId": "21534567890",
  "adGroupId": "16812345678",
  "adId": "71234567890",
  "campaignStatus": "paused"
}

​

Errors

Code	When
101	A field is missing or invalid. details names it.
205	Google refused the request: for example, the account already has a campaign with this name, or the ad text breaks Google’s advertising policies. details says what to change.
400	The Google user you linked cannot access this ad account, Google Ads access was revoked, the campaign is not yours, or a change targets a campaign removed in Google Ads.
370	Google could not complete the request, or Google has not yet approved Ayrshare’s access. details includes Google’s request id when there is one. A create that answers 370 because Google’s answer was lost may still have created the campaign. Google refuses a second campaign with the same name in one account, so retrying with the same name answers 205 instead of creating a duplicate.