Skip to main content

Microsoft Bing Ads Component

Manage campaigns, accounts, and customer services in Microsoft Bing Ads.

Component key: ms-bing-ads · Changelog ↓

Description​

Microsoft Advertising is a pay-per-click (PPC) advertising platform used to display ads based on the keywords used in a search query. The Bing Ads API provides programmatic access to Microsoft Advertising for managing large campaigns or integrating marketing with other systems.

This component allows you to add external conversions to Ads campaigns.

API Documentation​

This component was built using the Bing Ads API currently utilizing v13.

Microsoft documents many frequently asked questions that aid in troubleshooting.

Connections​

OAuth 2.0​

key: oauth

This component uses OAuth 2.0 to connect to the Microsoft Bing Ads API. Create a connection of type OAuth 2.0 to authenticate.

Prerequisites​

Setup Steps​

Obtain a Developer Token:

  1. Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
  2. Select the user to associate with the developer token. Typically an application only needs one universal token regardless of how many users are supported.
  3. Click the Request Token button and copy the token value.

Register an Azure Application:

Microsoft Advertising uses the Microsoft identity platform endpoint and the OAuth 2.0 protocol to authenticate work or school accounts from Azure Active Directory (AAD) and personal Microsoft accounts (MSA), such as hotmail.com, outlook.com, and msn.com.

  1. Navigate to the Azure portal - App registrations page. Sign in using either a personal Microsoft Account or a Work or School Account.
  2. Select New registration.
  3. On the Register an application page, enter the registration information:
    • In the Name section, enter a meaningful application name.
    • In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts.
  4. Select Register to create the application.
  5. On the app Overview page, find the Application (client) ID value and record it.
  6. Select the Add a Redirect URI link to open the Redirect URIs page. Add the callback URL: https://oauth2.prismatic.io/callback
  7. Select Certificates & secrets under Manage. Click the New client secret button. Enter a value in Description, select an option for Expires, and choose Add. Copy the client secret value before leaving the page. Refer to the Microsoft OAuth token documentation for additional details.

Configure the Connection​

  • Enter the Client ID from the Azure app registration Overview page
  • Enter the Client Secret Value generated in the Certificates & secrets section
  • Enter the Developer Token obtained from the Microsoft Advertising Developer Portal
  • Optionally, enable Use Sandbox to connect to the Microsoft Advertising sandbox environment instead of production
Using the Sandbox Environment

The Use Sandbox toggle switches the connection to the Microsoft Advertising sandbox environment (api.sandbox.bingads.microsoft.com) instead of production. This is useful for testing without affecting live campaign data. A separate sandbox developer token is required for sandbox access, which is different from the production developer token obtained from the Microsoft Advertising Developer Portal.

InputNotesExample
Authorize URL

The OAuth 2.0 Authorization URL for Microsoft Bing Ads.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Client ID

The client ID of the registered OAuth application for Microsoft Bing Ads.

Client Secret Value

The client secret value of the registered OAuth application for Microsoft Bing Ads.

Developer Token

The developer token from the Account Manager account used for API authentication.

Scopes

The permission scopes for the Microsoft Bing Ads OAuth application.

https://ads.microsoft.com/msads.manage offline_access
Token URL

The OAuth 2.0 Token URL for Microsoft Bing Ads.

https://login.microsoftonline.com/common/oauth2/v2.0/token
Use Sandbox

When true, uses the Microsoft Advertising sandbox environment (api.sandbox.bingads.microsoft.com) instead of production.

false

Data Sources​

Select Account ID​

Gets the account identifiers that are accessible from the specified customer. | key: selectAccountId | type: picklist

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

Customer ID

The unique identifier for the customer.

{
  "result": [
    {
      "key": "156089854",
      "label": "Contoso Advertising (id: 156089854)"
    },
    {
      "key": "156089912",
      "label": "Fabrikam Marketing (id: 156089912)"
    },
    {
      "key": "156090045",
      "label": "Northwind Campaigns (id: 156090045)"
    }
  ]
}

Select Customer ID​

Gets the customer identifiers that are accessible to the current authenticated user. | key: selectCustomerId | type: picklist

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

{
  "result": [
    {
      "key": "169592807",
      "label": "Contoso Ltd (id: 169592807)"
    },
    {
      "key": "169593041",
      "label": "Fabrikam Inc (id: 169593041)"
    },
    {
      "key": "169594112",
      "label": "Northwind Traders (id: 169594112)"
    }
  ]
}

Actions​

Initiates the client link process to manage the accounts of another customer. Sends a link request from one customer to another customer or account. | key: addClientLinks

InputNotesExample
Client Entity ID

The identifier of the client advertiser account or client customer to manage.

Connection

The Microsoft Bing Ads connection to use.

Customer Link Permission

Determines whether the user's access to the accounts is restricted by customer hierarchy i.e., customer level client linking. This element is only applicable if Type is set to CustomerLink. In that case, the possible values include Administrative and Standard. Otherwise this field should be nil or empty.

Inviter Email

The email address of the user who created the client link request.

john.doe@example.com
Inviter Name

The name of the parent customer of the user who created the client link request.

Inviter Phone

The phone number of the user who created the client link request.

Is Bill To Client

Determines whether the owner of the client advertiser account or the managing customer is responsible for billing payments.

false
Managing Customer ID

The identifier of the customer who manages or is requesting to manage the client advertiser account.

Name

The friendly name that can be used to reference this client link. The name can contain a maximum of 40 characters.

Note

Optional message from the requestor providing context and details about the client link invitation.

Suppress Notification

Determines whether or not to send email notification of the client link invitation to the primary user of the client advertiser account. If set to true the client will not receive an email and otherwise, since the default value is false, the client will receive an email notification.

false
Type

Determines whether the link is to a client advertiser account or a client customer.

AccountLink

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 0,
          "Details": "",
          "Message": "No errors occurred."
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 515,
            "Details": "ClientEntityId 144015218 is invalid for this operation.",
            "Message": "The client entity ID is not valid."
          }
        ]
      }
    }
  }
}

Add Offline Conversions Goal​

Creates a new offline conversions goal. | key: addOfflineConversionsGoal

InputNotesExample
Account ID

The identifier of the ad account that owns or is associated with the entities in the request. This header element must have the same value as the AccountId body element when both are required

Connection

The Microsoft Bing Ads connection to use.

Conversion Goal Category

The category that best describes the conversion goal. The category must be a valid Microsoft Advertising category.

Purchase
Scope

Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. When multiple Microsoft Advertising accounts exist, conversions can be tracked across all of them. If associated with one account, conversions will be tracked for that account only.

Status

Defines the possible user-determined status values of a conversion goal. These are the status values that a user can decide to set, for example a goal can be set to Paused to stop tracking conversions for that goal.

Conversion Window In Minutes

The length of time in minutes after a click to track conversions. For example, setting this value to 43200 minutes (30 days) means conversions that happen within 30 days after a click are tracked. Past conversions are not affected. The default value is 43200. The minimum value supported is 1 minute, although a shorter conversion window will reduce the number of conversions recorded. The maximum value supported is 129600 minutes (90 days).

129600
Count Type

Determines how conversions are recorded within the chosen conversion window.

All
Customer ID

The identifier of the manager account (customer) the user is accessing or operating from. A user can have access to multiple manager accounts.

Exclude From Bidding

Determines whether or not to exclude data otherwise related to this conversion goal from a subset of performance report columns.

false
Is Enhanced Conversions Enabled

Determines whether enhanced conversions are enabled for a conversion goal.

false
Is Externally Attributed

When true, the offline conversion goal uses a custom attribution model and allows importing fractional credit for each MSCLKID.

false
Conversion Goal Name

The conversion goal name. The maximum length of the name is 100, and the name must be unique among all conversion goals belonging to the same customer.

My Conversion Goal

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 0,
          "Details": "",
          "Message": "No errors occurred."
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 4803,
            "Details": "The conversion goal name already exists for the given account.",
            "Message": "Duplicate conversion goal name."
          }
        ]
      }
    }
  }
}

Apply Offline Conversions​

Applies offline conversions to a Microsoft Bing Ads account. | key: applyOfflineConversions

InputNotesExample
Customer Account Id

The identifier of the ad account that owns or is associated with the entities in the request. This header element must have the same value as the AccountId body element when both are required

Connection

The Microsoft Bing Ads connection to use.

Customer ID

The identifier of the manager account (customer) the user is accessing or operating from. A user can have access to multiple manager accounts.

Offline Conversions Body

The JSON body that contains the offline conversions to apply to the Bing Ads account.

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 0,
          "Details": "",
          "Message": "No errors occurred."
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 4806,
            "Details": "The offline conversion for click ID ABC123 could not be applied.",
            "Message": "Offline conversion application failed."
          }
        ]
      }
    }
  }
}

Get Account Info​

Gets the identifiers, names, and numbers of accounts that are accessible from the specified customer. | key: getAccountsInfo

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

Customer ID

The identifier of the customer used to get the account information. This request element is optional. If not set, the user's credentials are used to determine the customer.

{
  "data": {
    "AccountsInfo": {
      "AccountInfo": [
        {
          "Id": 156089854,
          "Name": "Contoso Advertising",
          "Number": "F168K7MC",
          "AccountLifeCycleStatus": "Active"
        },
        {
          "Id": 156089912,
          "Name": "Fabrikam Marketing",
          "Number": "F107RHVU",
          "AccountLifeCycleStatus": "Active"
        }
      ]
    }
  }
}

Get Customer​

Gets the details of a customer. | key: getCustomer

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

Customer ID

The identifier of the customer whose information you want to get.

{
  "data": {
    "Customer": {
      "CustomerFinancialStatus": "ClearFinancialStatus",
      "Id": 169592807,
      "Industry": "NA",
      "LastModifiedByUserId": 2,
      "LastModifiedTime": "2022-10-26T13:35:34.957",
      "MarketCountry": "US",
      "ForwardCompatibilityMap": {
        "KeyValuePairOfstringstring": [
          {
            "key": "ManagedByCustomerId",
            "value": 0
          }
        ],
        "MarketLanguage": "English",
        "Name": "Contoso Ltd",
        "ServiceLevel": "SelfServe",
        "CustomerLifeCycleStatus": "Active",
        "TimeStamp": "AAAAADlQGFU=",
        "Number": "F145006C7T",
        "CustomerAddress": {
          "City": "Sioux Falls",
          "CountryCode": "US",
          "Id": 135264702,
          "Line1": "1235 W 12th St",
          "Line2": "Suite 202",
          "PostalCode": 27108,
          "StateOrProvince": "SD",
          "TimeStamp": "AAAAADlQGE4="
        }
      }
    }
  }
}

Get Customers Info​

Gets the identifiers and names of customers that are accessible to the current authenticated user. The results are filtered by customer name. | key: getCustomersInfo

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

Customer Name Filter

A partial or full name of the customers to retrieve. The operation includes the customer in the result if the customer's name begins with the specified filter name. This element is optional. To skip filtering by customer name, set this element to an empty string.

Top Number

A nonzero positive integer that specifies the number of customers to return in the result.

5

{
  "data": {
    "CustomersInfo": {
      "CustomerInfo": [
        {
          "Id": 169592807,
          "Name": "Contoso Ltd"
        },
        {
          "Id": 169593041,
          "Name": "Fabrikam Inc"
        }
      ]
    }
  }
}

Get Linked Accounts And Customers Info​

Gets the customer and account hierarchy under the specified customer. | key: getLinkedAccountsAndCustomersInfo

InputNotesExample
Connection

The Microsoft Bing Ads connection to use.

Customer ID

The identifier of the customer whose hierarchy you want to get.

Only Parent Accounts

Determines whether to return only the advertiser accounts that belong to the customer or to also return linked customers and linked advertiser accounts under other customers. To limit the results to advertiser accounts directly under the specified customer, set this element to true, and otherwise leave it empty or set the property to false. The default value is false.

false

{
  "data": {
    "AccountsInfo": {
      "AccountInfo": [
        {
          "Id": 156089854,
          "Name": "Contoso Advertising",
          "Number": "F168K7MC",
          "AccountLifeCycleStatus": "Active"
        },
        {
          "Id": 156089912,
          "Name": "Fabrikam Marketing",
          "Number": "F107RHVU",
          "AccountLifeCycleStatus": "Active"
        }
      ]
    },
    "CustomersInfo": {
      "CustomerInfo": [
        {
          "Id": 169592807,
          "Name": "Contoso Ltd"
        }
      ]
    }
  }
}

Raw Request​

Sends a raw HTTP request to Microsoft Bing Ads. | key: rawRequest

InputNotesExample
Account ID

The unique identifier for the advertiser account.

Connection

The Microsoft Bing Ads connection to use.

Customer ID

The unique identifier for the customer.

SOAP Action

After selecting the Microsoft Bing API Web Service, the SOAP Action is the method or endpoint to call.

GetCustomer
SOAP Body Request

The required SOAP Body element contains the actual SOAP message intended for the ultimate endpoint of the message. Immediate child elements of the SOAP Body element may be namespace-qualified.

Web Service API

Bing Ads API Version 13 includes the following web service addresses.

CUSTOMER_MANAGEMENT_API

Search Accounts​

Searches for accounts that match the request criteria. | key: searchAccounts

InputNotesExample
Account ID

Use this field to search the Id element of the AdvertiserAccount.

Account Life Cycle Status

Use this field to search the AccountLifeCycleStatus element of the AdvertiserAccount.

Account Name

The name to search for in the Name element of the AdvertiserAccount.

Account Number

The number to search for in the Number element of the AdvertiserAccount.

Connection

The Microsoft Bing Ads connection to use.

Customer ID

Use this field to search the Id element of the Customer.

Ordering

Determines the order of results by the specified property of an account.

User ID

The unique identifier for the user to search for.

{
  "data": {
    "Accounts": {
      "AdvertiserAccount": [
        {
          "BillToCustomerId": 369545927,
          "CurrencyCode": "USD",
          "AccountFinancialStatus": "ClearFinancialStatus",
          "Id": 156089854,
          "Language": "English",
          "LastModifiedByUserId": 3,
          "LastModifiedTime": "2022-10-26T18:6:8.443",
          "Name": "Contoso Advertising",
          "Number": "F168K7MC",
          "ParentCustomerId": 1696874121,
          "PaymentMethodId": 1268789111,
          "PaymentMethodType": "CreditCard",
          "PrimaryUserId": 168125418,
          "AccountLifeCycleStatus": "Active",
          "TimeStamp": "AAAAADlTWUc=",
          "TimeZone": "CentralTimeUSCanada",
          "LinkedAgencies": {
            "CustomerInfo": [
              {
                "Id": 169592807,
                "Name": "Contoso Agency"
              },
              {
                "Id": 169593041,
                "Name": "Fabrikam Partners"
              }
            ]
          },
          "TaxInformation": {
            "KeyValuePairOfstringstring": [
              {
                "key": "ManagedByCustomerId",
                "value": 0
              }
            ]
          },
          "BusinessAddress": {
            "City": "Sioux Falls",
            "CountryCode": "US",
            "Id": 135264777,
            "Line1": "4516 S 50th St",
            "Line2": "Suite 220",
            "PostalCode": 37108,
            "StateOrProvince": "SD",
            "BusinessName": "Contoso Software Inc."
          },
          "AutoTagType": "Inactive"
        }
      ]
    }
  }
}

Searches for the client links for the customer of the current authenticated user, filtered by the search criteria. The operation returns the most recent link for each unique combination of agency customer and client account. | key: searchClientLinks

InputNotesExample
Client Account ID

Search for advertiser account ClientLink objects by the client advertiser account identifier.

Client Customer ID

Search for customer ClientLink objects by the client customer identifier.

Connection

The Microsoft Bing Ads connection to use.

Direct Managing Customer ID

Search for both customer and advertiser account ClientLink objects by the agency's managing customer identifier. If other customers also link to the client customer, the results will not include those client links.

Managing Customer ID

Search for advertiser account ClientLink objects by the agency's managing customer identifier. If other customers also link to the client advertiser account, the results will include those client links. This predicate value is deprecated in favor of the DirectManagingCustomerId predicate.

Ordering

Determines the order of results by the specified property of an account.

{
  "data": {
    "ClientLinks": {
      "ClientLink": [
        {
          "ClientEntityId": 144015218,
          "ClientEntityName": "Contoso Advertising",
          "ClientEntityNumber": "F113T5TB",
          "InviterEmail": "admin@contoso.com",
          "InviterName": "Jane Smith",
          "InviterPhone": "null",
          "IsBillToClient": false,
          "LastModifiedByUserId": 134084676,
          "LastModifiedDateTime": "2022-11-11T15:26:49.357",
          "ManagingCustomerId": 169592807,
          "ManagingCustomerName": "contoso.com",
          "ManagingCustomerNumber": "F145006C7T",
          "Name": "Contoso Agency Link",
          "Note": "null",
          "StartDate": "2022-11-11T15:26:49.24Z",
          "Status": "LinkPending",
          "SuppressNotification": false,
          "Timestamp": "AAAAAAAAAAA=",
          "Type": "AccountLink"
        },
        {
          "ClientEntityId": 138108451,
          "ClientEntityName": "Fabrikam Marketing",
          "ClientEntityNumber": "F107RHVU",
          "InviterEmail": "john.doe@fabrikam.com",
          "InviterName": "John Doe",
          "InviterPhone": "425-555-0100",
          "IsBillToClient": true,
          "LastModifiedByUserId": 134080686,
          "LastModifiedDateTime": "2022-11-10T01:10:11.55",
          "ManagingCustomerId": 169592807,
          "ManagingCustomerName": "fabrikam.com",
          "ManagingCustomerNumber": "F145006C7T",
          "Name": "Fabrikam Client Link",
          "Note": "Agency management link for Q4 campaigns",
          "StartDate": "2022-11-10T01:10:11.423Z",
          "Status": "LinkPending",
          "SuppressNotification": false,
          "Timestamp": "AAAAAAAAAAA=",
          "Type": "AccountLink"
        }
      ]
    }
  }
}

Send User Invitation​

Sends an email invitation for a user to sign up for Microsoft Advertising. The invitation limits account access and permissions. | key: sendUserInvitation

InputNotesExample
Account ID

An array of identifiers of the accounts that the user can manage. To specify that the user can manage all current and future accounts of the customer to which the user belongs, set to NULL.

Connection

The Microsoft Bing Ads connection to use.

Customer ID

The identifier of the customer this user is invited to manage. The AccountIds element determines which customer accounts the user can manage.

Email

The email address corresponding to the user's Microsoft account. The address can contain a maximum of 100 characters.

john.doe@example.com
First Name

The first name of the user. The first name is limited to 40 characters.

John
Last Name

The last name of the user. The last name is limited to 40 characters.

Doe
LCID

The locale to use when sending correspondence to the user by email or postal mail.

EnglishUS
Role ID

The role that the user has for each customer or list of accounts.

{
  "data": {
    "UserInvitationId": 134015178
  }
}

Changelog​

2026-04-14​

Added sandbox environment toggle to the OAuth 2.0 connection for switching between production and sandbox API endpoints

2026-04-10​

Updated example payloads

2025-04-30​

Added global debug and inline data source features for enhanced debugging and data selection capabilities