Edit

Share via

ClientLink Data Object - Customer Management

  • Article

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

Used By

AddClientLinks
SearchClientLinks
UpdateClientLinks