ClientLink Data Object - Customer Management
Defines a client link object. Acceptance of a client link invitation enables an agency to manage the corresponding client advertiser accounts. To send an invitation to manage a client advertiser account, call the AddClientLinks operation and specify one client link per account to manage.
A client link does not have a public system identifier. You can identify distinct client links by ClientEntityId and ManagingCustomerId.
Tip
For more information about the client link lifecycle, see the Account Hierarchy technical guide. For more information about becoming an agency, see the Resources for agency partners. For more information from a client's perspective, see How to have an agency manage your Microsoft Advertising account.
Note
Agency customers in the Create Accounts on Behalf of Client pilot (GetCustomerPilotFeatures returns 793) can also establish ad account level client links via the SignupCustomer service operation. Please see SignupCustomer for more information.
Syntax
<xs:complexType name="ClientLink" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:sequence>
<xs:element minOccurs="0" name="Type" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="ClientEntityId" nillable="true" type="xs:long" />
<xs:element minOccurs="0" name="ClientEntityNumber" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="ClientEntityName" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="ManagingCustomerId" nillable="true" type="xs:long" />
<xs:element minOccurs="0" name="ManagingCustomerNumber" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="ManagingCustomerName" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Note" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="Name" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="InviterEmail" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="InviterName" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="InviterPhone" nillable="true" type="xs:string" />
<xs:element minOccurs="0" name="IsBillToClient" nillable="true" type="xs:boolean" />
<xs:element minOccurs="0" name="StartDate" nillable="true" type="xs:dateTime" />
<xs:element minOccurs="0" name="Status" nillable="true" type="tns:ClientLinkStatus" />
<xs:element minOccurs="0" name="SuppressNotification" type="xs:boolean" />
<xs:element minOccurs="0" name="LastModifiedDateTime" type="xs:dateTime" />
<xs:element minOccurs="0" name="LastModifiedByUserId" type="xs:long" />
<xs:element minOccurs="0" name="Timestamp" nillable="true" type="xs:base64Binary" />
<xs:element xmlns:q10="http://schemas.datacontract.org/2004/07/System.Collections.Generic" minOccurs="0" name="ForwardCompatibilityMap" nillable="true" type="q10:ArrayOfKeyValuePairOfstringstring" />
<xs:element minOccurs="0" name="CustomerLinkPermission" nillable="true" type="xs:string" />
</xs:sequence>
</xs:complexType>
Elements
The ClientLink object has the following elements: ClientEntityId, ClientEntityName, ClientEntityNumber, CustomerLinkPermission, ForwardCompatibilityMap, InviterEmail, InviterName, InviterPhone, IsBillToClient, LastModifiedByUserId, LastModifiedDateTime, ManagingCustomerId, ManagingCustomerName, ManagingCustomerNumber, Name, Note, StartDate, Status, SuppressNotification, Timestamp, Type.
| Element | Description | Data Type |
|---|---|---|
| ClientEntityId | The identifier of the client advertiser account or client customer to manage The Type element determines whether the link is to a client advertiser account or a client customer. Add: Required. Either the ClientEntityId or ClientEntityNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required. |
long |
| ClientEntityName | The name of the client advertiser account or client customer to manage The Type element determines whether the link is to a client advertiser account or a client customer. Add: Read-only Update: Read-only |
string |
| ClientEntityNumber | The number of the client advertiser account or client customer to manage The Type element determines whether the link is to a client advertiser account or a client customer. Add: Required. Either the ClientEntityId or ClientEntityNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required. |
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. If this field is set to "Administrative", the user has access to the ClientEntityId through an Administrative customer link. If this field is set to "Standard", the user has access to the ClientEntityId through a Standard customer link. The ClientEntityId is part of a customer link hierarchy whereby the user can access other customers below it. For more information, see the User Roles technical guide. Add: Optional Update: Read-only |
string |
| 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 the ClientLink object. |
KeyValuePairOfstringstring array |
| InviterEmail | The email of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the email already stored in Microsoft Advertising for the current authenticated user. If not specified, the service will set this value to the email already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only |
string |
| InviterName | The name of the parent customer of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the customer name already stored in Microsoft Advertising. If not specified, the service will set this value to the parent customer name already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only |
string |
| InviterPhone | The phone number of the user who created the client link request. This value does not need to be the same as, nor is it used to modify, the phone number already stored in Microsoft Advertising for the current authenticated user. If not specified, the service will set this value to the phone number already stored in Microsoft Advertising for the current authenticated user. Add: Optional Update: Read-only |
string |
| IsBillToClient | Determines whether the owner of the client advertiser account or the managing customer is responsible for billing payments. This element is only applicable for advertiser account client links, and not applicable for customer links. The client advertiser account must be set up for post-pay billing. Prepaid accounts are not supported for management by agencies. If set to true the client is responsible for billing. If set to false the managing customer is responsible for billing. Add: Required for advertiser account links; Not applicable for customer links. Update: Read-only |
boolean |
| LastModifiedByUserId | The identifier of the last user to update the client link's information. Add: Read-only Update: Read-only |
long |
| LastModifiedDateTime | The date and time that the client link 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 |
| ManagingCustomerId | The identifier of the customer who manages or is requesting to manage the client advertiser account. Add: Required. Either the ManagingCustomerId or ManagingCustomerNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required |
long |
| ManagingCustomerName | The name of the customer who manages or is requesting to manage the client advertiser account. Add: Read-only Update: Read-only |
string |
| ManagingCustomerNumber | The number of the customer who manages or is requesting to manage the client advertiser account. Add: Required. Either the ManagingCustomerId or ManagingCustomerNumber is required, but specifying both will cause the operation to fail. Update: Read-only and Required |
string |
| Name | The friendly name that can be used to reference this client link. The name can contain a maximum of 40 characters. A default name will be provided if none is specified. The name does not need to be unique compared to other client links for the user. Add: Optional Update: Read-only |
string |
| Note | Optional message from the requestor providing context and details about the client link invitation. Add: Optional Update: Optional. If no value is set for the update, this setting is not changed. |
string |
| StartDate | The date when the status would update. For an accepted link request the status would transition towards Active on this date, and for an unlink request the status would transition towards Inactive on this date. If not specified, this value will be set to the current date and time. Add: Optional Update: Read-only |
dateTime |
| Status | Determines the life cycle status of the client link, for example whether the client link has been accepted or declined. When adding a client link this element cannot be specified, and the service sets the effective status to LinkPending. Add: Read-only Update: Required |
ClientLinkStatus |
| SuppressNotification | 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. Add: Optional Update: Read-only |
boolean |
| Timestamp | Reserved for future use. | base64Binary |
| Type | Determines whether the link is to a client advertiser account or a client customer. The possible values are AccountLink and CustomerLink. If this element is empty or set to AccountLink, the ClientEntityId, ClientEntityName, and ClientEntityNumber represent a client advertiser account. If this element is set to CustomerLink, the ClientEntityId, ClientEntityName, and ClientEntityNumber represent a client customer. Add: Optional. If this element is not set, the service attempts to create an advertiser account client link. Update: Read-only |
string |
Requirements
Service: CustomerManagementService.svc v13
Namespace: https://bingads.microsoft.com/Customer/v13/Entities