Google Ads Connector Reference¶ Connection configuration¶ The connection is used to establish a connection to the Google Ads. The Google Ads API uses OAuth2 authentication with Tokens. For more information on authentication, go to Authorizing Your App with Google Ads. initThe init operation initializes the connection to Google Ads API. Parameter name Description Required name Unique name to identify the connection. Yes base The service root URL. The default value is https://googleads.googleapis.com. Yes apiVersion The API version to access the endpoint. The default value is v18. No clientId Client ID of the registered application. Yes clientSecret Client secret of the registered application. Yes refreshToken The refresh token that can be used to obtain a new access token. Yes developerToken The developer token for the Google Ads connection. Yes loginCustomerId The ID of the manager account. Required when using a manager account to access a customer account. No tokenEndpoint The HTTP endpoint that can be used to obtain an access token. The default value is https://www.googleapis.com/oauth2/v3/token. Yes Sample configuration <googleAds.init> <connectionType>googleAds</connectionType> <name>GOOGLE_ADS_CONN</name> <base>https://googleads.googleapis.com</base> <apiVersion>v18</apiVersion> <clientId>REPLACE_WITH_CLIENT_ID</clientId> <clientSecret>REPLACE_WITH_CLIENT_SECRET</clientSecret> <refreshToken>REPLACE_WITH_REFRESH_TOKEN</refreshToken> <developerToken>REPLACE_WITH_DEVELOPER_TOKEN</developerToken> <loginCustomerId>REPLACE_WITH_MANAGER_ID</loginCustomerId> <tokenEndpoint>https://www.googleapis.com/oauth2/v3/token</tokenEndpoint> </googleAds.init> The following operations allow you to work with the Google Ads API. Click an operation name to see parameter details and samples on how to use it. createCustomerClientThe createCustomerClient operation creates a new client under the provided manager. The new client customer is returned. Parameter name Description Required customerId The ID of the manager under whom the client customer is being created. Type: string Yes customerClient The new client customer to create. The resource name on this customer will be ignored. Type: Customer object Yes accessRole The proposed role of the user on the created client customer. Accessible only to customers on the allow-list. Type: AccessRole enum No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No emailAddress Email address of the user who should be invited on the created client customer. Accessible only to customers on the allow-list. Type: string No Sample configuration <googleAds.createCustomerClient configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.account_id)}</customerId> <customerClient>{json-eval($.client_data)}</customerClient> </googleAds.createCustomerClient> Sample request { "account_id": "123123123", "client_data": { "status": "ENABLED", "descriptiveName": "Client Customer 1", "currencyCode": "USD", "timeZone": "GMT" } } customersMutateThe customersMutate operation updates a customer. Operation statuses are returned. Parameter name Description Required customerId The ID of the customer being modified. Type: string Yes operation The operation to perform on the customer Type: CustomerOperation object Yes validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.customersMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operation>{json-eval($.operation)}</operation> <validateOnly>{json-eval($.validate_only)}</validateOnly> <responseContentType>{json-eval($.response_type)}</responseContentType> </googleAds.customersMutate> Sample request { "customer_id": "456456456", "validate_only": false, "response_type": "MUTABLE_RESOURCE", "operation": { "update": { "resourceName": "customers/456456456", "descriptiveName": "My Client 1", "hasPartnersBadge": true }, "updateMask": "descriptiveName,hasPartnersBadge" } } campaignBudgetsThe campaignBudgets operation creates, updates, or removes campaign budgets. Operation statuses are returned. Parameter name Description Required customerId The ID of the customer whose campaign budgets are being modified. Type: string Yes operations The list of operations to perform on individual campaign budgets. Type: CampaignBudgetOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. Type: boolean No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.campaignBudgets configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> </googleAds.campaignBudgets> Sample request CreateUpdateRemove { "customer_id": "456456456", "operations": [ { "create": { "name": "My Campaign Budget #1", "amountMicros": 500000 } }, { "create": { "name": "My Campaign Budget #2", "amountMicros": 400000 } } ] } { "customer_id": "456456456", "operations": [ { "update": { "resourceName": "customers/456456456/campaignBudgets/789789789", "amountMicros": "300000" }, "updateMask": "amountMicros" } ] } { "customer_id": "456456456", "operations": [ { "remove": "customers/456456456/campaignBudgets/789789789" } ] } campaignsMutateThe campaignsMutate operation creates, updates, or removes campaigns. Operation statuses are returned. Parameter name Description Required customerId The ID of the customer whose campaigns are being modified. Type: string Yes operations The list of operations to perform on individual campaigns. Type: CampaignOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. Type: boolean No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.campaignsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> <validateOnly>{json-eval($.validateOnly)}</validateOnly> </googleAds.campaignsMutate> Sample request CreateUpdateRemove { "customer_id": "1231231223", "validateOnly": false, "operations": [ { "create": { "status": "PAUSED", "advertisingChannelType": "SEARCH", "geoTargetTypeSetting": { "positiveGeoTargetType": "PRESENCE_OR_INTEREST", "negativeGeoTargetType": "PRESENCE" }, "name": "My Search campaign #1", "campaignBudget": "customers/1231231223/campaignBudgets/789789789", "targetSpend": {} } } ] } { "customer_id": "1231231223", "validateOnly": false, "operations": [ { "updateMask": "name", "update": { "resourceName": "customers/1231231223/campaigns/789789789", "name": "My Search campaign #2" } } ] } { "customer_id": "1231231223", "validateOnly": false, "operations": [ { "remove": "customers/1231231223/campaigns/789789789" } ] } adGroupsMutateThe adGroupsMutate operation creates, updates, or removes ad groups. Operation statuses are returned. Parameter name Description Required customerId The ID of the customer whose ad groups are being modified. Type: string Yes operations The list of operations to perform on individual ad groups. Type: AdGroupOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. Type: boolean No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.adGroupsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> </googleAds.adGroupsMutate> Sample request CreateUpdateRemove { "customer_id": "123123123", "operations": [ { "create": { "status": "UNSPECIFIED", "type": "SEARCH_STANDARD", "name": "Test Ad group 1", "campaign": "customers/123123123/campaigns/456456456" } } ] } { "customer_id": "123123123", "operations": [ { "updateMask": "name,cpmBidMicros", "update": { "resourceName": "customers/123123123/adGroups/456456456", "name": "My Ad group 1", "cpmBidMicros": "10000" } } ] } { "customer_id": "123123123", "operations": [ { "remove": "customers/123123123/adGroups/456456456" } ] } adGroupAdsMutateThe adGroupAdsMutate operation creates, updates, or removes ads. Operation statuses are returned. Parameter name Description Required customerId The ID of the customer whose ads are being modified. Type: string Yes operations The list of operations to perform on individual ads. Type: AdGroupAdOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. Type: boolean No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.adGroupAdsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> </googleAds.adGroupAdsMutate> Sample request CreateUpdateRemove { "customer_id": "123123123", "operations": [ { "create": { "adGroup": "customers/123123123/adGroups/456456456", "status": "PAUSED", "ad": { "name": "Test Ad 1", "responsiveSearchAd": { "headlines": [ { "pinned_field": "HEADLINE_1", "text": "An example headline" }, { "text": "Another example headline" }, { "text": "Yet another headline" } ], "descriptions": [ { "text": "An example description" }, { "text": "Another example description" } ], "path1": "integration" }, "finalUrls": [ "https://www.wso2.com" ] } } } ] } { "customer_id": "123123123", "operations": [ { "updateMask": "status", "update": { "status": "ENABLED", "resourceName": "customers/123123123/adGroupAds/456456456~789789789" } } ] } { "customer_id": "123123123", "operations": [ { "remove": "customers/123123123/adGroupAds/456456456~789789789" } ] } adsMutateThe adsMutate operation updates ads. Operation statuses are returned. Updating ads is not supported for TextAd, ExpandedDynamicSearchAd, GmailAd and ImageAd. Parameter name Description Required customerId The ID of the customer whose ads are being modified. Type: string Yes operations The list of operations to perform on individual ads. Type: AdOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. Type: boolean No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. Type: boolean No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. Type: ResponseContentType enum No Sample configuration <googleAds.adsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> </googleAds.adsMutate> Sample request { "customer_id": "123123123", "operations": [ { "updateMask": "finalUrls", "update": { "resourceName": "customers/123123123/ads/789789789", "finalUrls": [ "https://www.github.com" ] } } ] } searchThe search operation returns all rows that match the search query. Parameter name Description Required customerId The ID of the customer being queried. Type: string Yes query The query string. Type: string Yes pageToken Token of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: string No pageSize Number of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integer No validateOnly If true, the request is validated but not executed. Type: boolean No returnTotalResultsCount If true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: boolean No summaryRowSetting Determines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: SummaryRowSetting enum No Sample configuration <googleAds.search configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <query>{json-eval($.query)}</query> </googleAds.search> Sample request { "customer_id": "123123123", "query": "SELECT customer_client.client_customer FROM customer_client" } campaignCriteriaMutateThe campaignCriteriaMutate operation creates, updates, or removes criteria. Parameter Name Description Required customerId The ID of the customer whose criteria are being modified. Yes operations The list of operations to perform on individual criteria. Type: CampaignCriterionOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. No Sample configuration <googleAds.campaignCriteriaMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <query>{json-eval($.operations)}</query> </googleAds.campaignCriteriaMutate> Sample request { "customer_id": "123123123", "operations": [ { "create": { "campaign": "customers/123123123/campaigns/789789789", "criterion": { "customAudience": "customers/123123123/customAudiences/781704020" } } } ] } customAudiencesMutateThe customAudiencesMutate operation creates or updates custom audiences. Parameter Name Description Required customerId The ID of the customer whose custom audiences are being modified. Yes operations The list of operations to perform on individual custom audiences. Type: CustomAudienceOperation object Yes validateOnly If true, the request is validated but not executed. Only errors are returned, not results. No Sample configuration <googleAds.customAudiencesMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <query>{json-eval($.operations)}</query> </googleAds.customAudiencesMutate> Sample request { "customer_id": "123123123", "operations": [ { "create": { "status": "ENABLED", "name": "Tech Enthusiasts Custom Audience", "type": "AUTO", "description": "Custom audience targeting users interested in technology-related content.", "members": [ { "memberType": "KEYWORD", "keyword": "Artificial Intelligence" }, { "memberType": "URL", "url": "https://example.com/tech-articles" }, { "memberType": "APP", "app": "com.example.techapp" } ] } } ] } audiencesMutateThe audiencesMutate operation creates audiences. Parameter Name Description Required customerId The ID of the customer whose audiences are being modified. Yes operations The list of operations to perform on individual audiences. Type: AudienceOperation object Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. No responseContentType The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation. No Sample configuration <googleAds.audiencesMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <query>{json-eval($.operations)}</query> </googleAds.audiencesMutate> Sample request { "customer_id": "123123123", "operations": [ { "create": { "name": "Audience Group", "description": "Test audience group", "dimensions": [ { "age": { "ageRanges": [ { "minAge": 18, "maxAge": 24 }, { "minAge": 25, "maxAge": 34 } ] } } ] } } ] } userListsMutateThe userListsMutate operation creates or updates user lists. Operation statuses are returned. Parameter Name Description Required customerId Required. The ID of the customer whose user lists are being modified. Yes operations Required. The list of operations to perform on individual user lists. Type: UserListOperation object. Yes partialFailure If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. The default value is false. No validateOnly If true, the request is validated but not executed. Only errors are returned, not results. No Sample configuration <googleAds.userListsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <query>{json-eval($.operations)}</query> </googleAds.userListsMutate> Sample request { "customer_id": "123123123", "operations": [ { "create": { "name": "My Customer Match List", "description": "List created via MI", "membershipLifeSpan": 30, "crmBasedUserList": { "uploadKeyType": "CONTACT_INFO", "": "FIRST_PARTY" } } } ] } userDataMutateThe userDataMutate operation adds or removes users from user lists. Parameter Name Description Required customerId Required. The ID of the customer whose user lists are being modified. Yes userListId Required. The ID of the user list whose users are being modified. Yes inputStructure Required. Defines the data source for the user list. Options: GOOGLE_API_COMPATIBLE — Enables the Google Ads API-friendly input body as input. JSON_ARRAY — Activates attributes for uploading user data as a JSON array. Yes operations The list of operations to perform on individual user lists. Type: UserListOperation object. Required if inputStructure is GOOGLE_API_COMPATIBLE jsonArrayContent A JSON array containing user data to upload. Required if inputStructure is JSON_ARRAY operationType Defines the operation to be performed on the user list. Options: create or remove. Required if inputStructure is JSON_ARRAY userIdentifierSource Specifies the source of the user identifiers. Options: UNKNOWN, UNSPECIFIED, FIRST_PARTY or THIRD_PARTY. No transactionAttributes Allows the inclusion of transaction attributes for user data upload. No userAttributes Includes additional user attributes for the uploaded data. No consent Indicates consent for uploading user data. No Sample configuration for "GOOGLE_API_COMPATIBLE" <googleAds.userListsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <operations>{json-eval($.operations)}</operations> <userListId>{json-eval($.userListId)}</userListId> </googleAds.userListsMutate> Sample request for "GOOGLE_API_COMPATIBLE" { "customer_id": "123123123", "operations": [ { "create": { "userIdentifiers": [ { "hashedEmail": "2c41b9d011bc28e71842637075e2a67cf4e73010172f4a18985494467d73a6d6" }, { "hashedPhoneNumber": "00b340221ad566a1400936daadce44a7c61b5b04505fc66d3d55d96bde434bc1" } ] } } ], "userListId": "1232132321" } Sample configuration for "JSON_ARRAY" <googleAds.userListsMutate configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <inputStructure>JSON_ARRAY</inputStructure> <jsonArrayContent>{json-eval($.jsonArrayContent)}</jsonArrayContent> <operationType>create</operationType> <userIdentifierSource>UNSPECIFIED</userIdentifierSource> <userListId>{json-eval($.userListId)}</userListId> </googleAds.userListsMutate> Sample request for "JSON_ARRAY" { "customer_id": "123123123", "jsonArrayContent": [ {"phoneNumber": "+94112132234"}, {"email": "[email protected]"}, {"mobileId": "23131234324"} ], "userListId": "1232132321" } Acceptance Criteria for jsonArrayContent To upload a user list, the input must be a JSON array containing any number of user objects. Each user object represents a single user identifier. Below is the format and guidelines for creating and uploading the user list. Example Format: [ {"user_identifier1": "value1"}, {"user_identifier2": "value2"}, {"user_identifier3": "value3"} ] User Identifier Types: Each user object must contain only one of the following user identifiers: - Phone Number {"phoneNumber": "+94112132234"} - Email Address {"email": "[email protected]"} - Mobile ID {"mobileId": "23131234324"} - Third-Party User ID {"thirdPartyUserId": "2124234234"} - Address Information { "addressInfo": { "firstName": "Someone", "lastName": "Someone", "city": "somecity", "state": "aa", "countryCode": "aa", "postalCode": "12345", "streetAddress": "SampleRd" } } Additional Field: userIdentifierSource Each user object can optionally include a userIdentifierSource field with one of the following values: - FIRST_PARTY: User identifier provided by the advertiser. - THIRD_PARTY: User identifier provided by a partner. Example: {"userIdentifierSource": "FIRST_PARTY", "phoneNumber": "0772345164"} ** Notes:** - Each user object must contain only one user identifier. Multiple identifiers in the same object are treated as separate user objects. - Example of incorrect format: { "Email": "[email protected]", "Phone": "0893425678" } This will be treated as: [ {"email": "[email protected]"}, {"phoneNumber": "0893425678"} ] getCustomersThe getCustomers operation returns all customers. Parameter name Description Required customerId The ID of the customer being queried. Type: string Yes pageToken Token of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: string No pageSize Number of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integer No validateOnly If true, the request is validated but not executed. Type: boolean No returnTotalResultsCount If true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: boolean No summaryRowSetting Determines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: SummaryRowSetting enum No Sample configuration <googleAds.getCustomers configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> </googleAds.search> Sample request { "customer_id": "123123123" } getCampaignsThe getCampaigns operation returns all campaigns. Parameter name Description Required customerId The ID of the customer being queried. Type: string Yes pageToken Token of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: string No pageSize Number of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integer No validateOnly If true, the request is validated but not executed. Type: boolean No returnTotalResultsCount If true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: boolean No summaryRowSetting Determines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: SummaryRowSetting enum No Sample configuration <googleAds.getCampaigns configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> </googleAds.search> Sample request { "customer_id": "123123123" } getUserListsThe getUserLists operation returns all user lists. Parameter name Description Required customerId The ID of the customer being queried. Type: string Yes userListName The name of the user list to retrieve. Type: string No pageToken Token of the page to retrieve. If not specified, the first page of the results will be returned. Use the value obtained from nextPageToken in the previous response to request the next page of results. Type: string No pageSize Number of elements to retrieve in a single page. When too large a page is requested, the server may decide to further limit the number of returned resources. Type: integer No validateOnly If true, the request is validated but not executed. Type: boolean No returnTotalResultsCount If true, the total number of results that match the query ignoring the LIMIT clause will be included in the response. Default is false. Type: boolean No summaryRowSetting Determines whether a summary row will be returned. By default, a summary row is not returned. If requested, the summary row will be sent in a response by itself after all other query results are returned. Type: SummaryRowSetting enum No Sample configuration <googleAds.search configKey="GOOGLE_ADS_CONN"> <customerId>{json-eval($.customer_id)}</customerId> <userListName>{json-eval($.user_list_name)}</userListName> </googleAds.search> Sample request { "customer_id": "123123123", "user_list_name": "My User List" } Error codes related to Google Ads Connector¶ The connector may encounter errors during operation execution. When an error occurs, the ERROR_MESSAGE property will contain detailed information about the error. You can handle these errors using a Fault Sequence in your integration. For more information, see Using Fault Sequences. Error code Description 701001 General error. 701002 Invalid configuration error. 701003 Error in access token generation flow.