AdvertiserAccount Data Object - Customer Management

Article
03/20/2023

Defines an advertiser account.

Syntax

<xs:complexType name="AdvertiserAccount" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:sequence>
    <xs:element minOccurs="0" name="BillToCustomerId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="CurrencyCode" nillable="true" type="tns:CurrencyCode" />
    <xs:element minOccurs="0" name="AccountFinancialStatus" nillable="true" type="tns:AccountFinancialStatus" />
    <xs:element minOccurs="0" name="Id" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="Language" nillable="true" type="tns:LanguageType" />
    <xs:element minOccurs="0" name="LastModifiedByUserId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="LastModifiedTime" nillable="true" type="xs:dateTime" />
    <xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="Number" nillable="true" type="xs:string" />
    <xs:element minOccurs="0" name="ParentCustomerId" type="xs:long" />
    <xs:element minOccurs="0" name="PaymentMethodId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="PaymentMethodType" nillable="true" type="tns:PaymentMethodType" />
    <xs:element minOccurs="0" name="PrimaryUserId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="AccountLifeCycleStatus" nillable="true" type="tns:AccountLifeCycleStatus" />
    <xs:element minOccurs="0" name="TimeStamp" nillable="true" type="xs:base64Binary" />
    <xs:element minOccurs="0" name="TimeZone" nillable="true" type="tns:TimeZoneType" />
    <xs:element minOccurs="0" name="PauseReason" nillable="true" type="xs:unsignedByte" />
    <xs:element xmlns:q1="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q1:ArrayOfKeyValuePairOfstringstring" />
    <xs:element minOccurs="0" name="LinkedAgencies" nillable="true" type="tns:ArrayOfCustomerInfo" />
    <xs:element minOccurs="0" name="SalesHouseCustomerId" nillable="true" type="xs:long" />
    <xs:element xmlns:q2="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="TaxInformation" nillable="true" type="q2:ArrayOfKeyValuePairOfstringstring" />
    <xs:element minOccurs="0" name="BackUpPaymentInstrumentId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="BillingThresholdAmount" nillable="true" type="xs:decimal" />
    <xs:element minOccurs="0" name="BusinessAddress" nillable="true" type="tns:Address" />
    <xs:element minOccurs="0" name="AutoTagType" nillable="true" type="tns:AutoTagType" />
    <xs:element minOccurs="0" name="SoldToPaymentInstrumentId" nillable="true" type="xs:long" />
    <xs:element minOccurs="0" name="TaxCertificate" nillable="true" type="tns:AccountTaxCertificate">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
    <xs:element minOccurs="0" name="AccountMode" nillable="true" type="xs:string">
      <xs:annotation>
        <xs:appinfo>
          <DefaultValue EmitDefaultValue="false" xmlns="http://schemas.microsoft.com/2003/10/Serialization/" />
        </xs:appinfo>
      </xs:annotation>
    </xs:element>
  </xs:sequence>
</xs:complexType>

Elements

The AdvertiserAccount object has the following elements: AccountFinancialStatus, AccountLifeCycleStatus, AccountMode, AutoTagType, BackUpPaymentInstrumentId, BillingThresholdAmount, BillToCustomerId, BusinessAddress, CurrencyCode, ForwardCompatibilityMap, Id, Language, LastModifiedByUserId, LastModifiedTime, LinkedAgencies, Name, Number, ParentCustomerId, PauseReason, PaymentMethodId, PaymentMethodType, PrimaryUserId, SalesHouseCustomerId, SoldToPaymentInstrumentId, TaxCertificate, TaxInformation, TimeStamp, TimeZone.

Element	Description	Data Type
AccountFinancialStatus	The financial status of the account. For example, the status can indicate whether the account is in good standing or is past due. Add: Read-only Update: Read-only	AccountFinancialStatus
AccountLifeCycleStatus	The status of the account. You cannot set the status of the account. Add: Read-only Update: Read-only	AccountLifeCycleStatus
AccountMode	The account mode distinguishes between smart and expert accounts. The possible values include, but are not limited to: Expert - Expert Mode is the full-feature Microsoft Advertising experience. It gives you more control over campaign management, lets you add more content to your ads, and provides much more in the way of performance reporting and tracking. Smart - Microsoft Advertising will use Microsoft AI to create ads and manage your advertising campaign for you. UnifiedSmart - The account supports advertising across Bing, Google, and Facebook. You can also manage your social network presence on Facebook, Instagram, and LinkedIn. Note: As of April 25, 2023, UnifiedSmart no longer supports Twitter. Most Bing Ads API operations are only supported with Expert accounts. Accounts with any account mode are returned when you request account information e.g., FindAccountsOrCustomersInfo, GetAccount, GetAccountsInfo, GetUser, and SearchAccounts. Add: Read-only for most accounts. Customers in the closed Unified smart campaigns pilot can set the account mode to "UnifiedSmart". Update: Read-only	string
AutoTagType	Determines whether to append or replace the supported UTM tracking codes. Microsoft Advertising can automatically add UTM tags to your destination URL so you can use your website analytics tool, for example Google Analytics, to track how people got to your website. Auto-tags are applied for example to expanded text ads, keywords, Microsoft Shopping Campaigns, and Sitelink Extensions. For details about auto-tagging, please see the Microsoft Advertising help article How do I add UTM tags to my landing page URL?. Add: Optional. If not specified the default value is Inactive. Update: Optional. If no value is set for the update, this setting is not changed.	AutoTagType
BackUpPaymentInstrumentId	The identifier of a backup payment instrument to use to settle the account. This element is not applicable for invoiced accounts. Add: Read-only Update: Optional. If no value is set for the update, this setting is not changed.	long
BillingThresholdAmount	A customer specified amount for settling against the selected payment instrument. Add: Read-only Update: Optional. If no value is set for the update, this setting is not changed.	decimal
BillToCustomerId	The identifier of the customer that is billed for the charges that the account generates. This is either the aggregator that manages this account on behalf of the owner or the identifier of the customer that owns the account. The service sets the identifier based on the owner of the payment instrument identified in the PaymentMethodId element. Add: Read-only Update: Read-only	long
BusinessAddress	The location where your business is legally registered. If you are an agency working as an agent for your customer, this is the location where your client is legally registered. If you are an agency working as an aggregator, this is the legally registered business address of your company. The business address is used to determine your tax requirements. Add: Required. The Address BusinessName, City, and Line1 elements are required for all countries or regions. For Brazil (BR) and India (IN), the PostalCode and StateOrProvince elements are also required. Update: Optional for accounts that are not billed by monthly invoice. Having said that, if you want to make any changes to the Address then you must set its BusinessName, City, CountryCode, Line1, and StateOrProvince elements (where applicable); Read-only for monthly invoice accounts. To update the BusinessAddress of an invoice account, contact your account manager or support.	Address
CurrencyCode	The ISO code for the currency that is used to settle the account. The service uses the currency information for billing purposes. Add: Required Update: Read-only	CurrencyCode
ForwardCompatibilityMap	The list of key and value strings for forward compatibility to avoid otherwise breaking changes when new elements are added in the current API version. Forward compatibility changes will be noted here in future releases. There are currently no forward compatibility changes for this object.	KeyValuePairOfstringstring array
Id	The system-generated identifier of the account. This is the identifier that you set the AccountId element and CustomerAccountId SOAP header to in many of the campaign requests. Add: Read-only Update: Required	long
Language	The language used to render the billing documents that you receive from Microsoft Advertising (if you use an invoice as your payment method). This setting is only for billing documents for this account, and doesn't apply to other Microsoft Advertising accounts you might have. If you leave this empty when signing up a customer, the operation uses the language value from the Lcid element of the primary user. If the Lcid is set to a value such as FrenchCanada, then the account language is set to French. Add: Read-only for AddAccount; Required for SignupCustomer if the UserInvitation is set, and otherwise this element is Optional. Update: Optional. If no value is set for the update, this setting is not changed.	LanguageType
LastModifiedByUserId	The identifier of the last user to update the account's information. Add: Read-only Update: Read-only	long
LastModifiedTime	The date and time that the account was last updated. The value is in Coordinated Universal Time (UTC). The date and time value reflects the date and time at the server, not the client. For information about the format of the date and time, see the dateTime entry in Primitive XML Data Types. Add: Read-only Update: Read-only	dateTime
LinkedAgencies	The list of agencies linked to this account. Currently only one agency customer is supported when you add the account. When you retrieve the account all linked agency customer info will be included. Add: Optional for AddAccount; Optional for SignupCustomer if the agency customer is in the Create Accounts on Behalf of Client pilot (GetCustomerPilotFeatures returns 793). Aggregators cannot link as agencies in this context, and therefore cannot set this element. Update: Read-only	CustomerInfo array
Name	The name of the account. The string can contain between 3 and 100 characters and must be unique among all account names within the customer. Add: Required Update: Required	string
Number	The system-generated account number that is used to identify the account in the Microsoft Advertising web application. The account number has the form xxxxxxxx, where xxxxxxxx is a series of any eight alphanumeric characters. Add: Read-only Update: Read-only	string
ParentCustomerId	The identifier of the customer that owns the account. In the campaign requests that require a customer identifier, this is the identifier that you set the CustomerId SOAP header to. Add: Required for AddAccount; Required for SignupCustomer if the UserInvitation is not set, and otherwise this element is ignored. Update: Read-only	long
PauseReason	A flag value that indicates who paused the account. The following are the possible values: 1 - The user paused the account. 2 - The billing service paused the account. 4 - The user and billing service paused the account. Add: Read-only Update: Read-only	unsignedByte
PaymentMethodId	The identifier of the payment instrument to use to settle the account. Add: Optional for AddAccount; Read-only for SignupCustomer if the UserInvitation is not set. When you call SignupCustomer set this element to NULL. The service picks up the payment method identifier associated with the aggregator customer's invoice automatically. For SignupCustomer if the UserInvitation is set, and if the new client account is being linked to an agency via LinkedAgencies, and if the agency should be billed, set this element to the agency's payment instrument ID. Otherwise you should leave this element null. Update: Optional. If no value is set for the update, this setting is not changed.	long
PaymentMethodType	The type of payment instrument to use to settle the account. You do not have to set this value because the type is determined by the payment instrument corresponding to the PaymentMethodId element. When you call the GetAccount and SearchAccounts to get the account data, PaymentMethodType is set to NULL, and you cannot determine the payment method that the account uses. Reserved for internal use. Add: Read-only Update: Read-only	PaymentMethodType
PrimaryUserId	The identifier of the account manager who is primarily responsible for managing this account. Only Super Admin and Standard users can be set as the primary contact for an account. Add: For AddAccount if the new client account is being linked to an agency via LinkedAgencies, then you can assign one of the agency users as primary user for the new account. When you call SignupCustomer as an aggregator without including the UserInvitation, you should leave this element empty and the primary user will be set to the aggregator user identifier. When you call SignupCustomer and the UserInvitation is included, you can leave this element empty and the primary user will be set to the identifier of the new client user who accepts the invitation. When you call SignupCustomer and if the UserInvitation is set, and if the new client account is being linked to an agency via LinkedAgencies, then you can assign one of the agency users as primary user for the new account. Update: Optional. If no value is set for the update, this setting is not changed.	long
SalesHouseCustomerId	The identifier of the third party that is responsible for a sales lead. Add: Read-only Update: Read-only	long
SoldToPaymentInstrumentId	The identifier of the payment instrument of your client (the sold-to customer) to use to settle the account. Add: Required for AddAccount if the BillToCustomerId differs from the ParentCustomerId; Read-only and not applicable for SignupCustomer. Update: Optional. If no value is set for the update, this setting is not changed.	long
TaxCertificate	The account tax certificate data object.	AccountTaxCertificate
TaxInformation	For a list of valid key and value strings for this element, see AdvertiserAccount TaxInformation in the section below. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. To remove a key and value pair, set the key and then set the value to an empty string ("").	KeyValuePairOfstringstring array
TimeStamp	The time-stamp value that the system uses internally to reconcile updates when you call the UpdateAccount and DeleteAccount operations. Add: Read-only Update: Required	base64Binary
TimeZone	The default time-zone value to use for campaigns in this account. If you do not specify a value when the account is added, the time zone will be set to PacificTimeUSCanadaTijuana by default. This time-zone value is used by the Microsoft Advertising web application to display the account time zone preference, and does not provide a default time-zone value for campaigns that are created by using the Bulk or Campaign Management API. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.	TimeZoneType

Remarks

AdvertiserAccount TaxInformation

The following is the list of keys that are available for the TaxInformation element of an AdvertiserAccount.

Note

Microsoft Advertising cannot provide guidance on tax or VAT. Please contact your tax advisor or local tax office if you have questions.

TaxInformation Key	Description	Countries or Regions
AUGSTNumber	The tax identifier for accounts in Australia. Without a tax identifier, taxes might apply based on your BusinessAddress location. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.	Australia
CCM	The municipal registration number, or Cadastro de contribuinte mobiliario (CCM), of the legal entity. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed.	Brazil
CNPJ	The tax identifier for business accounts in Brazil. Without a tax identifier, taxes might apply based on your BusinessAddress location. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.	Brazil
CPF	The tax identifier for personal accounts in Brazil. Without a tax identifier, taxes might apply based on your BusinessAddress location. Add: Required Update: Optional. If no value is set for the update, this setting is not changed.	Brazil
GSTINNumber	This ID starts with two numbers representing the state code in which the business is registered followed by a maximum of 13 numbers and letters. Add: Optional Update: Optional	India
GSTNumber	In Singapore, billing is managed by Microsoft Ireland Operations Ltd., in Ireland. Effective January 1, 2020, Microsoft Advertising is required to charge the Singapore Goods and Services Tax (SG GST) for businesses registered in Singapore. If you provide your SG GST registration number, Microsoft Advertising will apply SG GST at 0%. If you do not provide your SG GST registration number, Microsoft Advertising is required to charge 7% SG GST. (Note: tax rate is subject to change.) Possible GSTNumber formats include: two alpha-numeric characters followed by an optional dash followed by seven digits followed by an optional dash followed by one alpha-numeric character; OR eight or nine digits followed by one alpha-numeric character; OR T or S followed by two digits followed by one capitalized letter A - Z followed by one alpha-numeric character followed by four digits followed by one alpha-numeric character. GSTNumber examples: ab-1234567-a; ab1234567-a; ab1234567a; ab-1234567a; 12345678a; 123456789a; T12Aa1234a Add: Optional Update: Optional	Singapore
IsIVAOrVATTaxPayer	The value is either TRUE or FALSE, which is used for the tax determination. Add: Required Update: Required	Chile
IsWithholdingTaxExempted	The value is either TRUE or FALSE, which is used for the tax determination. Add: Required Update: Required	Chile
NZGSTNumber	This is an 8 or 9 Digit long tax ID. Without the NZGSTNumber taxes might apply based on your business location. Add: Optional Update: Read-only	New Zealand
PanNumber	The PAN number. Add: Required Update: Read-only	India
VATNumber	The account's Value Added Tax (VAT) registration number (also known as VAT identifier). The VAT number must be valid in the country or region that you specified in the BusinessAddress element. Without a VAT registration number or exemption certificate, taxes might apply based on your business location. Add: Optional Update: Optional	Please see VAT number format per country/region for details.

VAT number format per country or region

This table lists VAT registration number formats per country or region.

VAT number	Country/region
Starts with 2 letters that are specific to each country/region, followed by a maximum of 12 digits or letters.	Austria, Belgium, Bulgaria, Cyprus, Czech Republic, Germany, Denmark, Estonia, Greece, Finland, France, United Kingdom, Croatia, Hungary, Ireland, Italy, Lithuania, Luxembourg, Latvia, Malta, Monaco, The Netherlands, Poland, Portugal, Romania, Spain, Sweden, Slovenia, and Slovakia.
Must be in the following format: XXXXXXXX-X or XXXXXXXX-K, where X represents 8 digits followed by a trailing digit.	Chile
Must be in the following format: HUXXXXXXXX (where HU is followed by 8 digits).	Hungary
Must be in the following format: LIXXXXX or XXXXX (where both formats are supported and LI is optional, and the number of digits is 5).	Liechtenstein
Must be in the following format: XXXXXXXX-0001 (where 8 digits preceed -0001).	Nigeria
Must be in the following format: PTXXXXXXXXX (where PT is followed by 9 digits).	Portugal
9 or 13 digits in length, of which the first 8 or 12 digits are the actual ID number, and the last digit is a checksum digit calculated according to ISO 7064, MOD 11-10.	Serbia
CHE + 9 numeric digits + TVA, MWST, or IVA (ex. CHE-123.456.788 TVA). The last digit is a MOD11 checksum digit built with the weighting pattern: 5,4,3,2,7,6,5,4.	Switzerland
Must be in the following format: 13 digits in length.	Thailand

Requirements

Service: CustomerManagementService.svc v13
Namespace: https://bingads.microsoft.com/Customer/v13/Entities

Used By

AddAccount
GetAccount
SearchAccounts
SignupCustomer
UpdateAccount

Share via