Client Access

This guide covers client access resources, which allow you to manage client buyers, and associated client users that can directly access the Authorized Buyers Marketplace to view, negotiate, and approve deals. These resources allow you to programmatically perform operations that you can do manually in the Clients section of the Authorized Buyers Account Settings tab.

Clients

A Client represents one of your client buyers, and must be associated with a known advertiser, brand, or agency. You can associate multiple clients with an entity, so long as each has a unique name.

Retrieve a list of clients

You can retrieve all client buyers associated with a given account by sending an HTTP GET request to the accounts.clients resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients
Authorization: Bearer access token here

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the client buyer data. You can use a returned ID to obtain information for a specific client, update a specific client, or manage client users as described in the following sections.

{
  "clients": [
    {
      "clientAccountId": "30000001",
      "accountId": "1000002",
      "role": "CLIENT_DEAL_APPROVER",
      "status": "ACTIVE",
      "visibleToSeller": true,
      "entityType": "ADVERTISER",
      "entityId": "3",
      "entityName": "Great Company"
    },
    {
      "clientAccountId": "30000000",
      "accountId": "1000002",
      "role": "CLIENT_DEAL_NEGOTIATOR",
      "status": "ACTIVE",
      "visibleToSeller": true,
      "entityType": "BRAND",
      "entityId": "4",
      "entityName": "Top Brand"
    }
  ]
}

Create a new client buyer

To create a new client buyer, send a POST request to the accounts.clients resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients

Note: Each client buyer must be associated with a known business entity—an advertiser, brand, or agency. Specify the type of the business entity in the entityType property. Specify the ID of the business entity in the entityId property. Lists of all known advertisers, brands, and agencies with their identifiers can be found in the advertisers.txt, brands.txt, and agencies.txt files respectively.

Request

Here's an example of a POST request that creates a new client resource:

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients
Authorization: Bearer access token here
Content-Type: application/json

{
  "role": "CLIENT_DEAL_APPROVER",
  "status": "ACTIVE",
  "visibleToSeller": true,
  "entityId": 2,
  "entityType": "AGENCY",
  "clientName": "Test"
}

Response

If the request succeeds, the server responds with a 200 OK status code and the full representation of the created client resource.

{
  "clientAccountId": "30000004",
  "accountId": "1000002",
  "role": "CLIENT_DEAL_APPROVER",
  "status": "ACTIVE",
  "clientName": "Test",
  "visibleToSeller": true,
  "entityType": "ADVERTISER",
  "entityId": "2",
  "entityName": "Effective Agency"
}

Get a specific client buyer

You can retrieve information for a specific client buyer by sending an HTTP GET request to the accounts.clients resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000001
Authorization: Bearer access token here

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the client's data:

{
  "clientAccountId": "30000001",
  "accountId": "1000002",
  "role": "CLIENT_DEAL_NEGOTIATOR",
  "status": "ACTIVE",
  "visibleToSeller": true,
  "entityType": "ADVERTISER",
  "entityId": "4",
  "entityName": "Disney"
}

Update a client buyer

To update and fully replace an existing client buyer resource, follow these steps:

1. Retrieve the resource you want to update.
2. Modify the properties you want to change.
3. Send a PUT request to the accounts.clients resource URI and supply the modified resource as the message body.

The URI for the client resource has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId

Note: The clientAccountId and entityName properties are read-only. Updates to these fields are ignored.

Note: An accountId specified in the request body will be ignored. To specify the account of the sponsor buyer, the API will use the value specified in the accountId path variable instead.

Request

Here's an example of a PUT request (the final step above) that updates and fully replaces an account resource:

PUT https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000003
Authorization: Bearer access token here
Content-Type: application/json

{
  "visibleToSeller": true,
  "status": "DISABLED",
  "role": "CLIENT_DEAL_NEGOTIATOR",
  "entityId": 3,
  "entityType": "ADVERTISER"
}

Response

If the request succeeds, the server responds with a 200 OK status code and the full representation of the modified client resource.

{
  "clientAccountId": "30000003",
  "accountId": "1000002",
  "role": "CLIENT_DEAL_NEGOTIATOR",
  "status": "DISABLED",
  "visibleToSeller": true,
  "entityType": "ADVERTISER",
  "entityId": "3",
  "entityName": "Microsoft"
}

Invitations

A ClientUserInvitation represents an invitation sent to a given email address for a prospective client user. If accepted, the invitation is removed and an associated ClientUser is created.

Note: You cannot currently modify or delete an existing invitation. Resending an existing invitation is currently not supported through the API. You can manually resend an invitation from the Clients section of the Authorized Buyers Account Settings tab.

Send an invitation

To invite a new client user to access Authorized Buyers Marketplace, send a POST request to the accounts.clients.invitations resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/invitations

The invitation will contain a name of the account the user is invited to access, a brief description of the access role, and a link to accept the invitation and access the Authorized Buyers UI.

Request

Here's an example of a POST request that creates a new ClientUserInvitation and sends an invitation to the specified email address:

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000000/invitations
Authorization: Bearer access token here
Content-Type: application/json

{
  "email":"[e-mail]"
}

Response

If the request succeeds and an email invitation has been sent, the server responds with a 200 OK status code and the created ClientUserInvitation.

{
  "invitationId": "10000002",
  "email": "[e-mail]",
  "clientAccountId": "30000000"
}

Note: You can only invite a given user to access the Authorized Buyers Marketplace through the same client once. If you try to invite a user that has already been invited to access the Authorized Buyers Marketplace through the same client, you will get a 409 Conflict HTTP status code.

Note: The API server checks to ensure that the invited user has a well-formed email, but does not verify that an email actually exists or whether an invitation is delivered.

Invitation email example

Hello [e-mail],

You are invited to access the Authorized Buyers Marketplace using Sample Bidder’s account. This invitation offers you View only access for deals, which lets you view available products and publisher profiles in the marketplace and limited access to debugging and reporting tools.

To accept and begin using Authorized Buyers, click the button below. You will be prompted to sign in with a Google account, which you can quickly create with an existing Gmail account, or any other email address and password. Once you complete your account setup, you can access Authorized Buyers directly at www.google.com/authorizedbuyers.

ACCEPT INVITATION

Your access is managed by the terms that govern Authorized Buyers. For additional information or help using Authorized Buyers, visit the Authorized Buyers help center.

Welcome to Authorized Buyers!

Retrieve a list of client user invitations

You can retrieve all outstanding invitations to Authorized Buyers Marketplace for a given client by sending an HTTP GET request to the accounts.clients.invitations resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/invitations

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000000/invitations
Authorization: Bearer access token here

Note: The request above retrieves invitations for a specific client, but you can retrieve invitations for all clients by specifying "-" as the clientAccountId path variable.

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and a list of invitations for the specified client.

{
  "invitations": [
    {
      "invitationId": "10000000",
      "email": "[e-mail]",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000001",
      "email": "[e-mail]",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000002",
      "email": "[e-mail]",
      "clientAccountId": "30000000"
    }
  ]
}

Get a specific user invitation

You can retrieve information about a specific user invitation by sending an HTTP GET request to the accounts.clients.invitations resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/invitations/invitationId

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000000/invitations/10000002
Authorization: Bearer access token here

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the invitation data:

{
  "invitationId": "10000002",
  "email": "[e-mail]",
  "clientAccountId": "30000000"
}

Users

A ClientUser represents a user who can access the Authorized Buyers Marketplace UI on behalf of a Client while logged in to their Google account. Each Authorized Buyers account can have multiple clients, and each client can have multiple client users who are authorized to access the Authorized Buyers Marketplace UI.

Note: You cannot create a client user directly. A ClientUser is created when a ClientUserInvitation is accepted by the owner of the invited email address.

Retrieve list of client users

You can retrieve a list of all client users of a given client by sending an HTTP GET request to the accounts.clients.users resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/users

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000001/users
Authorization: Bearer access token here

Note: The request above retrieves users for a specific client, but you can retrieve invitations across all clients by specifying "-" as the clientAccountId path variable.

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and a list of client users. You can use a returned ID to obtain information about a specific user, disable a user, or re-enable a user, as described in the following sections.

{
  "users": [
    {
      "userId": "1000006",
      "clientAccountId": "30000001",
      "status": "ACTIVE",
      "email": "[e-mail]"
    }
  ]
}

Get information about a specific client user

You can retrieve information about a specific client user by sending an HTTP GET request to the accounts.clients.users resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/users/userId

Request

Here's an example:

GET https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000001/users/1000006 HTTP/1.1
Authorization: Bearer access token here

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and the client user data:

{
  "userId": "1000006",
  "clientAccountId": "30000001",
  "status": "ACTIVE",
  "email": "[e-mail]"
}

Disable or re-enable a client user

To disable a client user, send a PUT request to the accounts.clients.users resource URI and set the status property to DISABLED. To re-enable a client user, send a PUT request to the resource URI and set the status property to ACTIVE.

Note: Only the status property of the client user resource can be updated. Updates to the userId, email, and clientAccountId properties are ignored.

The URI for the client user resource has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/accountId/clients/clientAccountId/users/userId

Request

Here's an example of a PUT request that disables a client user:

PUT https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000001/users/1000006
Authorization: Bearer access token here
Content-Type: application/json

{
  status: "DISABLED"
}

Response

If the request succeeds, the server responds with a 200 OK status code and the modified client user resource.

{
  "userId": "1000006",
  "clientAccountId": "30000001",
  "status": "DISABLED",
  "email": "[e-mail]"
}