Client Access

This guide covers client access resources, which allow you to manage client buyers, and associated client users that can directly access the Ad Exchange 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 Ad Exchange Buyer 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

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.

Send an invitation

To invite a new client user to access Ad Exchange 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 Ad Exchange 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":"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 created ClientUserInvitation.

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

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!

Retrieve a list of client user invitations

You can retrieve all outstanding invitations to Ad Exchange 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

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": "user1@domain.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000001",
      "email": "user2@domain.com",
      "clientAccountId": "30000000"
    },
    {
      "invitationId": "10000002",
      "email": "user3@domain.com",
      "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": "user@domain.com",
  "clientAccountId": "30000000"
}

Users

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

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

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": "test_102@example.com"
    }
  ]
}

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": "test_102@example.com"
}

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.

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": "test_102@example.com"
}

Send feedback about...

Buyer REST API
Buyer REST API