Management Model for Agencies
An agency builds a Bing Ads API application for their company to manage the campaigns of their advertising clients. Agencies may manage some or all aspects of an advertiser account. When sending the invitation to manage a client account, the agency may specify whether the client or agency is responsible for billing. For more information about becoming an agency, see the help article Managing your clients as an agency with Microsoft Advertising or Resources for agency partners.
The client account must be set up for post-pay billing. Prepaid accounts are not supported for management by agencies.
Agency Entity Model
The following figure shows two clients managed by an agency.
Only an agency Super Admin can Link to Client Accounts. Linking enables any agency Super Admin to access the specified client account. If the client has multiple accounts, then a client link invitation must be sent for each client account. The super admin may also determine which individual accounts the advertiser campaign manager and viewer users can access. In the figure above User A has access to account A1, and User B has access to accounts A2, B1, and B2. For more information about user roles, see User Roles and Available Service Operations.
Link to Client Accounts
Linking to client accounts as an agency is not supported in the sandbox environment.
To manage client accounts, a Super Admin user of the agency must send an invitation to the client, which must then be accepted by a Super Admin user of the client. To determine whether a link already exists, call the SearchClientLinks operation and check the Status element of any returned ClientLink. For a list of possible status values, see ClientLinkStatus value set. To search by individual account, set the predicate field to ClientAccountId and set the predicate value to the account identifier that you want to find. There is no set limit to the amount of client accounts that can be linked to an agency.
If a link exists with status either Active, LinkAccepted, LinkInProgress, LinkPending, UnlinkInProgress, or UnlinkPending, the agency may not initiate a duplicate client link.
If a client link to the specified account does not yet exist, or if the lifecycle of an existing link had ended with status of Expired, LinkCanceled, LinkDeclined, LinkFailed, or Inactive, then the agency may initiate a new client link invitation by calling the AddClientLinks operation. The service transitions client link status to LinkPending immediately.
The agency may specify whether the client or agency is responsible for billing by setting the IsBillToClient element in the service request. If not otherwise specified, the agency will be billed.
To update a client link, the TimeStamp element is required for validation, so you must first call the SearchClientLinks operation to get the existing ClientLink object. Then modify the Status element of the returned ClientLink, and include the updated ClientLink object in a subsequent call to the UpdateClientLinks operation.
The client may only use the UpdateClientLinks operation to update the status as LinkAccepted or LinkDeclined.
The client may accept or decline through an application built on the Bing Ads API, or through the Accounts & Billing tab in the Microsoft Advertising web application. In either case the client credentials must be used to accept or decline. For more information, see the Microsoft Advertising help article Getting started as an agency with Microsoft Advertising.
If the client sets the status to LinkDeclined, the client link lifecycle ends. You may not update a declined client link, and you must send a new invitation to manage the client account. If the client sets the status to LinkAccepted, the status transitions to LinkInProgress. If the link process succeeds, the service updates the client link status to Active.
If the link process fails, possibly due to a billing transition error, the service updates the client link status to LinkFailed. You may not update a failed client link, and you must send a new invitation to manage the client account.
If the client or agency does not take action within 30 days, the service sets the status to LinkExpired and the client link lifecycle ends. You may not update an expired client link, and you must send a new invitation to manage the client account.
If the client link status is LinkPending, the agency may choose to cancel a prior link request. If the client link status is Active, the agency may choose to initiate the unlink process, which would terminate the existing relationship with the client.
To initiate the unlink process, the agency sets the client link status to UnlinkRequested and calls the UpdateClientLinks operation. Updating the status with UnlinkRequested effectively sets the status to UnlinkInProgress. The service transitions client link status to UnlinkPending immediately, and then waits for system resources to proceed. The state should transition quickly to UnlinkInProgress.
If the unlink process fails, possibly due to a billing transition error, the client link resumes to Active status. If the unlink process succeeds the status will update to Inactive, and the client link lifecycle ends. You may not update an inactive client link, and you must send a new invitation to manage the client account.
For code examples that show how to add and update a client link invitation, see Client Links Code Example.