Microsoft Bing Ads Component

Manage Microsoft Bing Ad Customer Services

Component key: ms-bing-ads

Description

Microsoft Advertising is a pay-per-click (PPC) advertising platform used to display ads based on the keywords used in a user's search query. For advertisers placing a large number of ads or developers building advertising tools, the Bing Ads API provides programmatic access to Microsoft Advertising.

Using the Bing Ads API is the most efficient way to manage many large campaigns or to integrate your marketing with other in-house systems. Some organizations may choose a hybrid approach; using the web UI for most tasks but automating reporting or campaign optimization with the API.

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

Microsoft documents many frequent asked questions that will aid in troubleshooting.

Connections

OAuth 2.0 Authorization Code

This component uses OAuth 2.0 to connect to the Microsoft Bing Ads API.

To use Bing Ads APIs, you must have a developer token and valid user credentials. If you do not yet have a Microsoft Advertising account, you can sign up via the Microsoft Advertising web application.

You can follow these steps to get a developer token for production.

Sign in with Super Admin credentials at the Microsoft Advertising Developer Portal account tab.
Choose the user that you want associated with the developer token. Typically an application only needs one universal token regardless how many users will be supported.
Click on the Request Token button.

Microsoft Advertising leverages the Microsoft identity platform endpoint for developers 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.

Before your application can authenticate Microsoft Advertising users, you must register your application and get the corresponding client ID and client secret.

Navigate to the Microsoft identity platform for developers in the Azure portal - App registrations page. You can login using either a personal Microsoft Account or a Work or School Account.
Select New registration.
When the Register an application page appears, enter your application's registration information:
- In the Name section, enter a meaningful application name that will be displayed to users of the app, for example My browserless client.
- In the Supported account types section, select Accounts in any organizational directory and personal Microsoft accounts.
Select Register to create the application.
On the app Overview page, find the Application (client) ID value and record it for later. You will use it as the client_id when you request user consent and get an access token.
Select the Add a Redirect URI link and then you should see the Redirect URIs page.
- For web applications, provide the base URL of your application. For Prismatic, use callback url https://oauth2.prismatic.io/callback. Users would use this URL to sign into a web client application.
For web applications, select Certificates & secrets under Manage. Select the New client secret button. Enter a value in Description, select any option for Expires and choose Add. Copy the client secret value before leaving the page. You will use it later as the client_secret to get an access token.

Now that you have a Client ID and Client Secret, add Microsoft Bing Ads step to your integration in Prismatic.

Open the Configuration Wizard Designer by clicking Configuration Wizard, select your Microsoft Bing Ads Connection and enter your client ID and secret.

Input	Default	Notes
Authorize URL string / Required Hidden Field authorizeUrl	https://login.microsoftonline.com/common/oauth2/v2.0/authorize	The OAuth 2.0 Authorization URL for Microsoft Bing Ads
Client ID string / Required clientId
Client Secret Value password / Required clientSecret
Developer Token password / Required developerToken		Developer token of your Account Manager account
Scopes string Hidden Field scopes	https://ads.microsoft.com/msads.manage offline_access	Microsoft Bing Ads permission scopes are set on the OAuth application
Token URL string / Required Hidden Field tokenUrl	https://login.microsoftonline.com/common/oauth2/v2.0/token	The OAuth 2.0 Token URL for Microsoft Bing Ads

Data Sources

Select Account ID

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

Input	Notes
Connection connection / Required connection
Customer ID string customerId

Example Payload for Select Account ID

{
  "result": [
    {
      "key": "17685412",
      "label": "XYZ 1 (id: 17685412)"
    },
    {
      "key": "68745216",
      "label": "XYZ 2 (id: 68745216)"
    },
    {
      "key": "89442154",
      "label": "XYZ 3 (id: 89442154)"
    }
  ]
}

Select Customer ID

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

Input	Notes
Connection connection / Required connection

Example Payload for Select Customer ID

{
  "result": [
    {
      "key": "17685412",
      "label": "XYZ 1 (id: 17685412)"
    },
    {
      "key": "68745216",
      "label": "XYZ 2 (id: 68745216)"
    },
    {
      "key": "89442154",
      "label": "XYZ 3 (id: 89442154)"
    }
  ]
}

Actions

Add Client Link

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

Input	Default	Notes
Client Entity ID string clientEntityId		The identifier of the client advertiser account or client customer to manage.
Connection connection / Required connection
Customer Link Permission string customerLinkPermission		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 string inviterEmail		The email of the user who created the client link request.
Inviter Name string inviterName		The name of the parent customer of the user who created the client link request.
Inviter Phone string inviterPhone		The phone number of the user who created the client link request.
Is Bill To Client boolean isBillToClient	false	Determines whether the owner of the client advertiser account or the managing customer is responsible for billing payments.
Managing Customer ID string / Required managingCustomerId		The identifier of the customer who manages or is requesting to manage the client advertiser account.
Name string name		The friendly name that can be used to reference this client link. The name can contain a maximum of 40 characters.
Note string note		Optional message from the requestor providing context and details about the client link invitation.
Suppress Notification boolean suppressNotification	false	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.
Type string / Required type	AccountLink	Determines whether the link is to a client advertiser account or a client customer.

Example Payload for Add Client Link

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        },
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          },
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          }
        ]
      }
    }
  }
}

Add Offline Conversions Goal

Create a new offline conversions goal. | key: addOfflineConversionsGoal

Input	Default	Notes	Example
Account ID string / Required accountIdInput		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 connection / Required connection
Conversion Goal Category string / Required conversionGoalCategory		The category that best describes the conversion goal. The category must be a valid Microsoft Advertising category.	Purchase
Scope string conversionScope		Determines if the goal applies to all accounts or only the account specified in the required CustomerAccountId header element. If you have multiple Microsoft Advertising accounts, you can track conversions across all of those accounts. If you associate a goal with one account, conversions will be tracked for that account only.
Status string conversionStatus		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 if you no longer wish to track conversions for that goal.
Conversion Window In Minutes string conversionWindowInMinutes		The conversion window is the length of time in minutes after a click that you want to track conversions. If you set this value to 43200 minutes (30 days), then conversions that happen within 30 days after a click are tracked. Past conversions aren't affected. The default value is 43200. The minimum value supported is 1 minute, although keep in mind that a shorter conversion window will reduce the number of conversions your account records. The maximum value supported is 129600 minutes (90 days).	129600
Count Type string countType	All	This determines how your conversions are recorded within your chosen conversion window.
Customer ID string customerIdInput		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 boolean excludeFromBidding	false	Determines whether or not to exclude data otherwise related to this conversion goal from a subset of performance report columns.
Is Enhanced Conversions Enabled boolean isEnhancedConversionsEnabled	false	Determines whether enhanced conversions are enabled for a conversion goal.
Is Externally Attributed boolean isExternallyAttributed	false	This determines if your offline conversion goal uses your own attribution model and allows you to import fractional credit for each MSCLKID.
Conversion Goal Name string / Required 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

Example Payload for Add Offline Conversions Goal

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        },
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          },
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          }
        ]
      }
    }
  }
}

Apply Offline Conversions

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

Input	Notes	Example
Customer Account Id string / Required accountIdInput	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 connection / Required connection
Customer ID string customerIdInput	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 code / Required offlineConversionsBody	The JSON body that contains the offline conversions to apply to the Bing Ads account.

Example Payload for Apply Offline Conversions

{
  "data": {
    "OperationErrors": {
      "OperationError": [
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        },
        {
          "Code": 12345678,
          "Details": "xyz",
          "Message": "some error message"
        }
      ]
    },
    "PartialErrors": {
      "ArrayOfOperationError": {
        "OperationError": [
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          },
          {
            "Code": 12345678,
            "Details": "xyz",
            "Message": "some error message"
          }
        ]
      }
    }
  }
}

Get Account Info

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

Input	Notes
Connection connection / Required connection
Customer ID string customerId	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.

Example Payload for Get Account Info

{
  "data": {
    "AccountsInfo": {
      "AccountInfo": [
        {
          "Id": 12345678,
          "Name": "Account Name 1",
          "Number": "F123456KG",
          "AccountLifeCycleStatus": "Active"
        },
        {
          "Id": 12345678,
          "Name": "Account Name 2",
          "Number": "F123456KG",
          "AccountLifeCycleStatus": "Active"
        }
      ]
    }
  }
}

Get Customer

Gets the details of a customer. | key: getCustomer

Input	Notes
Connection connection / Required connection
Customer ID string / Required customerId	The identifier of the customer whose information you want to get.

Example Payload for Get Customer

{
  "data": {
    "Customer": {
      "CustomerFinancialStatus": "ClearFinancialStatus",
      "Id": 1234567,
      "Industry": "NA",
      "LastModifiedByUserId": 2,
      "LastModifiedTime": "2022-10-26T13:35:34.957",
      "MarketCountry": "US",
      "ForwardCompatibilityMap": {
        "KeyValuePairOfstringstring": [
          {
            "key": "ManagedByCustomerId",
            "value": 0
          }
        ],
        "MarketLanguage": "English",
        "Name": "zyx",
        "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": "fl",
          "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

Input	Default	Notes	Example
Connection connection / Required connection
Customer Name Filter string customerNameFilter		A partial or full name of the customers that you want to get. The operation includes the customer in the result if the customer's name begins with the specified filter name. This request element is optional. If you do not want to filter by customer name, set this element to an empty string.
Top Number string topN	5	A nonzero positive integer that specifies the number of customers to return in the result.	5

Example Payload for Get Customers Info

{
  "data": {
    "CustomersInfo": {
      "CustomerInfo": [
        {
          "Id": 12345678,
          "Name": "xyz inc"
        },
        {
          "Id": 12345689,
          "Name": "xyz inc"
        }
      ]
    }
  }
}

Get Linked Accounts And Customers Info

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

Input	Default	Notes
Connection connection / Required connection
Customer ID string / Required customerId		The identifier of the customer whose hierarchy you want to get.
Only Parent Accounts boolean onlyParentAccounts	false	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.

Example Payload for Get Linked Accounts And Customers Info

{
  "data": {
    "AccountsInfo": {
      "AccountInfo": [
        {
          "Id": 12345678,
          "Name": "Account Name 1",
          "Number": "F123456KG",
          "AccountLifeCycleStatus": "Active"
        },
        {
          "Id": 12345678,
          "Name": "Account Name 2",
          "Number": "F123456KG",
          "AccountLifeCycleStatus": "Active"
        }
      ]
    },
    "CustomersInfo": {
      "CustomerInfo": [
        {
          "Id": 12345678,
          "Name": "xyz inc"
        }
      ]
    }
  }
}

Raw Request

Send raw HTTP request to Bing Ads | key: rawRequest

Input	Default	Notes
Account ID string / Required accountId		Use this field to search the Id element of the AdvertiserAccount.
Connection connection / Required connection
Customer ID string / Required customerId
Soap Action string / Required soapAction		After selecting the Microsoft Bing API Web Service, the Soap Action is the method or endpoint you want call.
Soap Body Request code / Required soapBodyRequest		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 string / Required webService	CUSTOMER_MANAGEMENT_API	Bing Ads API Version 13 includes the following web service addresses.

Search Accounts

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

Input	Notes
Account ID string accountId	Use this field to search the Id element of the AdvertiserAccount.
Account Life Cycle Status string accountLifeCycleStatus	Use this field to search the AccountLifeCycleStatus element of the AdvertiserAccount.
Account Name string accountName	Use this field to search the Name element of the AdvertiserAccount.
Account Number string accountNumber	Use this field to search the Number element of the AdvertiserAccount.
Connection connection / Required connection
Customer ID string customerId	Use this field to search the Id element of the Customer.
Ordering string ordering	Determines the order of results by the specified property of an account.
User ID string userId	Use this field to search the UserId element of the User.

Example Payload for Search Accounts

{
  "data": {
    "Accounts": {
      "AdvertiserAccount": [
        {
          "BillToCustomerId": 369545927,
          "CurrencyCode": "USD",
          "AccountFinancialStatus": "ClearFinancialStatus",
          "Id": 156089854,
          "Language": "English",
          "LastModifiedByUserId": 3,
          "LastModifiedTime": "2022-10-26T18:6:8.443",
          "Name": "XYZ.co",
          "Number": "F168K7MC",
          "ParentCustomerId": 1696874121,
          "PaymentMethodId": 1268789111,
          "PaymentMethodType": "CreditCard",
          "PrimaryUserId": 168125418,
          "AccountLifeCycleStatus": "Active",
          "TimeStamp": "AAAAADlTWUc=",
          "TimeZone": "CentralTimeUSCanada",
          "LinkedAgencies": {
            "CustomerInfo": [
              {
                "Id": 12345678,
                "Name": "xyz inc"
              },
              {
                "Id": 12345689,
                "Name": "xyz inc"
              }
            ]
          },
          "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": "NE",
            "BusinessName": "XYZ Software Inc."
          },
          "AutoTagType": "Inactive"
        }
      ]
    }
  }
}

Search Client Links

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

Input	Notes
Client Account ID string clientAccountId	Search for advertiser account ClientLink objects by the client advertiser account identifier.
Client Customer ID string clientCustomerId	Search for customer ClientLink objects by the client customer identifier.
Connection connection / Required connection
Direct Managing Customer ID string directManagingCustomerId	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 string / Required managingCustomerId	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 string ordering	Determines the order of results by the specified property of an account.

Example Payload for Search Client Links

{
  "data": {
    "ClientLinks": {
      "ClientLink": [
        {
          "ClientEntityId": 144015218,
          "ClientEntityName": "Example - Company",
          "ClientEntityNumber": "F113T5TB",
          "InviterEmail": "example@company.com",
          "InviterName": "Bob",
          "InviterPhone": "null",
          "IsBillToClient": false,
          "LastModifiedByUserId": 134084676,
          "LastModifiedDateTime": "2022-11-11T15:26:49.357",
          "ManagingCustomerId": 169592807,
          "ManagingCustomerName": "company.com",
          "ManagingCustomerNumber": "F145006C7T",
          "Name": "Example Link",
          "Note": "null",
          "StartDate": "2022-11-11T15:26:49.24Z",
          "Status": "LinkPending",
          "SuppressNotification": false,
          "Timestamp": "AAAAAAAAAAA=",
          "Type": "AccountLink"
        },
        {
          "ClientEntityId": 138108451,
          "ClientEntityName": "Test Example 1",
          "ClientEntityNumber": "F107RHVU",
          "InviterEmail": "john@other-example.com",
          "InviterName": "John Doe",
          "InviterPhone": "111-555-1234",
          "IsBillToClient": true,
          "LastModifiedByUserId": 134080686,
          "LastModifiedDateTime": "2022-11-10T01:10:11.55",
          "ManagingCustomerId": 169592807,
          "ManagingCustomerName": "other-example.com",
          "ManagingCustomerNumber": "F145006C7T",
          "Name": "Test Client Link",
          "Note": "This is just a test",
          "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

Input	Default	Notes
Account ID string Value List accountIds		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 connection / Required connection
Customer ID string / Required customerId		The identifier of the customer this user is invited to manage. The AccountIds element determines which customer accounts the user can manage.
Email string / Required email		The email address corresponding to the user's Microsoft account. The address can contain a maximum of 100 characters.
First Name string / Required firstName		The first name of the user. The first name is limited to 40 characters.
Last Name string / Required lastName		The last name of the user. The last name is limited to 40 characters.
Lcid string / Required lcid	EnglishUS	The locale to use when sending correspondence to the user by email or postal mail.
Role Id string / Required roleId		The role that the user has for each customer or list of accounts.

Example Payload for Send User Invitation

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

Manage Microsoft Bing Ad Customer Services

Description​

Connections​

OAuth 2.0 Authorization Code​

Data Sources​

Select Account ID​

Select Customer ID​

Actions​

Add Client Link​

Add Offline Conversions Goal​

Apply Offline Conversions​

Get Account Info​

Get Customer​

Get Customers Info​

Get Linked Accounts And Customers Info​

Raw Request​

Search Accounts​

Search Client Links​

Send User Invitation​