Microsoft Advertising API Guides

https://learn.microsoft.com/en-us/advertising/guides/
Admin
Microsoft Advertising API documentation providing guides for programmatic access to the Bing Ads...
Tokens:669,189
Snippets:4,982
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Java Labels example setup

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-labels

Java example setup for the Bing Ads v13 Labels example, including imports, constants for paging limits, and initialization of the CampaignManagementService client.

```java
package com.microsoft.bingads.examples.v13;

import java.util.Random;
import java.rmi.RemoteException;
import java.util.Calendar;
import java.util.List;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;

public class Labels extends ExampleBase {

    static java.lang.Integer MAX_GET_LABELS_BY_IDS = 1000;
    static java.lang.Integer MAX_LABEL_IDS_FOR_GET_LABEL_ASSOCIATIONS = 1;
    static java.lang.Integer MAX_ENTITY_IDS_FOR_GET_LABEL_ASSOCIATIONS = 100;
    static java.lang.Integer MAX_PAGING_SIZE = 1000;
        
    public static void main(java.lang.String[] args) {
    
        try
        {
            authorizationData = getAuthorizationData();
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                authorizationData, 
                API_ENVIRONMENT,
                ICampaignManagementService.class);

            // Add an ad group in a campaign. Later we will create labels for them. 
            // Although not included in this example you can also create labels for ads and keywords. 
```

--------------------------------

### Set up service and choose base campaign in Java

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-experiments

Starts a Java experiments example: sets up the Campaign Management service, retrieves campaigns by account ID, and selects a base campaign that is not an experiment and does not use a shared budget. If no eligible campaign exists, it prints a message and returns.

```java
package com.microsoft.bingads.examples.v13;

import java.util.ArrayList;
import java.util.Calendar;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;
import java.util.HashSet;
import java.util.List;
import java.util.stream.*;

public class Experiments extends ExampleBase {
    
    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData(); 
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                        authorizationData, 
                        API_ENVIRONMENT,
                        ICampaignManagementService.class);
            
            ArrayList<CampaignType> campaignTypes = new ArrayList<CampaignType>();
            campaignTypes.add(CampaignType.SEARCH);   
            
            // Choose a base campaign for the experiment.
                        
            outputStatusMessage("-----\nGetCampaignsByAccountId:");
            GetCampaignsByAccountIdResponse getCampaignsByAccountIdResponse = CampaignManagementExampleHelper.getCampaignsByAccountId(
                authorizationData.getAccountId(),
                campaignTypes,
                null);
            ArrayOfCampaign campaigns = getCampaignsByAccountIdResponse.getCampaigns();
            outputStatusMessage("Campaigns:");
            CampaignManagementExampleHelper.outputArrayOfCampaign(campaigns);  
            
            // The base campaign cannot be an experiment of another base campaign
            // i.e., the campaign's ExperimentId must be nil. 
            // Likewise the base campaign cannot use a shared budget
            // i.e., the campaign's BudgetId must be nil. 

            Campaign baseCampaign = null;
            if (baseCampaign == null) baseCampaign = campaigns.getCampaigns().stream().filter(
                    campaign -> campaign.getExperimentId() == null && campaign.getBudgetId() == null).findFirst().orElse(null);
            
            if (baseCampaign == null)
            {
                outputStatusMessage("You do not have any campaigns that are eligible for experiments.");
                return;
            }
```

--------------------------------

### Download and Upload Bulk Data (Python)

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-bulk-requests

Python example that downloads campaigns by account IDs, polls the download status, and starts a bulk upload by requesting an upload URL. Requires the auth_helper module and the openapi_client bulk models.

```python
import time
import os
from auth_helper import *
from openapi_client.models.bulk import *

# The full path to the bulk file
BULK_FILE_PATH = "c:\\dev\\bulk\\campaigns.zip"
UPLOAD_FILE_PATH = "c:\\dev\\bulk\\campaigns_upload.zip"

def main(authorization_data):
    try:
        # Confirm that the download folder exists
        folder = os.path.dirname(BULK_FILE_PATH)
        if not os.path.exists(folder):
            print(f"The output folder, {folder}, does not exist.")
            print("Ensure that the folder exists and try again.")
            return
        
        # Download campaigns by account IDs
        print("Requesting bulk download...")
        
        download_request = DownloadCampaignsByAccountIdsRequest(
            account_ids=[authorization_data.account_id],
            data_scope=DataScope.ENTITYDATA,
            download_entities=[DownloadEntity.ADGROUPS, DownloadEntity.CAMPAIGNS],
            download_file_type=DownloadFileType.CSV,
            format_version='6.0',
            last_sync_time_in_utc=None
        )
        
        download_response = bulk_service.download_campaigns_by_account_ids(
            download_campaigns_by_account_ids_request=download_request
        )
        
        download_request_id = download_response.DownloadRequestId
        
        if not download_request_id:
            print("DownloadRequestId should not be null")
            return
        
        print(f"Download Request ID: {download_request_id}")
        
        # Poll for download status
        print("\nPolling for download status...")
        
        download_success = False
        wait_time = 5
        result_file_url = None
        
        for i in range(10):
            time.sleep(wait_time)
            
            status_request = GetBulkDownloadStatusRequest(
                request_id=download_request_id
            )
            
            status_response = bulk_service.get_bulk_download_status(
                get_bulk_download_status_request=status_request
            )
            
            request_status = status_response.RequestStatus
            result_file_url = status_response.ResultFileUrl
            
            print(f"Attempt {i+1}:")
            print(f"  PercentComplete: {status_response.PercentComplete}")
            print(f"  RequestStatus: {request_status}")
            print(f"  ResultFileUrl: {result_file_url}")
            
            if request_status == "Completed":
                download_success = True
                break
        
        if download_success and result_file_url:
            print(f"\nDownloading file from {result_file_url}...")
            # In a real implementation, you would download the file here
            # For example, using requests library:
            # import requests
            # response = requests.get(result_file_url)
            # with open(BULK_FILE_PATH, 'wb') as f:
            #     f.write(response.content)
            print(f"File would be saved to: {BULK_FILE_PATH}")
        else:
            print(f"Download request failed or timed out. Request ID: {download_request_id}")
            return
        
        # Bulk Upload
        print("\n" + "="*50)
        print("Starting bulk upload...")
        
        get_upload_url_request = GetBulkUploadUrlRequest(
            response_mode=ResponseMode.ERRORSANDRESULTS,
            account_id=authorization_data.account_id
        )
        
        upload_url_response = bulk_service.get_bulk_upload_url(
            get_bulk_upload_url_request=get_upload_url_request
        )
        
        upload_request_id = upload_url_response.RequestId
        upload_url = upload_url_response.UploadUrl
```

--------------------------------

### Manage Conversion Goals with PHP (Add, Get, Update)

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-conversion-goals

PHP code example for managing conversion goals in Microsoft Advertising. It shows adding an app install goal, fetching goals by IDs, and updating a goal (including changing its type). The code uses the Campaign Management service and includes assertions for partial errors.

```php
$appInstallGoal = new AppInstallGoal();
// You must provide a valid app platform and app store identifier,
// otherwise this goal will not be added successfully.
$appInstallGoal->setAppPlatform("Windows");
$appInstallGoal->setAppStoreId("AppStoreIdGoesHere");
$appInstallGoal->setConversionWindowInMinutes(30);
$appInstallGoal->setCountType(ConversionGoalCountType::ALL);
$appInstallGoal->setName("My App Install Goal".self::generateRandomAlphaNumeric());
// Account scope is not supported for app install goals. You can
// set scope to Customer or don't set it for the same result.
$appInstallGoal->setScope(EntityScope::CUSTOMER);
$appInstallGoal->setStatus(ConversionGoalStatus::ACTIVE);
// The TagId is inherited from the ConversionGoal base class,
// however, App Install goals do not use a UET tag.

$revenue = new ConversionGoalRevenue();
$revenue->setType(ConversionGoalRevenueType::FIXED_VALUE);
$revenue->setValue(5.00);
$appInstallGoal->setRevenue($revenue);

$request = new AddConversionGoalsRequest([
    'ConversionGoals' => [$durationGoal, $eventGoal, $pagesViewedPerVisitGoal, $urlGoal, $appInstallGoal]
]);

$response = self::$campaignManagementServiceApi->addConversionGoals($request);
$goalIds = $response->getConversionGoalIds() ?? [];
print("ConversionGoalIds:\r\n");
print_r($goalIds);
print("PartialErrors:\r\n");
print_r($response->getPartialErrors());
self::assertEmpty($response->getPartialErrors());
self::assertNotEmpty($goalIds);

return array_values(array_filter($goalIds));
}
```

```php
/**
 * @depends testAddConversionGoals
 * @throws ApiException
 */
public function testGetConversionGoalsByIds($goalIds)
{
    print("-----\r\nFetching Conversion Goals:\r\n");

    $request = new GetConversionGoalsByIdsRequest([
        'ConversionGoalIds' => $goalIds,
        'ConversionGoalTypes' => $this->conversionGoalTypes,
        'ReturnAdditionalFields' => $this->returnAdditionalFields
    ]);

    $response = self::$campaignManagementServiceApi->getConversionGoalsByIds($request);
    $conversionGoals = $response->getConversionGoals() ?? [];
    print("ConversionGoals:\r\n");
    print_r($conversionGoals);
    print("PartialErrors:\r\n");
    print_r($response->getPartialErrors());
    self::assertEmpty($response->getPartialErrors());
    self::assertNotEmpty($conversionGoals);
}
```

```php
/**
 * @depends testAddConversionGoals
 * @depends testGetConversionGoalsByIds
 * @throws ApiException
 */
public function testUpdateConversionGoals($goalIds)
{
    print("-----\r\nUpdating Conversion Goals:\r\n");

    $updateDurationGoal = new DurationGoal();
    // You can change the conversion goal type e.g. in this example an event goal
    // had been created above at index 1. Now we are using the returned identifier
    // at index 1 to update the type from EventGoal to DurationGoal.
    $updateDurationGoal->setId($goalIds[1]);
    $updateDurationGoal->setName("Updated Duration Goal".self::generateRandomAlphaNumeric());
    $updateDurationGoal->setConversionWindowInMinutes(60);
    $updateDurationGoal->setCountType(ConversionGoalCountType::UNIQUE);
    $updateDurationGoal->setMinimumDurationInSeconds(120);
    $updateDurationGoal->setStatus(ConversionGoalStatus::PAUSED);
    // The Scope cannot be updated, even if you update the goal type.
    // You can either send the same value or leave Scope empty.
    $updateDurationGoal->setScope(EntityScope::ACCOUNT);

    $revenue = new ConversionGoalRevenue();
    $revenue->setType(ConversionGoalRevenueType::FIXED_VALUE);
    $revenue->setValue(10.00);
    $updateDurationGoal->setRevenue($revenue);
    // You can update the tag as needed. In this example we will explicitly use the same UET tag.
    // To keep the UET tag unchanged, you can also leave this element nil or empty.
    // Update Event Goal

    $updateEventGoal = new EventGoal();
    // For both add and update conversion goal operations, you must include one or more
    // of the following event operator pairs:
    // (ActionOperator and ActionExpression), (CategoryOperator and CategoryExpression),
    // (LabelOperator and LabelExpression), (ValueOperator and Value).
    // Each event pair (e.g. ActionOperator and ActionExpression) is optional if you include
    // one or more of the other events.
```

--------------------------------

### Set up a service API client with Configuration

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started-php

Configure authentication once using the Configuration class and construct a typed API client per service. This example sets up a CampaignManagementServiceApi with OAuth desktop/mobile auth code grant, sandbox environment, and a refresh token. Replace placeholders like YOUR_CLIENT_ID and YOUR_ACCOUNT_ID with actual values.

```php
use Microsoft\MsAds\Rest\Api\CampaignManagementServiceApi;
use Microsoft\MsAds\Rest\Auth\ApiEnvironment;
use Microsoft\MsAds\Rest\Auth\AuthorizationData;
use Microsoft\MsAds\Rest\Auth\OAuthDesktopMobileAuthCodeGrant;
use Microsoft\MsAds\Rest\Auth\OAuthScope;
use Microsoft\MsAds\Rest\Configuration;
use GuzzleHttp\Client;

$configuration = Configuration::getDefaultConfiguration();

$authentication = (new OAuthDesktopMobileAuthCodeGrant())
    ->withEnvironment(ApiEnvironment::SANDBOX)
    ->withClientId('YOUR_CLIENT_ID')
    ->withOAuthScope(OAuthScope::MSADS_MANAGE);

$configuration->setAuthorizationData(
    (new AuthorizationData())
        ->withAuthentication($authentication)
        ->withDeveloperToken('BBD37VB98')
        ->withCustomerId('YOUR_CUSTOMER_ID')
        ->withAccountId('YOUR_ACCOUNT_ID')
);

$configuration->getAuthorizationData()->Authentication->RequestOAuthTokensByRefreshToken($refreshToken);

$campaignManagementServiceApi = new CampaignManagementServiceApi(
    new Client(),
    $configuration,
    null,
    ApiEnvironment::SANDBOX
);
```

--------------------------------

### OfflineConversions class setup (Java)

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-offline-conversions

This Java snippet shows the class declaration and main method setup for the OfflineConversions example, including imports and service client initialization.

```java
package com.microsoft.bingads.examples.v13;

import java.util.ArrayList;

import java.util.Calendar;
import java.util.TimeZone;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;

public class OfflineConversions extends ExampleBase {

    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData();
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                        authorizationData, 
                        API_ENVIRONMENT,
                        ICampaignManagementService.class);
```

--------------------------------

### Add and Search Client Links in Java

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-client-links

Java example that adds a client link if required and then searches for client links. It uses CustomerManagementExampleHelper to add and search client links, and handles exceptions with ExampleExceptionHelper.

```java
if(newLinkRequired)
            {
                clientLink = new ClientLink();
                clientLink.setClientEntityId(ClientAccountId);
                clientLink.setManagingCustomerId(authorizationData.getCustomerId());
                clientLink.setIsBillToClient(true);
                clientLink.setName("My Client Link");
                clientLink.setStartDate(null);
                clientLink.setSuppressNotification(true);

                ArrayOfClientLink addClientLinks = new ArrayOfClientLink();
                addClientLinks.getClientLinks().add(clientLink);
                
                outputStatusMessage("-----\nAddClientLinks:");
                AddClientLinksResponse addClientLinksResponse = CustomerManagementExampleHelper.addClientLinks(
                        addClientLinks);
                outputStatusMessage("OperationErrors:");                    
                CustomerManagementExampleHelper.outputArrayOfOperationError(addClientLinksResponse.getOperationErrors());   
                outputStatusMessage("PartialErrors:");
                for(ArrayOfOperationError operationErrors: addClientLinksResponse.getPartialErrors().getArrayOfOperationErrors())
                {
                    CustomerManagementExampleHelper.outputArrayOfOperationError(operationErrors);   
                }
            }

            // Output the client links after any status updates above.

            outputStatusMessage("-----\nSearchClientLinks:");
            clientLinks = CustomerManagementExampleHelper.searchClientLinks(
                predicates,
                ordering,
                pageInfo).getClientLinks();
            outputStatusMessage("ClientLinks:");
            CustomerManagementExampleHelper.outputArrayOfClientLink(clientLinks);
        } 
        catch (Exception ex) {
            String faultXml = ExampleExceptionHelper.getBingAdsExceptionFaultXml(ex, System.out);
            outputStatusMessage(faultXml);
            String message = ExampleExceptionHelper.handleBingAdsSDKException(ex, System.out);
            outputStatusMessage(message);
        }
    }
}
```

--------------------------------

### Upgrade the Bing Ads Python SDK with pip.exe install --upgrade msads

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started-python

Run this command if you already have the Bing Ads Python SDK installed to get the latest bits.

```powershell
pip.exe install --upgrade msads

```

--------------------------------

### Set up Campaign Management service client in Java

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-profile-criteria

Java example that sets up the Campaign Management service client for the ProfileCriteria example. It imports the necessary Bing Ads and Java libraries, initializes authorization data, and creates a ServiceClient for ICampaignManagementService.

```java
package com.microsoft.bingads.examples.v13;

import java.util.ArrayList;

import com.microsoft.bingads.*;
import com.microsoft.bingads.v13.campaignmanagement.*;
import java.io.File;
import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.nio.file.Files;
import java.util.Base64;
import java.util.Calendar;

public class ProfileCriteria extends ExampleBase {

    public static void main(java.lang.String[] args) {
    
        try
        {
            authorizationData = getAuthorizationData();
             
            CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                authorizationData, 
                API_ENVIRONMENT,
                ICampaignManagementService.class);
```

--------------------------------

### Python ReportFileReader usage

Source: https://learn.microsoft.com/en-us/advertising/guides/sdk-reporting-service-manager

Python example: instantiate ReportFileReader with file_path and format='Csv', get the report container, access report_records, and close the container.

```python
report_file_reader = ReportFileReader(
    file_path=result_file_name, 
    format='Csv'
)
report_container=report_file_reader.get_report()
report_record_iterable=report_container.report_records
report_container.close()
```

--------------------------------

### Initialize and run main with Campaign Management service

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-responsive-ads

Main entry point that initializes authorization data, authenticates, creates a Campaign Management service client (version 13), and calls the main function. Requires DEVELOPER_TOKEN and ENVIRONMENT to be defined.

```python
if __name__ == '__main__':
    print("Loading the web service client...")

    authorization_data = AuthorizationData(
        account_id=None,
        customer_id=None,
        developer_token=DEVELOPER_TOKEN,
        authentication=None,
    )

    authenticate(authorization_data)

    campaign_service = ServiceClient(
        service='CampaignManagementService',
        version=13,
        authorization_data=authorization_data,
        environment=ENVIRONMENT,
    )

    main(authorization_data)
```

--------------------------------

### Java ReportFileReader usage

Source: https://learn.microsoft.com/en-us/advertising/guides/sdk-reporting-service-manager

Java example: create ReportFileReader with the file path and ReportFormat.CSV, get the Report, iterate records, and close the report.

```java
ReportFileReader reportFileReader = new ReportFileReader(
    ResultFileName,
    ReportFormat.CSV
);
Report report = reportFileReader.getReport();
Iterable<ReportRecord> reportRecords = report.getReportRecords();
report.close();
```

--------------------------------

### C# ReportFileReader usage

Source: https://learn.microsoft.com/en-us/advertising/guides/sdk-reporting-service-manager

C# example: instantiate ReportFileReader with the file path and ReportFormat.Csv, get the Report, iterate records, and dispose the report.

```csharp
ReportFileReader reportFileReader = new ReportFileReader(
    ResultFileName,
    ReportFormat.Csv
);
Report report = reportFileReader.GetReport();
IEnumerable<IReportRecord> reportRecordIterable = reportContainer.GetReportRecords();
report.Dispose();
```

--------------------------------

### Create Responsive Ad Recommendation and Audience Campaign in Python

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-responsive-ads

Python example that creates a responsive ad recommendation, selects suggested images, adds them to media, creates an Audience campaign with an ad group and responsive ad, then cleans up by deleting media and campaigns. Requires auth_helper and openapi_client models.

```python
import base64
import uuid

from auth_helper import *
from openapi_client.models.campaign import *


def main(authorization_data):
    try:
        ad_final_url = "https://contoso.com"
        final_urls = [ad_final_url]
        create_responsive_ad_recommendation_request = CreateResponsiveAdRecommendationRequest(
            final_urls=final_urls
        )

        responsive_ad_recommendation_response = campaign_service.create_responsive_ad_recommendation(
            create_responsive_ad_recommendation_request=create_responsive_ad_recommendation_request
        )

        responsive_ad = responsive_ad_recommendation_response.ResponsiveAd
        image_suggestions = responsive_ad_recommendation_response.ImageSuggestions

        # Select a few images from the suggested list. This example picks first 5 images
        selected_images = image_suggestions[:5]

        # Add selected images to your media library
        save_images(selected_images)

        images = [obj.AssetLink for obj in selected_images]
        responsive_ad.Images = images
        responsive_ad.BusinessName = "Contoso"
        responsive_ad.CallToActionLanguage = LanguageName.ENGLISH

        # Create an Audience campaign with one ad group and a responsive ad
        campaign = Campaign()
        campaign.BudgetType = BudgetLimitType.DAILYBUDGETACCELERATED
        # CampaignType must be set for Audience campaigns
        campaign.CampaignType = CampaignType.AUDIENCE
        campaign.DailyBudget = 50.00
        campaign.Languages = ['All']
        campaign.Name = "Ad recommendation test " + str(uuid.uuid4())
        campaign.TimeZone = 'PacificTimeUSCanadaTijuana'
        campaigns = [campaign]

        add_campaigns_request = AddCampaignsRequest(
            account_id=authorization_data.account_id,
            campaigns=campaigns,
        )

        add_campaigns_response = campaign_service.add_campaigns(
            add_campaigns_request=add_campaigns_request
        )
        campaign_ids = add_campaigns_response.CampaignIds

        # Add an ad group within the campaign.
        ad_group = AdGroup()
        ad_group.Name = "Holiday Sale"
        ad_group.StartDate = None
        end_date = Date()
        end_date.Day = 31
        end_date.Month = 12
        current_time = gmtime()
        end_date.Year = current_time.tm_year
        ad_group.EndDate = end_date
        cpc_bid = Bid()
        cpc_bid.Amount = 0.09
        ad_group.CpcBid = cpc_bid
        # Network cannot be set for ad groups in Audience campaigns
        ad_group.Network = None
        ad_groups = [ad_group]

        add_ad_groups_request = AddAdGroupsRequest(
            campaign_id=campaign_ids[0],
            ad_groups=ad_groups
        )

        add_ad_groups_response = campaign_service.add_ad_groups(
            add_ad_groups_request=add_ad_groups_request
        )
        ad_group_ids = add_ad_groups_response.AdGroupIds

        # Add a responsive ad within the ad group
        ads = [responsive_ad]
        add_ads_request = AddAdsRequest(
            ad_group_id=ad_group_ids[0],
            ads=ads
        )

        add_ads_response = campaign_service.add_ads(
            add_ads_request=add_ads_request
        )
        ad_ids = add_ads_response.AdIds

        # Clean up
        media_ids = [obj.Asset.Id for obj in responsive_ad.Images]
        delete_media_request = DeleteMediaRequest(
            account_id=authorization_data.account_id,
            media_ids=media_ids
        )

        campaign_service.delete_media(
            delete_media_request=delete_media_request
        )

        delete_campaigns_request = DeleteCampaignsRequest(
            account_id=authorization_data.account_id,
            campaign_ids=campaign_ids
        )

        campaign_service.delete_campaigns(
            delete_campaigns_request=delete_campaigns_request
        )

    except Exception as ex:
        print(f"Error occurred: {str(ex)}")


def download_bytes(url):
    """Download bytes from a URL using streaming."""
    response = requests.get(url, stream=True)
    response.raise_for_status()
```

--------------------------------

### Add microsoft.bingads Maven dependency

Source: https://learn.microsoft.com/en-us/advertising/guides/get-started-java

Add the microsoft.bingads dependency to a Maven POM file to install the Bing Ads Java SDK. Version 13.0.10 is shown as an example.

```XML
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  ...
  <dependencies>
    <dependency>
      <groupId>com.microsoft.bingads</groupId>
      <artifactId>microsoft.bingads</artifactId>
          <version>13.0.10</version>
    </dependency>
  </dependencies>
</project>
```

--------------------------------

### Associate, retrieve, and update ad extensions in Java

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-ad-extensions

Java code example for managing ad extensions in Microsoft Advertising. It associates ad extensions with a campaign, retrieves editorial rejection reasons, gets location ad extensions by IDs, and updates them to remove scheduling. The example uses CampaignManagementExampleHelper methods and handles partial errors.

```java
outputStatusMessage("-----\nSetAdExtensionsAssociations:");
SetAdExtensionsAssociationsResponse setAdExtensionsAssociationsResponse = CampaignManagementExampleHelper.setAdExtensionsAssociations(
    authorizationData.getAccountId(), 
    adExtensionIdToEntityIdAssociations, 
    AssociationType.CAMPAIGN);
outputStatusMessage("PartialErrors:");
CampaignManagementExampleHelper.outputArrayOfBatchError(setAdExtensionsAssociationsResponse.getPartialErrors());
```

```java
outputStatusMessage("-----\nGetAdExtensionsEditorialReasons:");
GetAdExtensionsEditorialReasonsResponse getAdExtensionsEditorialReasonsResponse = CampaignManagementExampleHelper.getAdExtensionsEditorialReasons(
    authorizationData.getAccountId(), 
    adExtensionIdToEntityIdAssociations, 
    AssociationType.CAMPAIGN);
outputStatusMessage("EditorialReasons:");
ArrayOfAdExtensionEditorialReasonCollection adExtensionEditorialReasonCollection = getAdExtensionsEditorialReasonsResponse.getEditorialReasons();
CampaignManagementExampleHelper.outputArrayOfAdExtensionEditorialReasonCollection(adExtensionEditorialReasonCollection);
outputStatusMessage("PartialErrors:");
CampaignManagementExampleHelper.outputArrayOfBatchError(getAdExtensionsEditorialReasonsResponse.getPartialErrors());
```

```java
ArrayList<AdExtensionsTypeFilter> adExtensionsTypeFilter = new ArrayList<AdExtensionsTypeFilter>();
adExtensionsTypeFilter.add(AdExtensionsTypeFilter.LOCATION_AD_EXTENSION);

ArrayList<AdExtensionAdditionalField> returnAdditionalFields = new ArrayList<AdExtensionAdditionalField>();
returnAdditionalFields.add(AdExtensionAdditionalField.DISPLAY_TEXT);
returnAdditionalFields.add(AdExtensionAdditionalField.IMAGES);
```

```java
outputStatusMessage("-----\nGetAdExtensionsByIds:");
GetAdExtensionsByIdsResponse getAdExtensionsByIdsResponse = CampaignManagementExampleHelper.getAdExtensionsByIds(
    authorizationData.getAccountId(),
    adExtensionIds,
    adExtensionsTypeFilter,
    returnAdditionalFields);
adExtensions = getAdExtensionsByIdsResponse.getAdExtensions();
outputStatusMessage("AdExtensions:");
CampaignManagementExampleHelper.outputArrayOfAdExtension(adExtensions);
outputStatusMessage("PartialErrors:");
CampaignManagementExampleHelper.outputArrayOfBatchError(getAdExtensionsByIdsResponse.getPartialErrors());
```

```java
ArrayOfAdExtension updateExtensions = new ArrayOfAdExtension();
ArrayOflong updateExtensionIds = new ArrayOflong();

for (AdExtension extension : adExtensions.getAdExtensions())
{
    // GetAdExtensionsByIds will return a nil element if the request conditions were not met.
    if(extension != null && extension.getId() != null)
    {
        // Remove read-only elements that would otherwise cause the update operation to fail.
        AdExtension updateExtension = setReadOnlyAdExtensionElementsToNull(extension);

        // If you set the Scheduling element null, any existing scheduling set for the ad extension will remain unchanged. 
        // If you set this to any non-null Schedule object, you are effectively replacing existing scheduling 
        // for the ad extension. In this example, we will remove any existing scheduling by setting this element  
        // to an empty Schedule object.
        updateExtension.setScheduling(new Schedule());
        updateExtensions.getAdExtensions().add(updateExtension);
        updateExtensionIds.getLongs().add((long)updateExtension.getId());
    }
}

outputStatusMessage("-----\nUpdateAdExtensions:"); 
CampaignManagementExampleHelper.updateAdExtensions(
        authorizationData.getAccountId(), 
        updateExtensions);
outputStatusMessage("Removed scheduling from the location ad extensions.");
```

--------------------------------

### C# Responsive Ads Setup with Campaign Management

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-responsive-ads

C# example for setting up Responsive Ads for the Microsoft Audience Network using the Campaign Management service. Requires an image file at the specified path and proper authorization. The code adds an image to the media library and begins creating an Audience campaign.

```csharp
using System;
using System.IO;
using System.Linq;
using System.ServiceModel;
using System.Threading.Tasks;
using Microsoft.BingAds.V13.CampaignManagement;
using Microsoft.BingAds;
using System.Drawing;

namespace BingAdsExamplesLibrary.V13
{
    /// <summary>
    /// How to create Responsive Ads with the Campaign Management service.
    /// </summary>
    public class ResponsiveAds : ExampleBase
    {
        // To run this example you'll need to provide your own image.  
        // For required aspect ratios and recommended dimensions please see 
        // Image remarks at https://go.microsoft.com/fwlink/?linkid=872754.

        private const string MediaFilePath = "c:\\dev\\media\\";
        private const string ResponsiveAdMediaFileName = "imageresponsivead1200x628.png";

        public override string Description
        {
            get { return "Responsive Ads | Campaign Management V13"; }
        }

        public async override Task RunAsync(AuthorizationData authorizationData)
        {
            try
            {
                ApiEnvironment environment = ((OAuthDesktopMobileAuthCodeGrant)authorizationData.Authentication).Environment;

                CampaignManagementExampleHelper CampaignManagementExampleHelper = new CampaignManagementExampleHelper(
                    OutputStatusMessageDefault: this.OutputStatusMessage);
                CampaignManagementExampleHelper.CampaignManagementService = new ServiceClient<ICampaignManagementService>(
                    authorizationData: authorizationData,
                    environment: environment);

                // Add an image to your media library. 
                // The image asset is needed later to create the responsive ad.

                var landscapeImageMedia = GetImageMedia(
                    "Image191x100",
                    MediaFilePath + ResponsiveAdMediaFileName,
                    System.Drawing.Imaging.ImageFormat.Png);

                var media = new Media[]
                {
                    landscapeImageMedia,
                };

                OutputStatusMessage("-----\nAddMedia:");
                AddMediaResponse addMediaResponse = await CampaignManagementExampleHelper.AddMediaAsync(
                    accountId: authorizationData.AccountId,
                    media: media);
                long[] mediaIds = addMediaResponse.MediaIds.ToArray();
                OutputStatusMessage("MediaIds:");
                CampaignManagementExampleHelper.OutputArrayOfLong(mediaIds);
                
                // Create an Audience campaign with one ad group and a responsive ad.

                var campaigns = new[]{
                    new Campaign
                    {
                        BudgetType = BudgetLimitType.DailyBudgetStandard,
                        // CampaignType must be set for Audience campaigns
                        CampaignType = CampaignType.Audience,
                        DailyBudget = 50,
                        // Languages must be set for Audience campaigns
                        Languages = new string[] { "All" },
                        Name = "Everyone's Shoes " + DateTime.UtcNow,
                        TimeZone = "PacificTimeUSCanadaTijuana",
                    },
                };
```

--------------------------------

### GetBMCStoresByCustomerId Response XML

Source: https://learn.microsoft.com/en-us/advertising/guides/smart-shopping-campaigns

Example response from the GetBMCStoresByCustomerId operation showing the store identifier and details. Use this to retrieve the Microsoft Merchant Center store ID for your smart shopping campaign setup.

```xml
<GetBMCStoresByCustomerIdResponse xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
    <BMCStores xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <BMCStore>
            <HasCatalog>true</HasCatalog>
            <Id>StoreIdGoesHere</Id>
            <IsActive>true</IsActive>
            <IsProductAdsEnabled>true</IsProductAdsEnabled>
            <Name>My MMC Store</Name>
            <SubType i:nil="true"/>
        </BMCStore>
    </BMCStores>
</GetBMCStoresByCustomerIdResponse>
```

--------------------------------

### Sample package.json

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-remarketing-lists

A sample package.json file with basic metadata and scripts.

```json
{
    "name": "example",
    "version": "1.0.0",
    "description": "A sample package.json",
    "main": "index.js",
    "scripts": {
        "start": "node index.js",
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "author": "",
    "license": "ISC"
}
```

--------------------------------

### CustomerSignup.java - Sign up a new customer and account

Source: https://learn.microsoft.com/en-us/advertising/guides/code-example-customer-signup

Use this Java example to sign up a new customer and advertiser account via the Customer Management API. It first retrieves the current user and checks that the user has the aggregator role (33) before proceeding. The example creates a customer and account with sample properties, then calls SignupCustomer and prints the new customer ID and number.

```java
public class CustomerSignup extends ExampleBase {
        
    public static void main(java.lang.String[] args) {
     
        try
        {
            authorizationData = getAuthorizationData();
                         
            CustomerManagementExampleHelper.CustomerManagementService = new ServiceClient<ICustomerManagementService>(
                    authorizationData, 
                    API_ENVIRONMENT,
                    ICustomerManagementService.class);
            
            outputStatusMessage("-----\nGetUser:");
            GetUserResponse getUserResponse = CustomerManagementExampleHelper.getUser(
                    null);
            User user = getUserResponse.getUser();
            outputStatusMessage("User:");
            CustomerManagementExampleHelper.outputUser(user);
            outputStatusMessage("CustomerRoles:");
            CustomerManagementExampleHelper.outputArrayOfCustomerRole(getUserResponse.getCustomerRoles());
                            
            // Only a user with the aggregator role (33) can sign up new customers. 
            // If the user does not have the aggregator role, then do not continue.
            
            ArrayOfint roleIds = new ArrayOfint();
            for(CustomerRole customerRole : getUserResponse.getCustomerRoles().getCustomerRoles()){
                roleIds.getInts().add(customerRole.getRoleId());
            }
            if(!roleIds.getInts().contains(33))
            {
                outputStatusMessage("Only a user with the aggregator role (33) can sign up new customers.");
                return;
            }

            Customer customer = new Customer();

            // The primary business segment of the customer, for example, automotive, food, or entertainment.
            customer.setIndustry(Industry.OTHER);

            // The primary country where the customer operates. 
            customer.setMarketCountry("US");

            // The primary language that the customer uses. 
            customer.setMarketLanguage(LanguageType.ENGLISH);

            // The name of the customer.
            customer.setName("Child Customer " + System.currentTimeMillis());
                        
            AdvertiserAccount account = new AdvertiserAccount();

            // The location where your business is legally registered. 
            // The business address is used to determine your tax requirements.
            Address businessAddress = new Address();
            businessAddress.setBusinessName("Contoso");
            businessAddress.setCity("Redmond");
            businessAddress.setLine1("One Microsoft Way");
            businessAddress.setPostalCode("98052");
            businessAddress.setStateOrProvince("WA");
            account.setBusinessAddress(businessAddress);

            // The type of currency that is used to settle the account. 
            // The service uses the currency information for billing purposes.
            account.setCurrencyCode(CurrencyCode.USD);

            // The name of the account. 
            account.setName("Child Account " + System.currentTimeMillis());

            // The identifier of the customer that owns the account. 
            account.setParentCustomerId((long)user.getCustomerId());

            // The TaxInformation (VAT identifier) is optional. If specified, The VAT identifier must be valid 
            // in the country that you specified in the BusinessAddress element. Without a VAT registration 
            // number or exemption certificate, taxes might apply based on your business location.
            account.setTaxInformation(null);

            // The default time-zone for campaigns in this account.
            account.setTimeZone(TimeZoneType.PACIFIC_TIME_US_CANADA_TIJUANA);
            
            // Signup a new customer and account for the reseller. 
            outputStatusMessage("-----\nSignupCustomer:");
            SignupCustomerResponse signupCustomerResponse = CustomerManagementExampleHelper.signupCustomer(
                customer,
                account,
                user.getCustomerId(),
                null,
                null);

            outputStatusMessage("New Customer and Account:");

            // This is the identifier that you will use to set the CustomerId 
            // element in most of the Bing Ads API service operations.
            outputStatusMessage(String.format("\tCustomerId: %s", signupCustomerResponse.getCustomerId()));

            // The read-only system-generated customer number that is used in the Bing Ads web application. 
            // The customer number is of the form, Cnnnnnnn, where nnnnnnn is a series of digits.
            outputStatusMessage(String.format("\tCustomerNumber: %s", signupCustomerResponse.getCustomerNumber()));
        }
    }
}
```
Tokens:
Raw