Client Access

This guide covers client access resources for client buyers, client users, and client invitations.

Client buyers

Each instance of the client resource represents one of your client buyers. The client resource provides methods to perform the following operations:

Retrieve a list of client buyers for an account

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

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

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "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"
    }
  ]
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.Client;
import com.google.api.services.adexchangebuyer.v2beta1.model.ListClientsResponse;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …

  private static final String APPLICATION_NAME = "api-client";
  private static final String ADVERTISER = "ADVERTISER";
  private static final String CLIENT_DEAL_NEGOTIATOR = "CLIENT_DEAL_NEGOTIATOR";
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public List<Client> listClients(long accountId) throws IOException {
    ListClientsResponse response = api.accounts().clients().list(accountId).execute();
    return response.getClients();
  }

  …
  public static void main(String[] args) throws GeneralSecurityException, IOException {

    JsonFactory jsonFactory = new JacksonFactory();

    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

    Credential oAuth2Credential;
    // Create credentials using JSON credential file.
    try (FileInputStream credentialStream = new FileInputStream(args[0])) {
      oAuth2Credential = GoogleCredential
          .fromStream(credentialStream)
          .createScoped(AdExchangeBuyerIIScopes.all());
    } catch (Exception ex) {
      throw new RuntimeException("Unable to create a credential", ex);
    }

    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client =
        new AdExchangeBuyerII.Builder(httpTransport, jsonFactory, oAuth2Credential)
            .setApplicationName(APPLICATION_NAME)
            .build();
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    List<Client> clientBuyers = example.listClients(accountId);
    System.out.println("List of clients:" + clientBuyers);
  }
}

Create a new client buyer

In order to create a new client buyer, send a POST request to the client resource URI, which has the following format:

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

Note: Each client buyer needs to be associated with a known business entity—an advertiser, a brand, or an agency. Specify the type of the business entity in the entityType property. Specify the ID of the business entity in the entityId property. The list of all known advertisers with their identifiers is available in the advertisers.txt file. The list of all known brands with their identifiers is available in the brands.txt file. The list of all known agencies with their identifiers is available in the agencies.txt file.

Request

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

POST https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients HTTP/1.1
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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

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

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.Client;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private static final String APPLICATION_NAME = "api-client";
  private static final String ADVERTISER = "ADVERTISER";
  private static final String CLIENT_DEAL_NEGOTIATOR = "CLIENT_DEAL_NEGOTIATOR";
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public Client createSampleAdvertiserClient(long accountId) throws IOException {
    Client client = new Client()
        .setClientName("Enterprise Inc. " + new Random().nextInt(1000000))
        .setEntityId(1L)
        .setEntityType(ADVERTISER)
        .setRole(CLIENT_DEAL_NEGOTIATOR)
        .setVisibleToSeller(true);
    return api.accounts().clients().create(accountId, client).execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {

    JsonFactory jsonFactory = new JacksonFactory();

    HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();

    Credential oAuth2Credential;
    // Create credentials using JSON credential file.
    try (FileInputStream credentialStream = new FileInputStream(args[0])) {
      oAuth2Credential = GoogleCredential
          .fromStream(credentialStream)
          .createScoped(AdExchangeBuyerIIScopes.all());
    } catch (Exception ex) {
      throw new RuntimeException("Unable to create a credential", ex);
    }

    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client =
        new AdExchangeBuyerII.Builder(httpTransport, jsonFactory, oAuth2Credential)
            .setApplicationName(APPLICATION_NAME)
            .build();
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    Client createdClient = example.createSampleAdvertiserClient(accountId);
    System.out.println("Created a client: " + createdClient);
    clientBuyers = example.listClients(accountId);
    System.out.println("List of clients: " + clientBuyers);
  }
}

Get a specific client buyer

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

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

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

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.Client;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public Client getClient(long accountId, long clientAccountId) throws IOException {
    return api.accounts().clients().get(accountId, clientAccountId).execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    Client clientBuyer = example.getClient(accountId, clientAccountId);
    System.out.println(clientBuyer);
  }
}

Update a client buyer

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

  1. Retrieve the resource that you want to update.
  2. Modify the properties you want to change.
  3. Send a PUT request to the 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/account_id/clients/client_account_id

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

Note: The accountId field, if specified as part of the request body, is ignored. In order to specify the account identifier of the sponsor buyer, use the account_id path variable instead.

Request

Here is 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 HTTP/1.1
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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

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

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.Client;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public Client disableClient(long accountId, final long clientAccountId) throws IOException {
    Client client = api.accounts().clients().get(accountId, clientAccountId).execute();
    return api
        .accounts()
        .clients()
        .update(accountId, clientAccountId, client.setStatus(DISABLED))
        .execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    Client disabledClient = example.disableClient(accountId, createdClient.getClientAccountId());
    System.out.println("Disabled client: " + disabledClient);
    clientBuyers = example.listClients(accountId);
    System.out.println("Modified list of clients: " + clientBuyers);
  }
}

Client Users and Invitations

This section covers both the client user resource and the client user invitation resource. A client user resource represents a user who can access the Ad Exchange Marketplace on behalf of a client buyer. A client user invitation resource represents an outstanding email invitation to access the Marketplace that can be accepted by a user. Each sponsor buyer account can have multiple client buyers, and each client buyer can have multiple users who are authorized to access the Ad Exchange Marketplace.

Once a user accepts an invitation, the associated client user invitation resource is no longer available; an active client user resource with a different identifier is created instead.

Client user invitation resource

The client user invitation resource provides methods to perform the following operations:

Note: You cannot currently modify or delete an existing invitation. Resending outstanding invitations is currently not supported via the API methods. You can manually resend an outstanding invitation from the Clients section of the Ad Exchange Buyer Account Settings tab.

Invite a new client user

In order to invite a new client user to access Ad Exchange Marketplace, send a POST request to the client user invitation resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/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 Ad Exchange UI.

Invitation email example

Hello user@example.com,

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

To accept and begin using Ad Exchange, 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 Ad Exchange directly at www.google.com/adx.

ACCEPT INVITATION


Your access is managed by the terms that govern DoubleClick Ad Exchange. For additional information or help using Ad Exchange, visit support.google.com/adxbuyer.

Welcome to DoubleClick Ad Exchange!

Note: You can only invite a given user to access the Ad Exchange Marketplace via the same client once. If you try to invite a user that has already been invited to access the Ad Exchange Marketplace via 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 and an invitation is delivered.

Request

Here is an example of a POST request that creates a new client user invitation resource (sends an invitation to a new client user):

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

{
  "email":"user@domain.com"
}

Response

If the request succeeds and an email invitation has been sent, the server responds with a 200 OK status code and the full representation of the created user invitation resource.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "invitationId": "10000002",
  "email": "user@domain.com",
  "clientAccountId": "30000000"
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUserInvitation;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public ClientUserInvitation inviteUser(long accountId, long clientAccountId, String email)
      throws IOException {
    return api
        .accounts()
        .clients()
        .invitations()
        .create(accountId, clientAccountId, new ClientUserInvitation().setEmail(email))
        .execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    ClientUserInvitation createdInvitation =
        example.inviteUser(accountId, clientAccountId, email);
    System.out.println("Created an invitation: " + createdInvitation);
    List<ClientUserInvitation> invitations =
      example.listInvitations(accountId, clientAccountId);
    System.out.println("Outstanding invitations: " + invitations);
  }
}

Retrieve a list of outstanding user invitations for a given client buyer

You can retrieve all outstanding invitations to Ad Exchange Marketplace for a given client buyer by sending an HTTP GET request to the client user invitation resource URI, which has the following format:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/invitations

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "invitations": [
    {
      "invitationId": "10000000",
      "email": "user1@domain.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000001",
      "email": "user2@domain.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000002",
      "email": "user3@domain.com",
      "clientAccountId": "30000000"
    }
  ]
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUserInvitation;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …

  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public List<ClientUserInvitation> listInvitations(long accountId, long clientAccountId)
      throws IOException {
    return api
        .accounts()
        .clients()
        .invitations()
        .list(accountId, String.valueOf(clientAccountId))
        .execute()
        .getInvitations();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {

    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    List<ClientUserInvitation> invitations =
        example.listInvitations(accountId, clientAccountId);
    System.out.println("Outstanding invitations: " + invitations);
  }
}

Retrieve a list of all outstanding user invitations for all clients

You can retrieve a list of all outstanding user invitations for all clients of a given account by sending an HTTP GET request to the client user invitations resource URI and passing - as the client_account_id path variable:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/-/invitations

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "invitations": [
    {
      "invitationId": "10000003",
      "email": "user1@advertiser.com",
      "clientAccountId": "30000001"
    },
    {
      "invitationId": "10000004",
      "email": "user2@advertiser.com",
      "clientAccountId": "30000001"
    },
    {
      "invitationId": "10000000",
      "email": "user1@brand.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000001",
      "email": "user2@brand.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000002",
      "email": "user3@brand.com",
      "clientAccountId": "30000000"
    }
  ]
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUserInvitation;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private static final String ALL_CLIENTS = "-";
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public List<ClientUserInvitation> listAccountInvitations(long accountId)
      throws IOException {
    return api
        .accounts()
        .clients()
        .invitations()
        .list(accountId, ALL_CLIENTS)
        .execute()
        .getInvitations();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    List<ClientUserInvitation> invitations = example.listAccountInvitations(accountId);
    System.out.println("Outstanding invitations for all clients: " + invitations);
  }
}

Get a specific user invitation

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

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/invitations/invitation_id

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "invitationId": "10000002",
  "email": "user@domain.com",
  "clientAccountId": "30000000"
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUserInvitation;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public ClientUserInvitation getInvitation(
      long accountId, long clientAccountId, long invitationId) throws IOException {
    return api
        .accounts()
        .clients()
        .invitations()
        .get(accountId, clientAccountId, invitationId)
        .execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    long invitationId = Long.parseLong(args[3]);
    System.out.println("Invitation: " +
        example.getInvitation(
            accountId,
            clientAccountId,
            invitationId));
  }
}

Client user resource

The client user resource provides methods to perform the following operations:

Note: You cannot create a client user directly. You can grant access to the Ad Exchange Marketplace to a user of a client buyer by inviting that user (that is, creating a new client user invitation resource), and having the user accept the invitation.

Retrieve a list of users of a given client

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

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/users

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

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.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "users": [
    {
      "userId": "1000006",
      "clientAccountId": "30000001",
      "status": "ACTIVE",
      "email": "test_102@example.com"
    }
  ]
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUser;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public List<ClientUser> listUsers(long accountId, long clientAccountId)
      throws IOException {
    return api
        .accounts()
        .clients()
        .users()
        .list(accountId, String.valueOf(clientAccountId))
        .execute()
        .getUsers();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {

    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    List<ClientUser> clientUsers = example.listUsers(accountId, clientAccountId);
    System.out.println("Users of a client: " + clientUsers);
  }
}

Retrieve a list of users for all clients

You can retrieve a list of all the users of all clients of a given account by sending an HTTP GET request to the client user resource URI and passing - as the client_account_id path variable:

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/-/users

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

If the request succeeds, the server responds with a 200 OK HTTP status code and a list of users of all the clients.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "users": [
    {
      "userId": "1000006",
      "clientAccountId": "30000001",
      "status": "ACTIVE",
      "email": "test_102@example.com"
    },
    {
      "userId": "1000005",
      "clientAccountId": "30000000",
      "status": "DISABLED",
      "email": "test_101@example.com"
    }
  ]
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUser;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private static final String ALL_CLIENTS = "-";
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public List<ClientUser> listAccountUsers(long accountId)
      throws IOException {
    return api
        .accounts()
        .clients()
        .users()
        .list(accountId, ALL_CLIENTS)
        .execute()
        .getUsers();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    // Use the credentials to create a client for the API service.
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    List<ClientUser> allUsers = example.listAccountUsers(accountId);
    System.out.println("All client users: " + allUsers);
  }
}

Get information about a specific user

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

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/users/user_id

Request

Here is an example:

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

You can obtain an access token by following the steps in the Authorization guide.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "userId": "1000006",
  "clientAccountId": "30000001",
  "status": "ACTIVE",
  "email": "test_102@example.com"
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUser;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public ClientUser getUser(
      long accountId, long clientAccountId, long userId) throws IOException {
    return api
        .accounts()
        .clients()
        .users()
        .get(accountId, clientAccountId, userId)
        .execute();
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    long userId = Long.parseLong(args[3]);
    ClientUser user = example.getUser(accountId, clientAccountId, userId);
    System.out.println("Retrieved user: " + user);
  }
}

Disable or re-enable a client user

To disable a client user, send a PUT request to the 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 clientAccountIdproperties are ignored.

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

https://adexchangebuyer.googleapis.com/v2beta1/accounts/account_id/clients/client_account_id/users/user_id

Request

Here is an example of a PUT request that disables a user:

PUT https://adexchangebuyer.googleapis.com/v2beta1/accounts/1000002/clients/30000001/users/1000006 HTTP/1.1
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 full representation of the modified client user resource.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "userId": "1000006",
  "clientAccountId": "30000001",
  "status": "DISABLED",
  "email": "test_102@example.com"
}

Code samples

Java

import com.google.api.client.auth.oauth2.Credential;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerII;
import com.google.api.services.adexchangebuyer.v2beta1.AdExchangeBuyerIIScopes;
import com.google.api.services.adexchangebuyer.v2beta1.model.ClientUser;
import com.google.common.base.Predicate;
import com.google.common.collect.Iterables;

import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.List;
import java.util.Random;

public class ClientAccessApiExample {
  …
  private static final String DISABLED = "DISABLED";
  private static final String ACTIVE = "ACTIVE";
  private final AdExchangeBuyerII api;

  public ClientAccessApiExample(AdExchangeBuyerII api) {
    this.api = api;
  }

  public ClientUser disableUser(
      long accountId, long clientAccountId, long userId) throws IOException {
    return updateUserStatus(accountId, clientAccountId, userId, DISABLED);
  }

  public ClientUser enableUser(
      long accountId, long clientAccountId, long userId) throws IOException {
    return updateUserStatus(accountId, clientAccountId, userId, ACTIVE);
  }
  …

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    AdExchangeBuyerII client = …
    ClientAccessApiExample example = new ClientAccessApiExample(client);
    long accountId = Long.parseLong(args[1]);
    long clientAccountId = Long.parseLong(args[2]);
    long userId = Long.parseLong(args[3]);
    ClientUser disabledUser = example.disableUser(accountId, clientAccountId, userId);
    System.out.println("Disabled user: " + disabledUser);
    ClientUser enabledUser = example.enableUser(accountId, clientAccountId, userId);
    System.out.println("Enabled user: " + enabledUser);
  }
}

Send feedback about...

Buyer REST API
Buyer REST API