Google Apps Provisioning API (Deprecated)

Notice
The Google Apps Provisioning API has been officially deprecated as of May 15, 2013. It has been replaced by the Admin SDK’s Directory API. The Google Apps Provisioning API will continue to work as per our Deprecation Policy.

Google Apps Provisioning API

Google Apps allows website administrators to offer their users co-branded versions of a variety of personalized Google applications, such as Gmail. This document describes the Google Apps Provisioning API, which enables application developers to programmatically enable access to these applications. Specifically, the API provides functions for creating, retrieving, updating and deleting user accounts with one or more domains, nicknames, email aliases, organization units, and groups.

This version of the Provisioning API follows the principles of the Google Data APIs. Google Data APIs are based on both the Atom 1.0 and RSS 2.0 syndication formats in addition to the Atom Publishing Protocol. Learn more about Google Data APIs.

(Provisioning API version 1.0 is no longer in service. All customers must upgrade to version 2.0 of the API.)

  1. Using the Provisioning API
  2. Getting Started
    1. Creating an Administrator account
    2. Enabling the Provisioning API
  3. Managing User Accounts
    1. Creating a User Account
    2. Retrieving User Accounts
    3. Retrieving all Users in a Domain
    4. Retrieving a List of 100 Users
    5. Updating a User Account
    6. Suspending a User Account
    7. Restoring a User Account
    8. Deleting a User Account
  4. Managing Nicknames
    1. Sample NicknameEntry Request
    2. Sample NicknameFeed Response
    3. Creating a Nickname
    4. Retrieving a Nickname
    5. Retrieving all Nicknames for a User Account
    6. Retrieving all Nicknames in a Domain
    7. Retrieving List of 100 Nicknames
    8. Deleting a Nickname
  5. Methods for Groups
    1. Creating a Group
    2. Retrieving a Group
    3. Updating a Group
    4. Retrieving all Groups for a Member
    5. Retrieving all Groups in a Domain
    6. Deleting a Group
  6. Methods for Group Members
    1. Adding a Member to a Group
    2. Retrieving all Members of a Group
    3. Deleting a Member from an Group
  1. Methods for Group Owners
    1. Assigning an Owner to a Group
    2. Querying for all Owners of a Group
    3. Querying if a User or Group is Owner
    4. Deleting an Owner from a Group
  2. Managing Users in Multiple Domains
    1. Creating a User for a Domain
    2. Updating a Domain User's Account
    3. Renaming a User's Account
    4. Retrieving Users
    5. Deleting a User from a Domain
  3. Managing User Aliases in Multiple Domains
    1. Creating a User Alias in a Domain
    2. Retrieving User Aliases
    3. Deleting a User Alias from a Domain
  4. Managing Organization Units
    1. Retrieving a customerId
    2. Creating an Organization Unit
    3. Updating an Organization Unit
    4. Retrieving Organization Units
    5. Deleting an Organization Unit
  5. Managing Organization Users
    1. Creating an Organization User
    2. Updating an Organization User
    3. Retrieving Organization Users
    4. Deleting an Organization User
  6. Methods for Handling Errors
    1. Identifying Errors in API Responses

Using the Provisioning API

The following subsections explain how to use the Google Apps Provisioning API. Each subsection explains the methods available for accessing specific provisioning functionality with the supported client libraries or directly through HTTP requests. For help getting started with your chosen client library, see the corresponding Google Data Protocol article.

Getting Started

Before you can start using the Provisioning API, you'll need to create an administrator account for Google Apps. You'll also need to explicitly enable the Provisioning API in the administrative control panel.

Creating an Administrator account

To set up Google Apps, you will need to create a Google account that will serve as an admin account for your domain. You can use an existing Google account. However, since the owner of the account will have the ability to create, update and delete user accounts for your domain, we recommend that you consider creating a new Google account for your domain rather than using someone's personal Google account.

The following steps explain how you would set up Google Apps.

  1. Go to the home page for Google Apps and follow the instructions to sign up for Google Apps for Business (for your enterprise) or Google Apps for Education (for your school).
  2. Enter your domain name or indicate that you would like to purchase a new domain. If you purchase a new domain, you will need to complete the registration forms for the new domain before proceeding to the next step.
  3. Complete the form to provide information about your organization and yourself to Google.
  4. On the following page, complete the form indicating the number of user accounts you would like to purchase and then accept the terms and conditions.
  5. Complete the signup process using Google Checkout.
  6. Complete the form to set up your admin account.
  7. Follow the instructions to verify that you own your domain.
  8. Use the email address and password or two-step access code for your admin account to request an authentication token for your domain. The authentication token will be submitted in each API request that you send to Google, and Google will use the authentication token to authorize the execution of those API requests.

Enabling the Provisioning API

Before using the Provisioning API, you need to explicitly enable it in the domain control panel. The multiple domain users and user aliases feeds along with the organization unit and organization user feeds require your control panel to be Next generation. The exact steps to enable the API are slightly different between current and Next generation panels:

To enable the Provisioning API for a Next generation control panel

  1. Log in to your admin account and select Domain settings.
  2. Select the User settings tab.
  3. Select the checkbox enabling the Provisioning API, and save your changes.

To enable the Provisioning API for a current control panel

  1. Log in to your admin account and select the Users and groups tab.
  2. Select the the Settings subtab.
  3. Select the checkbox to enable the Provisioning API and save your changes.

You will need to complete the steps for setting up Google Apps before you can log in to your admin account.

Follow the appropriate Getting Started article to install the necessary software for compiling programs which use Google Data APIs (including the Provisioningt API).

Managing User Accounts

Creating a User Account

All create and update requests require you to submit the information needed to fulfill the request. If you are using client libraries, they convert the data objects from your chosen language into GData XML objects. To view GData XML examples that illustrate data objects and required information, check the tabbed sections for Protocol.

Protocol

To create a user account, use the following `POST` request:
POST https://apps-apis.google.com/a/feeds/domain/user/2.0
The following XML shows a sample request to create a user. This XML could also be used to update a user account. In addition, the ability to set the user's disk space quota using the <apps:quota> is no longer available. Setting a custom quota, different than 25600MB, has no effect. All fields that are set by you are shown in bold text. Note: This XML format contains all of the data that can be stored in a user entry object in the client libraries.
<?xml version="1.0" encoding="UTF-8"?>
<atom:entry
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:apps="http://schemas.google.com/apps/2006">
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<apps:login
userName="SusanJones-1321"
password="51eea05d46317fadd5cad6787a8f562be90b4446"
hashFunctionName="SHA-1" suspended="false"/>
<apps:quota limit="25600"/>
<apps:name familyName="Jones"
givenName="Susan"/>
</atom:entry>
Even though requests to create and update user accounts use the same XML format, these requests are different in several ways.
  • In a request to create a user, the <apps:name> tag and its attributes – `familyName` and `givenName` – are required. However, a request to update a user does not need to include this tag or its attributes unless the request is updating the user's given name or family name.
  • In a request to create a user, the <apps:login> tag is required, and the request must provide values for the `username` and `password` attributes. The `username` has to be unique and cannot be a nickname of another user. A request to update a user does not need to include the <apps:login> tag. In addition, the request should not provide a value for the <apps:login> tag's `password` attribute unless the user's password is being updated. As a recommended option, send the `password` value as a base 16-encoded hash value. Set the `hashFunctionName` attribute to either the SHA-1 or MD5 hash format.
  • Typically, the `suspended` attribute of the <apps:login> tag only appears in update requests. (By default, newly created accounts are active.)
This method takes the following arguments:
  • The `userName` argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
  • The `givenName` argument contains the user's first name.
  • The `familyName` argument contains the user's last name.
  • The `password` argument contains the password for the user account.
  • The `hashFunctionName` argument specifies the hash format of the password parameter.
  • The `limit` argument identifies the amount of disk space in MB that will be allocated to the user account.

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.createUser(String username, String givenName, String familyName, String password)
client.createUser(String username, String givenName, String familyName, String password, Integer quotaLimitInMb)
client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction)
client.createUser(String username, String givenName, String familyName, String password, String passwordHashFunction, Integer quotaLimitInMb)
This method takes the following arguments:
  • The `username` argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
  • The `givenName` argument contains the user's first name.
  • The `familyName` argument contains the user's last name.
  • The `password` argument contains the password for the user account.
  • The `passwordHashFunction` argument specifies the hash format of the password parameter.
  • The `quotaLimitInMb` argument identifies the amount of disk space in MB that will be allocated to the user account.

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.CreateUser(user_name, family_name, given_name, password, suspended=False, admin=None, quota_limit=None, password_hash_function=None, change_password=None)
This method takes the following arguments:
  • The `user_name` argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
  • The `family_name` argument contains the user's last name.
  • The `given_name` argument contains the user's first name.
  • The `password` argument contains the password for the user account.
  • The `suspended` argument specified whether the user account should be suspended.
  • The `admin` argument specified whether the user account should have administrator privileges.
  • The `quota_limit` argument identifies the amount of disk space in MB that will be allocated to the user account.
  • The `password_hash_function` argument specifies the hash format of the password parameter.
  • The `change_password` argument specifies whether the user is forced to change password at the next login.

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.CreateUser(String username, String givenName, String familyName, String password)
service.CreateUser(String username, String givenName, String familyName, String password, int quotaLimitInMb)
service.CreateUser(String username, String givenName, String familyName, String password, String passwordHashFunction)
service.CreateUser(String username, String givenName, String familyName, String password, String passwordHashFunction, int quotaLimitInMb)
This method takes the following arguments:
  • The `username` argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
  • The `givenName` argument contains the user's first name.
  • The `familyName` argument contains the user's last name.
  • The `password` argument contains the password for the user account.
  • The `passwordHashFunction` argument specifies the hash format of the password parameter.
  • The `quotaLimitInMb` argument identifies the amount of disk space in MB that will be allocated to the user account.

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->createUser($username, $givenName, $familyName, $password, $passwordHashFunction=null, $quota=null);
This method takes the following arguments:
  • The `username` argument contains the unique name that identifies the account owner and cannot be a nickname of another user.
  • The `givenName` argument contains the user's first name.
  • The `familyName` argument contains the user's last name.
  • The `password` argument contains the password for the user account.
  • The `passwordHashFunction` argument specifies the hash format of the password parameter.
  • The `quota` argument identifies the amount of disk space in MB that will be allocated to the user account.

The method returns a user entry response given in Protocol that is converted to user entry object by the libraries.

Retrieving User Accounts

Protocol

To retrieve a specific user account, use the following `GET` request:

GET https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.retrieveUser(String username)

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.RetrieveUser(user_name)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.RetrieveUser(String username)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->retrieveUser($username);

The only argument that you need to pass to the method is the username associated with the account that you wish to retrieve.

The method returns a user entry Response that is converted to user entry object by the libraries.

Retrieving all Users in a Domain

Protocol

To retrieve all of the users in a domain, use the following `GET` request:
GET https://apps-apis.google.com/a/feeds/domain/user/2.0

Sample UserFeed Response

The Provisioning API returns an Atom XML feed containing a list of users, each of which is identified in an <atom:entry> XML block. The XML below shows a sample API response for a request to retrieve all users for a domain.
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:apps="http://schemas.google.com/apps/2006"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
xmlns:gd="http://schemas.google.com/g/2005">
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/user/2.0
</atom:id>
<atom:updated>1970-01-01T00:00:00.000Z&
lt;/atom:updated>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">Users</atom:title>
<atom:link rel="next"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0?startUsername=
john"/>
<atom:link
rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<atom:link
rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<openSearch:startIndex>1</
openSearch:startIndex>
<atom:entry>
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones
</atom:id>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">SusanJones</atom:title>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<atom:link rel="edit"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<gd:who
rel="http://schemas.google.com/apps/2006#user.recipient"
email="SusanJones@example.com"/>
<apps:login userName="SusanJones"
suspended="false" admin="false" changePasswordAtNextLogin="false"
agreedToTerms="true"/>
<apps:quota limit="25600"/>
<apps:name familyName="Jones"
givenName="Susan"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.nicknames"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=
SusanJones"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.emailLists"
href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/?recipient=
SusanJones@example.com"/>
</atom:entry>
<atom:entry>
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith
</atom:id>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">JohnSmith</atom:title>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
<atom:link rel="edit"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/JohnSmith"/>
<gd:who
rel="http://schemas.google.com/apps/2006#user.recipient"
email="JohnSmith@example.com"/>
<apps:login userName="JohnSmith"
suspended="false" admin="false" changePasswordAtNextLogin="false"
agreedToTerms="true"/>
<apps:quota limit="25600"/>
<apps:name familyName="Smith"
givenName="John"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.nicknames"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=
JohnSmith"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.group"
href="https://apps-apis.google.com/a/feeds/group/example.com/2.0?recipient=
JohnSmith@example.com"/>
</atom:entry>
</atom:feed>

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.retrieveAllUsers()

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.RetrieveAllUsers()

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.RetrieveAllUsers()

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->retrieveAllUsers();

Retrieving a List of 100 Users

This method allows you to control the size of your result set when you request all of the users in your domain. As discussed in the Results Pagination section, the client libraries offers methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

Protocol

To retrieve a list of 100 users in your domain, use the following `GET` request:
GET https://apps-apis.google.com/a/feeds/domain/user/2.0
The maximum number of users returned in a UserFeed Response is 100 by default.

Sample UserFeed Response

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:apps="http://schemas.google.com/apps/2006"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
xmlns:gd="http://schemas.google.com/g/2005">
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/user/2.0
</atom:id>
<atom:updated>1970-01-01T00:00:00.000Z&
lt;/atom:updated>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">Users</atom:title>
<atom:link rel="next"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0?startUsername=
john"/>
<atom:link
rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<atom:link
rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0"/>
<openSearch:startIndex>1</
openSearch:startIndex>
<atom:entry>
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones
</atom:id>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">SusanJones</atom:title>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<atom:link rel="edit"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<gd:who
rel="http://schemas.google.com/apps/2006#user.recipient"
email="SusanJones@example.com"/>
<apps:login userName="SusanJones"
suspended="false" admin="false" changePasswordAtNextLogin="false"
agreedToTerms="true"/>
<apps:quota limit="25600"/>
<apps:name familyName="Jones"
givenName="Susan"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.nicknames"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=
SusanJones"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.emailLists"
href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/?recipient=
SusanJones@example.com"/>
</atom:entry>
<atom:entry>
 ...
</atom:entry>
 ...
</atom:feed>

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.retrievePageOfUsers(String startUsername)
This method returns a UserFeed XML response, which the Java client library converts to a `UserFeed` object.

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.RetrievePageOfUsers(start_username=None)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.RetrievePageOfUsers(String startUsername)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->retrievePageOfUsers($startUsername=null);

The only argument that you need to pass to the method is the first username that should appear in your result set. Usernames are ordered case-insensitively by ASCII value.

Updating a User Account

Protocol

To update a user account, use the following `PUT` request:
PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
To rename a user, `PUT` request is made with the updated user name in the XML entry as follows:
PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Sample User Entry Request

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry
xmlns:atom="http://www.w3.org/2005/Atom"
 xmlns:apps="http://schemas.google.com/apps/2006">
 <atom:category
scheme="http://schemas.google.com/g/2005#kind"
 term="http://schemas.google.com/apps/2006#user"/>
 <apps:login
userName="NewUserName"
password="51eea05d46317fadd5cad6787a8f562be90b4446" hashFunctionName="SHA-1"
suspended="false"/>
</atom:entry>

Sample User Entry Response

Whether you create, retrieve or update a user account, the Provisioning API returns an Atom XML response in the same format. The XML below shows a sample API response for modifying user account information. The client libraries convert this XML into a `UserEntry` object.
<?xml version="1.0" encoding="UTF-8"?>
<atom:entry
xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:apps="http://schemas.google.com/apps/2006"
xmlns:gd="http://schemas.google.com/g/2005">
<atom:id>https://apps-apis.google.com/a/
feeds/example.com/user/2.0/SusanJones</atom:id>
<atom:updated>1970-01-01T00:00:00.000Z&
lt;/atom:updated>
<atom:category
scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#user"/>
<atom:title
type="text">SusanJones</atom:title>
<atom:link rel="self"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<atom:link rel="edit"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/SusanJones"/>
<apps:login userName="SusanJones"
suspended="false" admin="false" changePasswordAtNextLogin="false"
agreedToTerms="true"/>
<apps:name familyName="Jones"
givenName="Susan"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.nicknames"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=
Susy-1321"/>
<gd:feedLink
rel="http://schemas.google.com/apps/2006#user.groups"
href="https://apps-apis.google.com/a/feeds//group/2.0/?recipient=us-
sales@example.com"/>
</atom:entry>
Note: For users with multiple domains, a `nickname` uses the same domain as the user's primary email address.

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.updateUser(String username, UserEntry userEntry)

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.UpdateUser(user_name, user_entry)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.UpdateUser(UserEntry userEntry)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->updateUser($username, $userEntry);

The common use case for this method will be to retrieve a user account, modify the user entry object that contains information about that account, and then submit the modified object to the UpdateUser method.

The method returns user entry XML response which the libraries convert to a user entry object.

To rename the user, update the user entry object with the new username and then invoke service.UpdateUser(UserEntry userEntry). Before renaming a user, it is recommended that you logout the user from all browser sessions and services. For instance, you can get the user on your support desk telephone line during the rename process to ensure they have logged out. The process of renaming can take up to 10 minutes to propagate across all services.

Suspending a User Account

Protocol

To suspend a user account using the protocol, change the user's `suspended` value to `true` and make a `PUT` request with the updated entry.

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.suspendUser(String username)

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
user_entry = client.RetrieveUser(user_name)
user_entry.login.suspended = True
client.UpdateUser(user_name, user_entry)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.SuspendUser(String username)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->suspendUser($username);

The only argument that you need to pass to the method is the name of the user whose account you wish to suspend. This method returns a user entry XML response, which the client libraries convert to a user entry object.

Restoring a User Account

Protocol

To restore a user account using the protocol, change a suspended user's `suspended` value to `false` and make a `PUT` request with the updated entry.

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.restoreUser(String username)

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
user_entry = client.RetrieveUser(user_name)
user_entry.login.suspended = False
client.UpdateUser(user_name, user_entry)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.RestoreUser(String username)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->restoreUser($username);

The only argument that you need to pass to the method is the name of the user whose account you wish to restore. This method returns a user entry XML response, which the client libraries converts to a user entry object.

Deleting a User Account

Important things to consider before deleting a user:

  • The deleted user will no longer be able to login.
  • For more information about account deletion, please refer to this guide.

Protocol

To delete a user account, use the following `DELETE` request:
DELETE
https://apps-apis.google.com/a/feeds/domain/user/2.0/userName

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.deleteUser(String username)

Python

import gdata.apps.client
...
client = gdata.apps.client.AppsClient(domain=domain)
client.ClientLogin(email=email, password=password, source='apps')
client.DeleteUser(user_name)

.NET

using Google.GData.Apps;
...
AppsService service = new AppsService(domain, email, password);
service.DeleteUser(String username)

PHP

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
Zend_Loader::loadClass('Zend_Gdata_Gapps');
...
$client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
$gdata = new Zend_Gdata_Gapps($client, 'example.com');
$gdata->deleteUser($username);

The only argument that you need to pass to the method is the name of the user whose account you wish to delete.

Managing Nicknames

Sample NicknameEntry Request

The following XML shows a sample request to create a nickname. The XML uses the <apps:nickname> tag to specify the nickname and the <apps:login> tag to identify the user who is assigned the nickname. The fields that are set by the partner are shown in bold text.

<?xml version="1.0" encoding="UTF-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:apps="http://schemas.google.com/apps/2006">
<atom:category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#nickname"/>
<apps:nickname name="Susy-1321"/>
<apps:login userName="SusanJones-1321"/>
</atom:entry>

Sample NicknameFeed Response

When you submit a request to retrieve all nicknames for a domain or all nicknames assigned to a particular user, the Provisioning API returns an Atom XML feed containing a list of nicknames, each of which is identified in an <atom:entry> XML block. The client libraries translate this feed into a NicknameFeed object, which contains a series of NicknameEntry objects.

The XML below shows a sample API response for a request to retrieve all nicknames for the username SusanJones.

<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
xmlns:apps="http://schemas.google.com/apps/2006">
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/nickname/2.0
</atom:id>
<atom:updated>1970-01-01T00:00:00.000Z</atom:updated>
<atom:category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#nickname"/>
<atom:title type="text">Nicknames for user SusanJones</atom:title>
<atom:link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/>
<atom:link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0"/>
<atom:link rel="self" type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0?username=SusanJones"/>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>2</openSearch:itemsPerPage>
<atom:entry>
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy
</atom:id>
<atom:category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#nickname"/>
<atom:title type="text">susy</atom:title>
<atom:link rel="self" type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/>
<atom:link rel="edit" type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/susy"/>
<apps:nickname name="susy"/>
<apps:login userName="SusanJones"/>
</atom:entry>
<atom:entry>
<atom:id>
https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse
</atom:id>
<atom:category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/apps/2006#nickname"/>
<atom:title type="text">suse</atom:title>
<atom:link rel="self" type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/>
<atom:link rel="edit" type="application/atom+xml"
href="https://apps-apis.google.com/a/feeds/example.com/nickname/2.0/suse"/>
<apps:nickname name="suse"/>
<apps:login userName="SusanJones"/>
</atom:entry>
</atom:feed>

Creating a Nickname

Protocol

To create a nickname, use the following `POST` request:
POST https://apps-apis.google.com/a/feeds/domain/nickname/2.0

Java

import sample.appsforyourdomain.AppsForYourDomainClient;
...
AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
client.createNickname(String username, String nickname)
When creating nicknames with this method, use these arguments:
  • The `username` argument identifies the user account for which you are creating a nickname.
  • The `nickname` argument identifies the nickname for the user account.
  • Python

    import gdata.apps.client
    ...
    client = gdata.apps.client.AppsClient(domain=domain)
    client.ClientLogin(email=email, password=password, source='apps')
    client.CreateNickname(user_name, nickname)
    
    When creating nicknames with this method, use these arguments:
  • The `user_name` argument identifies the user account for which you are creating a nickname.
  • The `nickname` argument identifies the nickname for the user account.
  • .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, email, password);
    service.CreateNickname(String username, String nickname)
    
    When creating nicknames with this method, use these arguments:
  • The `username` argument identifies the user account for which you are creating a nickname.
  • The `nickname` argument identifies the nickname for the user account.
  • PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->createNickname($username, $nickname);
    
    When creating nicknames with this method, use these arguments:
  • The `username` argument identifies the user account for which you are creating a nickname.
  • The `nickname` argument identifies the nickname for the user account.
  • The method returns a NicknameEntry XML response, which the client libraries converts to a NicknameEntry object.

    Retrieving a Nickname

    Protocol

    To retrieve details of a given nickname, use the following `GET` request:
    GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.retrieveNickname(String nickname)
    

    Python

    import gdata.apps.client
    ...
    client = gdata.apps.client.AppsClient(domain=domain)
    client.ClientLogin(email=email, password=password, source='apps')
    client.RetrieveNickname(nickname)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, email, password);
    service.RetrieveNickname(String nickname)
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveNickname($nickname);
    

    The only argument that you need to pass to the method is the nickname you wish to retrieve.

    This method returns a NicknameEntry XML response, which the client libraries converts to a NicknameEntry object.

    Retrieving all Nicknames for a User Account

    Protocol

    To retrieve all nicknames for a particular user, use the following `GET` request:
    GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0?username=
    userName
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.retrieveNicknames(String username)
    

    Python

    import gdata.apps.client
    ...
    client = gdata.apps.client.AppsClient(domain=domain)
    client.ClientLogin(email=email, password=password, source='apps')
    client.RetrieveNicknames(user_name)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, email, password);
    service.RetrieveNicknames(String username)
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveNicknames($username);
    

    The only argument that you need to pass to the method is the username for which you wish to retrieve nicknames.

    This method returns a NicknameFeed XML response, which the client libraries converts to a NicknameFeed object.

    Retrieving all Nicknames in a Domain

    Protocol

    To retrieve all nicknames created in the domain, use the following `GET` request:
    GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.retrieveAllNicknames()
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, email, password);
    service.RetrieveAllNicknames()
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    gdata.retrieveAllNicknames();
    

    This method returns a NicknameFeed XML response, which the client libraries converts to a NicknameFeed object.

    Retrieving List of 100 Nicknames

    This method allows you to control the size of your result set when you request all of the nicknames in your domain. As discussed in the Results Pagination section, the client libraries offer methods that allow you to request all results or to request 100 results at a time. If you use the latter method, you will need to ensure that your code requests additional pages of results as necessary.

    Protocol

    As discussed in Results Pagination, HTTP protocol requests for a NicknameFeed return 100 results by default.
    GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.retrievePageOfNicknames(String startNickname)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, email, password);
    service.RetrievePageOfNicknames(String startNickname)
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrievePageOfNicknames($startNickname=null);
    

    The only argument that you need to pass to the method is the first nickname that should appear in your result set. Nicknames are ordered case-insensitively by ASCII value.

    This method returns a NicknameFeed XML response, which the client libraries converts to a NicknameFeed object.

    Deleting a Nickname

    Protocol

    To delete a nickname, use the following `DELETE` request:
    DELETE https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.deleteNickname(String nickname)
    

    Python

    import gdata.apps.client
    ...
    client = gdata.apps.client.AppsClient(domain=domain)
    client.ClientLogin(email=email, password=password, source='apps')
    client.DeleteNickname(nickname)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.DeleteNickname(String nickname);
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->deleteNickname($nickname);
    

    The only argument that you need to pass to the method is the name of the nickname that you wish to delete.

    Methods for Groups

    Creating a Group

    Protocol

    To create a group, use the following `POST` request:
    POST https://apps-apis.google.com/a/feeds/group/2.0/domain
    
    Note: A group can be created for any domain associated with the account.

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.createGroup(String groupId, String groupName, String groupDescription, String emailPermission)
    
    This method returns a `GroupFeed` XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.CreateGroup(group_id, group_name, description, email_permission)
    
    This method returns a `GroupFeed` XML response, which the Python client library converts to a `Group` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.createGroup(String groupId, String groupName, String description, PermissionLevel? emailPermission)
    
    This method returns a `GroupFeed` XML response, which the .NET client library converts to a `Group` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->createEmailList($listName);
    
    The only argument that you need to pass to the method is the name of the Group that you wish to create. This method returns a `GroupFeed` XML response, which the PHP client library converts to a `Group` object.

    This method of Java, Python and .NET client libraries takes four arguments:

    • The groupId (required, group_id in Python) argument identifies the ID of the new group.
    • The groupName (required, group_name in Python) (required) argument identifies the name of the group being added.
    • The description argument provides a general description of the group.
    • The emailPermission argument sets the permissions level of the group. The permission values are:
      • Owner - Owners of the group
      • Member - Members of the group
      • Domain - Any user who belongs to the same domain as the group
      • Anyone - Any user

    Retrieving a Group

    Protocol

    To retrieve all the groups for a particular member, use the following `GET` request:
    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.retrieveGroup(String groupId)
    
    This method returns a `GroupEntry` XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.RetrieveGroup(group_id)
    
    This method returns a `GroupEntry` XML response, which the Python client library converts to a `GroupEntry` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RetrieveGroup(String groupId)
    
    This method returns a `GroupFeed` XML response, which the .NET client library converts to a `GroupEntry` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveGroup($listName);
    
    This method returns a `GroupEntry` XML response, which the PHP client library converts to a `Group` object.

    The only argument that you need to pass to the method is the name of the group that you wish to retrieve.

    Updating a Group

    Protocol

    To update a group, use the following `PUT` request:
    PUT https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.updateGroup(String groupId, String groupName, String description, String emailPermission)
    
    This method returns a `GroupEntry` XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.UpdateGroup(group_id, group_entry)
    
    This method returns a `GroupEntry` XML response, which the Python client library converts to a `GroupEntry` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.UpdateGroup(String groupId, String groupName, String description, String emailPermission)
    
    This method returns a `GroupEntry` XML response, which the .NET client library converts to a `GroupEntry` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    gdata.Groups.UpdateGroup(String groupId, String groupName, String description, String emailPermission);
    
    This method returns a `GroupEntry` XML response, which the PHP client library converts to a `Group` object.

    This method in the client libraries take four arguments:

    The groupId (required, group_id in Python) argument identifies the ID of the new group. The groupName (required, group_name in Python) argument identifies the name of the group to which the member is being added. The description argument provides a general description of the group. The emailPermission argument sets the permissions level of the group.

    Retrieving all Groups for a Member

    To retrieve all the groups for a particular member, use following method:

    Protocol

    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/?member=memberId[&directOnly=true|false]
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.retrieveGroups(String memberId, Boolean directOnly)
    
    This method returns a `GroupFeed` XML response, which the Java client library converts to a `GenericFeed` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.RetrieveGroups(member_id, direct_only=False)
    
    This method returns a `GroupFeed` XML response, which the Python client library converts to a `GroupFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RetrieveGroups(String memberId, Boolean directOnly)
    
    This method returns a `GroupFeed` XML response, which the .NET client library converts to a `GroupFeed` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveGroup($memberId);
    
    This method returns a `GroupFeed` XML response, which the PHP client library converts to a `Group` object.

    This method in the client libraries take two arguments:

    • The required memberId (member_id in Python) argument identifies the ID of a hosted user for which you want to retrieve group subscriptions.
    • If true, directOnly (direct_only in Python) identifies only members with direct association.

    Retrieving all Groups in a Domain

    To retrieve all of the groups in a domain, use the following method:

    Protocol

    GET https://apps-apis.google.com/a/feeds/group/2.0/domain[?[start=]]
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.retrieveAllGroups()
    
    This method returns a `GroupFeed` XML response, which the Java client library converts to a `GenericFeed` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.RetrieveAllGroups()
    
    This method returns a `GroupFeed` XML response, which the Python client library converts to a `GroupFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RetrieveAllGroups()
    
    This method returns a `GroupFeed` XML response, which the .NET client library converts to a `GroupFeed` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveAllGroups();
    
    This method returns a `GroupFeed` XML response, which the PHP client library converts to a `Group` object.

    Deleting a Group

    To delete a group, use the following method:

    Protocol

    DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.deleteGroup(String groupId)
    

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.DeleteGroup(group_id)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.DeleteGroup(String groupId)
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->deleteGroup($groupName);
    

    The only argument that you need to pass to the method is the name of the group that you wish to delete.

    Methods for Group Members

    Adding a Member to a Group

    To add a member to a group, use the following method:

    Protocol

    POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.addMemberToGroup(String groupId, String memberId)
    
    This method returns a `MemberEntry` XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.AddMemberToGroup(group_id, member_id)
    
    This method returns a `MemberEntry` XML response, which the Python client library converts to a `MemberEntry` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.AddMemberToGroup(String groupId, String memberId)
    
    This method returns an `MemberEntry` XML response, which the .NET client library converts to a `MemberEntry` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->addRecipientToEmailList($groupId, $memberId);
    
    This method returns an `GroupEntry` XML response, which the PHP client library converts to a `GroupEntry` object.

    This method takes two arguments:

    • The groupId argument (group_id in Python) identifies the group to which the address is being added.
    • The memberId argument (member_id in Python) identifies the username of the member that is being added to a group.

    Retrieving all Members of a Group

    To retrieve a list of all of the subscribers to a group, use the following method:

    Protocol

    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member[?[start=]&[includeSuspendedUsers=true|false]]
    
    • `start` - the start key for resuming a paged feed.
    • `includeSuspendedUsers` - true, to include suspended users. The default value is false.
    To retrieve a particular member of a group, use the following `GET` request:
    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.retrieveAllMembers(String groupId)
    
    This method returns a `MemberFeed` XML response, which the Java client library converts to a `GenericFeed` object.

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.RetrieveAllMembers(group_id)
    
    This method returns a `MemberFeed` XML response, which the Python client library converts to a `MemberFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RetrieveAllMembers(String groupId)
    
    This method returns a `MemberFeed` XML response, which the .NET client library converts to a `MemberFeed` object.

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->retrieveAllMembers($listName);
    
    This method returns a `GroupFeed` XML response, which the PHP client library converts to a `GroupFeed` object.

    The only argument that you need to pass to the method is the name of the group for which you wish to retrieve a member list.

    Deleting a Member from an Group

    To delete a member (email address) from a group using the client libraries, call the following method.

    Protocol

    DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.deleteMemberFromGroup(String groupId, String memberName)
    

    Python

    import gdata.apps.groups.client
    ...
    groupClient = gdata.apps.groups.client.GroupsProvisioningClient(domain=domain)
    groupClient.ClientLogin(email=email, password=password, source='apps')
    groupClient.RemoveMemberFromGroup(group_id, member_id)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RemoveMemberFromGroup(String groupId, String memberId)
    

    PHP

    <?php
    require_once 'Zend/Loader.php';
    Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
    Zend_Loader::loadClass('Zend_Gdata_Gapps');
    ...
    $client = Zend_Gdata_ClientLogin::getHttpClient($email, $password, Zend_Gdata_Gapps::AUTH_SERVICE_NAME);
    $gdata = new Zend_Gdata_Gapps($client, 'example.com');
    $gdata->removeRecipientFromGroup($listName, $recipient);
    

    This method takes two arguments:

    • The groupId (group_id in Python) argument identifies the member from which the address is being removed.
    • The memberId (member_id in Python) argument identifies the username of the member that is being removed from a group.

    Methods for Group Owners

    Assigning an Owner to a Group

    To assign an owner to a group using the client libraries, use the following method:

    Protocol

    POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner
    

    Sample OwnerEntry Request

    The XML uses the "email" property to identify the email address of the member being added as the owner of the group.
    <?xml version="1.0" encoding="UTF-8"?>
    <atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006"
    xmlns:gd="http://schemas.google.com/g/2005">
    <apps:property name="email" value="joe@example.com"/>
    </atom:entry>
    
    You can also add an owner that is a group itself by specifying the group's email address:
    <?xml version="1.0" encoding="UTF-8"?>
    <atom:entry xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns:apps="http://schemas.google.com/apps/2006"
    xmlns:gd="http://schemas.google.com/g/2005">
    <apps:property name="email" value="sales-leads@example.com"/>
    </atom:entry>
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.addOwnerToGroup(String groupId, String email)
    
    This method returns a `OwnerEntry` XML response, which the Java client library converts to a `GenericEntry` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.AddOwnerToGroup(String groupId, String email)
    

    This method takes two arguments:

    • The groupId (group_id in Python) argument identifies the group to which the address is being added.
    • The email (owner_email in Python) argument identifies the name that is being added to a group as the owner.

    Querying for all Owners of a Group

    To retrieve all of the owners of a group using the client libraries, use the following method:

    Protocol

    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner[?[start=]]
    
    • `start` — The start key for resuming a paged feed. This parameter is optional.
    • If the response returns over 200 entries, the responses includes pagination link tags.

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    client.retrieveGroupOwners(String groupId)
    
    This method returns a `OwnerFeed` XML response, which the Java client library converts to a `GenericFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RetrieveGroupOwners(String groupId)
    

    The only argument that you need to pass to the method is the name of the group for which you want to retrieve an owner list.

    Querying if a User or Group is Owner

    To query a group to find out if a user or group owns a group using the client libraries, use the following method:

    Protocol

    GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.isOwner(String groupId, String email)

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.IsOwner(String groupId, String email)
    

    This method returns a boolean value which is true if the user is an owner of the group, false otherwise.

    Deleting an Owner from a Group

    To delete an owner from a group using the client libraries, use the following method.

    Protocol

    DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail
    

    Java

    import sample.appsforyourdomain.AppsForYourDomainClient;
    ...
    AppsForYourDomainClient client = new AppsForYourDomainClient(email, password, domain);
    groupService.removeOwnerFromGroup(String groupId, String email)
    

    .NET

    using Google.GData.Apps;
    ...
    AppsService service = new AppsService(domain, userName, password);
    service.Groups.RemoveOwnerFromGroup(String email, String groupId)
    

    This method takes two arguments:

    • The email argument identifies the email address that is being removed as the owner of the group.
    • The groupId (group_id in Python) argument identifies the group from which the address is being removed.

    Managing Users in Multiple Domains

    A Google Apps account can include any of your domains. In a multiple domain account, users in one domain can share services with users in other account domains.

    Multiple domain terms

    • Primary domain — Your account's primary domain is the domain of the administrator who accepted the Google Apps Terms of Service agreement. This domain is at the account-level in the top-level organization unit. When signing up for a Google Apps account, we recommend using your business domain for the primary domain, and reserve your other domains for specialized uses such as pilots and testing.
      • The primary domain is used in your control panel's URL address (http://www.google.com/a/primary domain).
      • All administrators can manage the full account. But, in this version of the API, we recommend the administrator's primary email address use the account's primary domain.
      • The Provisioning API cannot change or move the Google Apps account's primary domain. But the API can rename a user's account.
      • For Google Apps for Business and Education accounts, you have 14 days to verify your ownership of the primary domain. For additional domains, you must verify your domain ownership before using the domain for a user's primary email address. In these cases, the 14 day grace period does not apply.
      • In this version of the API, the primary domain's settings apply to all domains associated with the account except for the user access to the Google Apps services.
    • Additional account domains — After establishing your primary domain and setting up your account, your can add your additional domains to the account.
      • For additional domains, verify your ownership when setting up this domain and before using the domain for a user's primary email address.
    • User's home domain — The domain used in a user's primary email address is the user's home domain. This domain can be any domain in the account, including the primary domain.

    Multiple domain resources

    • For control panel information, see the Add domain and domain aliases in the Help Center.
    • Google Apps Directory Sync tool — To provision your account's users and groups with your LDAP settings, use the Google Apps Directory Sync tool.
    • Java Multiple Domain Client — The sample Java client application code for multiple domains is available in the com.google.gdata.client.sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient.java class in the gdata-samples package.
    • This release's current multiple domain feed status and limitations — For the latest multiple domain feed limitations, see multidomain limitations. This includes information for domain aliases, account merging, etc.

    Creating a User for a Domain

    A user account can be added to any of your Google Apps account's domains including the primary domain. And before adding a user account, we recommend confirming the domain ownership.

    Protocol

    To create a user account using one of your domains, send the following `POST` HTTP request to the `user`> feed URI. Include the `Authorization` header as described in Authenticating Requests:

    POST https://apps-apis.google.com/a/feeds/user/2.0/the domain name
    
    For example, to create a new user account using the example.com domain, send a `POST` to:
    POST https://apps-apis.google.com/a/feeds/user/2.0/example.com
    
    The `POST` request contains the following Content-type header:
    Content-type: application/atom+xml
    
    The following example request creates the `liz@example.com` user account which is also the user's the primary email address:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <apps:property name="password" value="your domain password in SHA-1 hash format"/>
    <apps:property name="hashFunction" value="SHA-1"/>
    <apps:property name="userEmail" value="liz@example.com"/>
    <apps:property name="firstName" value="Liz"/>
    <apps:property name="lastName" value="Smith"/>
    <apps:property name="isAdmin" value="true"/>
    </atom:entry>
    
    A successful response returns an HTTP `201` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements for a new user account:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz@example.com</id>
    <updated>2008-10-17T15:02:45.646Z</updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40@example.com'/>
    <link rel='edit' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40@example.com'/>
        <apps:property name='password'
    value='51eea05d46317fadd5cad6787a8f562be90b4446'/>
        <apps:property name='userEmail' value='liz@example.com'/>
        <apps:property name='firstName' value='Liz'/>
        <apps:property name='lastName' value='Smith'/>
        <apps:property name='isAdmin' value='true'/>
    </entry>
    
    Note: The maximum number of domains allowed in an account is 600 (1 primary domain + 599 additional domains). And note the `firstName`, `lastName`, and, `isAdmin` properties as compared to the `familyName`, `givenName`, `admin` of the User Feed Response.

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail,
    adminPassword, domain, appName); multiDomainClient.createUser(String email, String password, String firstName, String lastName,
    Map<UserProperty, String>optionalAttributes)
    This method takes the following arguments:
    • The `email` argument contains the email address of the user.
    • The `firstName` argument contains the user's first name.
    • The `lastName` argument contains the user's last name.
    • The `password` argument contains the password for the user account.
    • The `optionalAttributes` argument (optional) contains a hashmap of user properties and values. The keys available are:
      -HASH_FUNCTION: The name of the hash function.
      -ADMIN: Whether the user is an admin or not.
      -SUSPENDED: Is the new user suspended.
      -CHANGE_PASSWORD_AT_NEXT_LOGIN: Should a user be prompted for a password change at next login.
      -QUOTA: Quota allocated to the user in Gb.
      -IP_WHITELIST: Determines whether or not the user's ip is whitelisted.
    This method returns a Multi Domain user entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.CreateUser(email, first_name, last_name, password, is_admin, hash_function=None, suspended=None, change_password=None, ip_whitelisted=None, quota=None)
    
    This method takes the following arguments:
    • The `email` argument contains the email address of the user.
    • The `first_name` argument contains the user's first name.
    • The `last_name` argument contains the user's last name.
    • The `password` argument contains the password for the user account.
    • The `is_admin` argument determines whether or not the user had admin privileges.
    • The `hash_function` argument (optional) contains the name of the function used to hash the password.
    • The `suspended` argument (optional) determines whether or not the user account is suspended.
    • The `change_password` argument (optional) determineswhether or not the user must change password at first login.
    • The `ip_whitelisted` argument (optional) determines whether or not the user's ip is whitelisted.
    • The `quota` argument (optional) is the value (in GB) of the user's quota.
    This method returns a a Multi Domain user entry XML response, which the Python client library converts to a Multi Domain user entry object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.CreateDomainUser(String domain, String userEmail, String password, String firstName, String lastName, Boolean isAdmin)
    service.CreateDomainUser(String domain, String userEmail, String password, String hashFunction, String firstName, String lastName, Boolean isAdmin)
    
    This method takes the following arguments:
    • The `domain` argument dentifies the domain on which you are creating the user.
    • The `userEmail` argument contains the unique email address that identifies the account.
    • The `password` argument contains the password for the user account.
    • The `hashFunction` argument contains the name of the function used to hash the password.
    • The `firstName` argument contains the user's first name.
    • The `lastName` argument contains the user's last name.
    • The `isAdmin` argument determines whether or not the user had admin privileges.
    This method returns a Multi Domain user entry XML response, which the .NET client library converts to a `AppsExtendedEntry` object.

    Updating a Domain User's Account

    To update a user account on a secondary domain use the following method.

    Protocol

    To update a user's account information, send a `PUT` request to the `user` feed's URI. Include the Authorization header as described in Authenticating Requests:
    PUT https://apps-apis.google.com/a/feeds/user/2.0/the domain name/user email address
    
    An example of a request changing the user's `firstName` property from `Liz` to `Elizabeth`:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <apps:property name='firstName' value='Elizabeth'/>
    </atom:entry>
    
    Note: The `userEmail` property can not be updated using the Update operation. See Renaming a User's Account A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the updated `entry` elements:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com</id>
        <updated>2008-10-17T15:02:45.646Z</atom:updated>
        <link rel='self' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com'/>
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="isAdmin" value="true" />
        <apps:property name="firstName" value="Elizabeth" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    
    multiDomainClient.updateUser(String email, Map<String, String> updatedAttributes)
    This method takes two arguments:
    • The `email` argument identifies the email account that you are updating.
    • The `updateAttributes` argument is a key-value map of attributes to be updated on a user account, including the user's first name, last name and password. The available keys are:
    • -password: The password of the user.
      -firstName: First name of the user.
      -lastName: Last name of the user.
      -name: The name of the hash function.
      -isAdmin: Whether the user is an admin or not.
      -isSuspended: Is the new user suspended.
      -isChangePasswordAtNextLogin: Should a user be prompted for a password change at next login.
      -quotaInGb: Quota allocated to the user in Gb.
      -ipWhitelisted: Determines whether or not the user's ip is whitelisted.
    This method returns an updated Multi Domain user entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.UpdateUser(email, user_entry)
    This method takes the following arguments:
    • The `email` argument identifies the email account that you are updating.
    • The `user_entry` object contains updated values about a user account, including the user's first name, last name, username and password.
    This method returns an updated Multi Domain user entry XML response, which the Python client library converts to a Multi Domain user entry object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.UpdateDomainUser(String domain, String userEmail, IDictionary attributes)
    
    This method takes 3 arguments:
    • The `domain` argument identifies the user's domain.
    • The `userEmail` argument contains the unique email address that identifies the account.
    • The `attributes` argument contains the set of attributes to update.
    This method returns an updated Multi Domain user entry XML response, which the .NET client library converts to a `AppsExtendedEntry` object.

    Renaming a User's Account

    To rename a user's account to a different domain use the following method.

    Protocol

    To rename a user's account to a different domain in the Google Apps account, send a `PUT` request to the `userEmail` feed's URI. Include the Authorization header as described in Authenticating Requests:
    PUT https://apps-apis.google.com/a/feeds/user/userEmail/2.0/the old domain name/full old primary email address
    
    An example of a request moving the user's account, the old primary email address `liz@example.com` is moved to one of the Google Apps account's other domains, `liz@newexample4liz.com`:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <apps:property name='newEmail' value='liz@newexample4liz.com'/>
    </atom:entry>
    
    Note: Renaming a user account changes the user's primary email address and the domain used when retrieving this user's information. Before changing the primary email address, we recommend you log the user out of all browser sessions and services. Also, when changing a user account, the old user email address is retained as an email alias to ensure continuous mail delivery of forwarded email messages. A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the updated `entry` elements:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/user/userEmail/2.0/example.com/
    liz%40example.com</id>
        <updated>2008-10-17T15:02:45.646Z</atom:updated>
        <link rel='self' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/user/userEmail/2.0/example.com/liz%40example.com'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/user/userEmail/2.0/example.com/liz%40example.com'/>
        <apps:property name="newEmail" value="liz@newexample4liz.com"
    />
    </entry>
    
    In this example, the Retrieving a Single User in a Domain operation returns the user's new account information which includes the updated `apps:property name="userEmail" value="liz@newexample4liz.com"` property.

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail,
    adminPassword, domain, appName); multiDomainClient.updateEmailAddress(String oldEmailAddress, String newEmailAddress)
    This method takes two arguments:
    • The `oldEmailAddress` argument identifies the email address that you are renaming.
    • The `newEmailAddress` argument identifies the new email address.
    This method returns an updated Multi Domain user entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RenameUser(old_email, new_email)
    This method takes the following arguments:
    • The `old_email` argument identifies the email account to be renamed.
    • The `new_email` argument identifies the new email account.
    This method returns an updated Multi Domain user entry XML response, which the Python client library converts to a `Multi Domain user entry` object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RenameDomainUser(String domain, String userEmail, String newEmail)
    
    This method takes 3 arguments:
    • The `domain` argument identifies the user's domain.
    • The `userEmail` argument contains the unique email address that identifies the account.
    • The `newEmail` argument contains the new user's email address.
    This method returns a user entry XML response, which the .NET client library converts to a `AppsExtendedEntry` object.

    Retrieving Users

    Retrieving a Single User in a Domain

    To retrieve a user account associated with a specific domain use the following method.

    Protocol

    To retrieve a user account associated with a specific domain, send a `GET` request to the `user` feed's URI. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/user/2.0/the domain name/full user email
    
    This example uses `joe@another_example.com`:
    GET https://apps-apis.google.com/a/feeds/user/2.0/another_example.com/joe@another_example.com
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements for the user account:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/user/2.0/another_example.com/joe%
    40another%5Fexample.com</id>
    <updated>2008-10-17T15:02:45.646Z</atom:updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/user/2.0/another_example.com/joe%40another%5Fexample.com'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/user/2.0/another_example.com/joe%40another%5Fexample.com'/>
        <apps:property name="lastName" value="Jones" />
        <apps:property name="isChangePasswordAtNextLogin" value="false"
    />
        <apps:property name="isSuspended" value="false" />
        <apps:property name="userEmail" value="joe@another_example.com"
    />
        <apps:property name="isAdmin" value="false" />
        <apps:property name="firstName" value="joe" />
        <apps:property name="ipWhitelisted" value="false" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.retrieveUser(String email)
    This method takes one argument:
    • The `email` argument identifies the email address of the user to be retrieved.
    This method returns a Multi Domain user entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RetrieveUser(email)
    This method takes the following argument:
    • The `email` argument identifies the email account of the user to be retrieved.
    This method returns a Multi Domain user entry XML response, which the Python client library converts to a Multi Domain user entry object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveDomainUser(String domain, String userEmail)
    
    This method takes 2 arguments:
    • The `domain` argument identifies the user's domain.
    • The `userEmail` argument contains the unique email address that identifies the account.
    This method returns a user entry XML response, which the .NET client library converts to a `AppsExtendedEntry` object.

    Retrieving All Users in All Domains

    To retrieve all users in all domains use the following method.

    Protocol

    To retrieve all users in all domains, send a `GET` request to the `user` feed's URI. This returns the users in all of your account's domains. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/user/2.0/the domainname?start=the user name@domain.com
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements for all users in your account's domains:
    <?xml version='1.0' encoding='UTF-8'?>
    <feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensesearchrss/1.0/"
    mlns:apps="http://schemas.google.com/apps/2006">
     
    <id>https://apps-apis.google.com/a/feeds/user/2.0/example.com</id>
      <updated>2010-01-26T23:38:13.215Z</updated>
      <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com" />
      <link rel="http://schemas.google.com/g/2005#post"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com" />
      <link rel="self" type="application/atom+xml"
     
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com?start=admin%40example.com" />
      <openSearch:startIndex>1</openSearch:startIndex>
      <entry>
       
    <id>https://apps-apis.google.com/a/feeds/user/2.0/example.com/admin%40example.com</id>
        <updated>2010-01-26T23:38:13.210Z</updated>
        <link rel="self" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com/admin%40example.com" />
        <link rel="edit" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com/admin%40example.com" />
        <apps:property name="lastName" value="Brown" />
        <apps:property name="isChangePasswordAtNextLogin" value="false"
    />
        <apps:property name="isSuspended" value="false" />
        <apps:property name="userEmail" value="admin@example.com" />
        <apps:property name="isAdmin" value="true" />
        <apps:property name="firstName" value="Joe" />
        <apps:property name="ipWhitelisted" value="false" />
      </entry>
      <entry>
       
    <id>https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com</id>
        <updated>2010-01-26T23:38:13.210Z</updated>
        <link rel="self" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com" />
        <link rel="edit" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/user/2.0/example.com/liz%40example.com" />
        <apps:property name="lastName" value="Smith" />
        <apps:property name="isChangePasswordAtNextLogin" value="false"
    />
        <apps:property name="isSuspended" value="false" />
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="isAdmin" value="true" />
        <apps:property name="firstName" value="Elizabeth" />
        <apps:property name="ipWhitelisted" value="false" />
      </entry>
    </feed>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.retrieveAllUsers()
    This method returns a Multi Domain UserFeed XML response, which the Java client library converts to a List of `GenericEntry` objects.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RetrieveAllUsers()
    This method returns a Multi Domain UserFeed XML response, which the Python client library converts to a Multi Domain UserFeed object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllDomainUsers(String domain)
    
    The only argument that you need to pass to the method is the name of the domain for which you want to retrieve all users. This method returns a UserFeed XML response, which the .NET client library converts to a `AppsExtendedFeed` object.

    Deleting a User from a Domain

    To delete a user account use the following method.

    Protocol

    To delete a user account, send a `DELETE` request to the `user` feed's URI. Include the Authorization header as described in Authenticating Requests:
    DELETE https://apps-apis.google.com/a/feeds/user/2.0/the domain name/user email address
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.deleteUser(email)
    
    This method takes one argument:
    • The `email` argument identifies the email address of the user to be deleted.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.DeleteUser(email)
    This method takes the following argument:
    • The `email` argument identifies the email account of the user to be deleted.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.DeleteDomainUser(String domain, String userEmail)
    
    This method takes 2 arguments:
    • The `domain` argument identifies the user's domain.
    • The `userEmail` argument contains the unique email address that identifies the account.

    Managing User Aliases in Multiple Domains

    A user's email alias is an alternate email address that uses the same mailbox used by the user's primary email address. For example, using the account's example.com and anotherexample.com domains, the user liz@example.com could have these email aliases:

    • support@example.com
    • helpdesk@anotherexample.com

    Creating a User Alias in a Domain

    A user alias can be associated with a different domain than the domain used by the user's primary email address. The API requires a domain's ownership be confirmed before the user alias can be created.

    To create a user alias that can be associated with a different domain use the following method:

    Protocol

    To create a user alias, send a `POST` request to the `alias` feed's URI. Include the Authorization header as described in Authenticating Requests:
    POST https://apps-apis.google.com/a/feeds/alias/2.0/the alias domain
    
    The `POST` request contains the following Content-type header:
    Content-type: application/atom+xml
    
    The following example request creates the user alias using one of the account's additional domains, `helpdesk@gethelp_example.com`, for `liz@example.com`, the user's primary email address:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
        <apps:property name="aliasEmail"
    value="helpdesk@gethelp_example.com" />
        <apps:property name="userEmail" value="liz@example.com" />
      </atom:entry>
    
    A successful response returns an HTTP `201` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements for a new user. The example uses the helpdesk@gethelp_example.com user alias for liz@example.com:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com</id>
    <updated>2008-10-17T15:02:45.646Z</atom:updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com'/>
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="aliasEmail"
    value="helpdesk@gethelp_example.com" />
    </entry>
    
    Note: To update a user alias, create a new user alias with the same `aliasEmail` value.

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.createAlias(String aliasEmail, String userEmail)
    This method takes two arguments:
    • The `aliasEmail` argument identifies the alias email of the user.
    • The `userEmail` argument is the email address of the user.
    This method returns a entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.CreateAlias(user_email, alias_email)
    
    This method takes the following arguments:
    • The `user_email` argument identifies the email of the user.
    • The `alias_email` argument is the alias email of the user.
    This method return a Entry XML response, which the Python client library converts to a `MultiDomain Alias user entry` object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.CreateDomainUserAlias(String domain, String userEmail, String aliasEmail)
    
    This method takes 3 arguments:
    • The `domain` argument identifies the user's domain.
    • The `userEmail` argument contains the unique email address that identifies the account.
    • The `aliasEmail` argument contains the alias to be added to the user.
    This method returns a `AppsExtendedEntry` object.

    Retrieving User Aliases

    Retrieving a User Alias in a Domain

    To retrieve a single user alias use the following method:

    Protocol

    To retrieve a single user alias, send a `GET` request to the `alias` feed's URI. The URI's domain name can be the user alias's domain or the domain in the user's primary email address. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/alias/2.0/the domain name/alias email address
    
    This example uses helpdesk@example.com:
    GET https://apps-apis.google.com/a/feeds/alias/2.0/example.com/helpdesk@example.com
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements. The example uses the helpdesk@gethelp_example.com user alias for liz@example.com:
    <?xml version='1.0' encoding='UTF-8'?>
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com</id>
    <updated>2008-10-17T15:02:45.646Z</atom:updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%5Fexample.com'/>
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="aliasEmail"
    value="helpdesk@gethelp_example.com" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.retrieveAlias(String aliasEmail)
    
    This method takes one argument:
    • The `aliasEmail` argument is email alias of the user.
    This method returns a entry XML response, which the Java client library converts to a `GenericEntry` object.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RetrieveAlias(email)
    
    This method takes the following argument:
    • The `email` argument identifies the email of the alias to be retrieved.
    This method return a Entry XML response, which the Python client library converts to a `MultiDomain Alias user entry` object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveDomainUserAlias(String domain, String aliasEmail)
    
    This method takes 2 arguments:
    • The `domain` argument identifies the user alias's domain or the domain in the user's primary email address.
    • The `aliasEmail` argument contains the alias' email address.
    This method returns a `AppsExtendedEntry` object.

    Retrieving All User Aliases in a Domain

    To retrieve all of a domain's user aliases use the following method:

    Protocol

    To retrieve all of a domain's user aliases, send a `GET` request to the `alias` feed's URI. The URI's domain name can be an alias's domain or a user's primary email address domain. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/alias/2.0/the domain name?start=alias@domain
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements. The example uses the helpdesk@gethelp_example.com user alias for liz@example.com. If this response returns over 100 entries, the response uses pagination link tags.
    <?xml version='1.0' encoding='UTF-8'?>
    <feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
    xmlns:apps="http://schemas.google.com/apps/2006">
     
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com<
    /id>
      <updated>2010-01-26T23:38:13.215Z</updated>
      <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com" />
      <link rel="http://schemas.google.com/g/2005#post"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com" />
      <link rel="self" type="application/atom+xml"
     
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com?start=
    helpdesk%40gethelp%2Fexample.com" />
      <openSearch:startIndex>1</openSearch:startIndex>
      <entry>
       
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com</id>
        <updated>2010-01-26T23:38:13.210Z</updated>
        <link rel="self" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com" />
        <link rel="edit" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com" />
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="aliasEmail"
    value="helpdesk@gethelp_example.com" />
      </entry>
    <entry>
     ...
    </entry>
     ...
    </feed>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.retrieveAllAliases()
    
    This method returns a entry XML response, which the Java client library converts to a list of `GenericEntry` objects.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RetrieveAllAliases()
    
    This method return a Feed XML response, which the Python client library converts to a `MultiDomain Alias UserFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllDomainUserAlias(String domain)
    
    The only argument that you need to pass to the method is the name of the domain for which you want to retrieve all aliases. This method returns a `AppsExtendedFeed` object.

    Retrieving All User Aliases for a User

    To retrieve all the aliases for a user use the following method:

    Protocol

    To retrieve all of a user's aliases, send a `GET` request to the `alias` feed's URI. The URI's domain name can be the alias's domain or the user's primary email address domain. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/alias/2.0/the domain name?userEmail=user@domain
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements. This example uses the gethelp_example.com domain, the liz@example.com user, and the helpdesk@gethelp_example.com alias:
    <?xml version='1.0' encoding='UTF-8'?>
    <feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
    xmlns:apps="http://schemas.google.com/apps/2006">
     
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com<
    /id>
      <updated>2010-01-26T23:38:13.215Z</updated>
      <link rel="http://schemas.google.com/g/2005#feed"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com" />
      <link rel="http://schemas.google.com/g/2005#post"
      type="application/atom+xml"
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com" />
      <link rel="self" type="application/atom+xml"
     
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com?
    userEmail=helpdesk%40gethelp%2Fexample.com" />
      <openSearch:startIndex>1</openSearch:startIndex>
      <entry>
       
    <id>https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com</id>
        <updated>2010-01-26T23:38:13.210Z</updated>
        <link rel="self" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com" />
        <link rel="edit" type="application/atom+xml"
       
    href="https://apps-apis.google.com/a/feeds/alias/2.0/gethelp_example.com/
    helpdesk%40gethelp%2Fexample.com" />
        <apps:property name="userEmail" value="liz@example.com" />
        <apps:property name="aliasEmail"
    value="helpdesk@gethelp_example.com" />
      </entry>
    </feed>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.retrieveAllUserAliases(String userEmail)
    
    This method takes one argument:
    • The `userEmail` argument is the email address of the user.
    This method returns a entry XML response, which the Java client library converts to a list of `GenericEntry` objects.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.RetrieveAllUserAliases(user_email)
    
    This method takes one argument:
    • The `user_email` argument identifies the email of the user.
    This method returns a Feed XML response, which the Python client library converts to a `AliasFeed` object.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllDomainUserAliasForUser(String domain, String userEmail)
    
    This method takes 2 arguments:
    • The `domain` argument identifies the user alias's domain or the domain in the user's primary email address.
    • The `userEmail` argument contains the unique email address that identifies the account.
    This method returns a `AppsExtendedFeed` object.

    Deleting a User Alias from a Domain

    To delete a user alias use the following method:

    Protocol

    To delete a user alias, send a `DELETE` request to the `alias` feed's URI. Include the Authorization header as described in Authenticating Requests:
    DELETE https://apps-apis.google.com/a/feeds/alias/2.0/the domain name/user email address
    

    Java

    import sample.appsforyourdomain.labs.provisioning.ProvisioningApiMultiDomainSampleClient;
    ...
    ProvisioningApiMultiDomainSampleClient multiDomainClient = new ProvisioningApiMultiDomainSampleClient(adminEmail, adminPassword, domain, appName);
    multiDomainClient.deleteAlias(String aliasEmail)
    This method takes one argument:
    • The `aliasEmail` argument identifies the user’s email alias to be deleted.

    Python

    import gdata.apps.multidomain.client; 
    ...
    multiDomainClient = gdata.apps.multidomain.client.MultiDomainProvisioningClient(domain=domain)
    multiDomainClient.ClientLogin(email=email, password=password, source='apps')
    multiDomainClient.DeleteAlias(email)
    This method takes the following argument:
    • The `email` argument identifies the alias to be deleted.

    .NET

    using Google.GData.Apps;
    ...
    MultiDomainManagementService service = new MultiDomainManagementService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.DeleteDomainUserAlias(String domain, String aliasEmail)
    
    This method takes 2 arguments:
    • The `domain` argument identifies the user alias's domain or the domain in the user's primary email address.
    • The `aliasEmail` argument contains the alias' email address.

    Managing Organization Units

    A Google Apps account's organizational tree is composed of organization units which let you manage your users in a logical and hierarchical structure. This is similar to the functionality found at the control panel's 'Organizations and users' tab. For more information, see the Creating an organizational structure in the Help Center:

    • There is only one organization tree to a Google Apps account. When this account is initially configured, it has an organization unit at the account-level. This is the organization associated with the primary domain. For more information about the primary domain, see Managing Users in Multiple Domains.
    • An organization unit's pathname is unique. The organization unit's name may not be unique within the organization hierarchy but it's name is unique amongst it's sibling organization units. And an organization unit's name is case insensitive.
    • An organization unit inherits policies from the organizational hierarchy. Any organization unit can block this chain of parental inheritance. And the precedence of one policy over another is determined by the nearest organization unit. Meaning a lower organization unit's policies can take precedence over the policies of the higher parental units.
    • An organization unit can be moved up or down a hierarchical tree. And, the organization's associated users can be moved individually or in a batch when populating a new organization or moving a subset of users from one organization unit to another.
    • The data kept in organization unit properties can be constantly changing. When making a request, properties returned for an entity are guaranteed to be consistent at the time the entity was retrieved.That is, you will not see "partial" updates. If a retrieval operation returns more than one entity, there is no consistency guarantee across entities.This is especially true when a response spans multiple pages in pagination.

    Retrieving a customerId

    Within the organization hierarchy, a Google Apps account is uniquely identified by a customerId. This identifier is not the same as the account's domain name nor the customer's public business or personal name. This immutable String identifies the Google Apps account and is used in any API request and response operating on organizational units and users.

    Protocol

    To retrieve a `customerId` for the account of the authenticated administrator making this request, send a `GET` request to the `customer` feed's URI. Include the Authorization header as described in Authenticating to your Domain. Also note the spelling of 'customerId' has a capital 'I':
    GET https://apps-apis.google.com/a/feeds/customer/2.0/customerId
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements. Initially, the customerOrgUnitName and the customerOrgUnitDescription values are the domain name. These can be edited in the control panel. A response example:
    <?xml version='1.0' encoding='UTF-8">
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb</id>
    <updated>2008-10-17T15:02:45.646Z</atom:updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb'/>
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb'/>
        <apps:property name="customerId" value="C03az79cb" />
        <apps:property name="name" value="example.com" />
        <apps:property name="description" value="The customerId of the
    example.com account" />
        <apps:property name="customerOrgUnitName" value="example.com"
    />
        <apps:property name="customerOrgUnitDescription"
    value="customer org unit for example.com account" />
    </entry>
    
    The `customerId` parameters are:
    customerId
    The `customerId` is the system's unique identifier for the Google Apps customer's account. This ID is used in all request and response operations for organizational units and users for the account's primary domain and, in the case of multiple domains, for any account's domain aliases. The customerId can be called by any domain administrator for this account. Note: The `customerId` parameter's format may change in future API releases. When making an API request, both formats are supported. But future API responses may contain a different `customerId` in the URL's response links than the `customerId` value used in your request. If your client application uses the request's `customerId` as a key value for persistent data, this key could break if the response returns a different `customerId` value
    name
    The name helps to identify the `customerId` to a specific Google Apps account. Initially, this property's value may be the account's domain name. The name should be no more than 128 characters.
    description
    The description is the descriptive text referring to the account's domain name. This property value may be an empty String if no description has been entered, and if entered, the description should be no more than 512 characters.

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName);
    orgUnitClient.retrieveCustomerId(String domain)
    
    This method takes one argument:
    • The `domain` argument is the nameof the domain.
    This method returns a GenericEntry XML response.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveCustomerId()
    This method returns a Python dictionary object.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveCustomerId(String domain)
    
    The only argument that you need to pass to the method is the name of the domain for which you want to retrieve the customerId. This method returns a `AppsExtendedEntry` object.

    Creating an Organization Unit

    To create an organization unit use the following method.

    Protocol

    To create an organization unit, send a `POST` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    POST https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId
    
    For example, to create an organization unit for the customerId CO3az79cb, send a `POST` to:
    POST https://apps-apis.google.com/a/feeds/orgunit/2.0/CO3az79cb
    
    The following example request creates a Human Resources organization unit:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb</id>
        <apps:property name="name" value="Human Resources" />
        <apps:property name="description" value="The corporate human
    resources organization" />
        <apps:property name="parentOrgUnitPath"
    value="corp/Human+Resources" />
        <apps:property name="blockInheritance" value="false" />
    </atom:entry>
    
    The organization unit creation parameters are:
    name
    The `name` is the simple organization unit text name, not the full path name. This parameter is required. The `name` is composed of unicode/UTF-8 characters and should be no more than 128 characters. The path name is unique and is case insensitive. The `name` cannot be blank or a series of spaces. Do not use spaces to distinguish one organization name from another. When a new organization unit is created or modified, its name is verified. For more naming guidelines, see Character Usage. We recommend using names that are descriptive of the organization's purpose, and names that are short in length for easier management. As a `name` property, the organization's name is not URL-encoded. But when listed in a path, for example the `parentOrgUnitPath`, each organization unit name in the path is subject to URL-encoding. In this example, the Human Resources organization is URL-encoded when in a parent organization's path, Human+Resources.
    description
    The `description` is the human readable text description of the organization unit. The `description` should be no more than 512 characters. This parameter is optional but strongly recommended.
    parentOrgUnitPath
    The `parentOrgUnitPath` is the full path of the parental tree to this organization unit. It does not include the specific organization unit name. The `orgUnitPath` parameter, used when calling specific organization units or users, is the full parent path with the organization unit's name. Path names are case insensitive. This parameter is required. If the parent organization unit is the top-level organization, it is represented as a forward slash, '/'.
    blockInheritance
    The `blockInheritance` parameter blocks policy setting inheritance from organization units higher in the organization tree. The value is either the boolean `true` or `false`. This parameter is optional, and the default is `false`.
    A successful response returns an HTTP `201` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` element showing the `orgUnitPath` for new Sales organization unit:
    <?xml version='1.0' encoding='UTF-8">
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
    <apps:property name="OrgUnitPath" value="example.com/corp/Sales" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.createOrganizationUnit(String customerId, String orgUnitName, String parentOrgUnitPath, String description, Boolean blockInheritance)
    
    This method takes the following arguments:
    • The `customerId` argument contains the ID of the Google Apps customer.
    • The `orgUnitName` argument is the organization unit name.
    • The `parentOrgUnitPath` argument is the full path of the parental tree to this organization unit.
    • The `description` argument is the human readable text description of the organization unit.
    • The `blockInheritance` argument blocks policy setting inheritance from organization units higher in the organization tree.
    This method returns a GenericEntry XML response.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.CreateOrgUnit(customer_id, name, parent_org_unit_path='/', description='', block_inheritance=False)
    
    This method takes the following arguments:
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `name` argument is the organization unit name.
    • The `parent_org_unit_path` argument is the full path of the parental tree to this organization unit.
    • The `description` argument is the human readable text description of the organization unit.
    • The `block_inheritance` argument blocks policy setting inheritance from organization units higher in the organization tree.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.CreateOrganizationUnit(String customerId, String orgUnitName, String parentOrgUnitPath, String description, Boolean blockInheritance)
    
    This method returns a `AppsExtendedEntry` object. This method takes the following arguments:
    • The `customerId` argument contains the ID of the Google Apps customer.
    • The `orgUnitName` argument is the organization unit name.
    • The `parentOrgUnitPath` argument is the full path of the parental tree to this organization unit.
    • The `description` argument is the human readable text description of the organization unit.
    • The `blockInheritance` argument blocks policy setting inheritance from organization units higher in the organization tree.

    Updating an Organization Unit

    To update an organization unit use the following method.

    Protocol

    To update an organization unit, send a `PUT` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    PUT https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId/full org unit path
    
    For example, using the CO3az79cb customerId and Partners organization unit in the parent Sales organization unit:
    PUT https://apps-apis.google.com/a/feeds/orgunit/2.0/CO3az79cb/Sales/Partners
    
    Note: If the organization unit's pathnames have HTML reserved characters, use URL-encoding. For more information, see Percent-encoding. The request's new parameters update those created when Creating an Organization Unit:
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <id>https://apps-apis.google.com/a/feeds/customer/2.0/C03az79cb</id>
        <apps:property name="name" value="new organization unit's
    name" />
        <apps:property name="description" value="new organization
    description" />
        <apps:property name="parentOrgUnitPath" value="new parent
    path/organization unit" />
        <apps:property name="blockInheritance" value="true or
    false" />
    </atom:entry>
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements for a new user. This request returns the `orgUnitPath` property:
    <?xml version='1.0' encoding='UTF-8">
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
        <apps:property name="orgUnitPath" value="parent's
    path/organization's unit name" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.updateOrganizationUnit(String customerId, String orgUnitPath, Map<OrgUnitProperty, String> attributes)
    
    This method takes three arguments:
    • The `customerId` argument contains the ID of the Google Apps customer.
    • The `orgUnitPath` argument contains the full path name.
    • The `attributes` argument is a map of OrgUnitProperty and value to be updated. The keys available are:
    • -NAME: The name of the organization unit.
      -PARENT_ORG_UNIT_PATH: The full path of the parental tree to this organization unit.
      -DESCRIPTION: Human readable text description of the organization unit.
      -BLOCK_INHERITANCE: Blocks policy setting inheritance from organization units higher in the organization tree.
      -USERS_TO_MOVE: A comma separated list of email addresses that are to be moved across orgUnits
    This method returns a GenericEntry XML response.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.UpdateOrgUnit(customer_id, org_unit_path, org_unit_entry)
    
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `org_unit_path` argument contains the full path name.
    • The `org_unit_entry` argument contains the updated organization unit.
    This method returns a Python dictionary object.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.UpdateOrganizationUnit(String customerId, String orgUnitPath, IDictionary attributes)
    
    This method takes 3 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUnitPath` argument contains the path to the organization unit.
    • The `attributes` argument contains the set of attributes to update.
    This method returns a `AppsExtendedEntry` object.

    Retrieving Organization Units

    This section gives details on retrieving organization units at three levels: a single unit, all units, and only the immediate children of a unit.

    Retrieving a Single Organization Unit

    To retrieve a single organization unit use the following method

    Protocol

    To retrieve a single organization unit, send a `GET` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveOrganizationUnit(String customerId, String orgUnitPath)
    
    • The `customerId` argument contains the ID of the Google Apps customer.
    • The `org_UnitPath` argument is the full path name of the organization.
    This method returns a GenericEntry XML response.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveOrgUnit(customer_id, org_unit_path)
    
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `org_unit_path` argument is the full path name of the organization.
    This method returns a Python dictionary object.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveOrganizationUnit(String customerId, String orgUnitPath)
    
    • The `customerId` argument contains the ID of the Google Apps customer.
    • The `org_UnitPath` argument is the full path name of the organization.
    This method returns a `AppsExtendedEntry` object.

    Retrieving All Organization Units

    To retrieve all organization units use the following method.

    Protocol

    To retrieve all organization units, send a `GET` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId?get=all
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements. Note the `parentOrgUnitPath` property is an empty String signifying this is the top-level organization unit:
    <feed xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
      <openSearch:startIndex>1</openSearch:startIndex>
      <entry>
        <id>https://apps-apis.google.com/a/feeds/orgunit/2.0/the
    customerId/NA_Sales</id>
    ...
        <apps:property name="name" value="NA_Sales" />
        <apps:property name="description" value="The North America
    sales organization" />
        <apps:property name="orgUnitPath" value="NA_Sales" />
        <apps:property name="parentOrgUnitPath" value="" />
        <apps:property name="blockInheritance" value="false" />
      </entry>
    </feed>
    
    Note: Depending on the size of your organization tree and number of users, retrieving all organizations could return a large amount of data. In these situations, the API "paginates" or breaks the response into pages of a maximum of 100 entries each. The API response will contain an tag for which the rel attribute has a value of next. The URL identified in that tag points to the next page of results for the request. For more information, see Results Pagination.

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveAllOrganizationUnits(String customerId)
    
    This method returns a GenericEntry XML response.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveAllOrgUnits(customer_id)
    
    This method returns a Python dictionary object. To retrieve one page of Organization Units at a time, call the following method.
    ouclient.RetrievePageOfOrgUnits(customer_id, startKey=None)
    

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllOrganizationUnits(String customerId)
    
    This method returns a `AppsExtendedFeed` object.

    The only argument that you need to pass to the method is the customerId that identifies the Google Apps account.

    Retrieving An Organization Unit's Immediate Sub-Organizations

    To retrieve the immediate children of an organization unit, call the following method.

    Protocol

    To retrieve the immediate children of an organization unit, send a `GET` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId?get=children&orgUnitPath=the URL-encoded organization unit's path
    
    Note: For URL-encoding information, see Percent-encoding. A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements:
    <?xml version='1.0' encoding='UTF-8">
    <feed xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <entry>
    <id>https://apps-apis.google.com/a/feeds/orgunit/2.0/C03az79cb/EMEA/Sales&
    lt;/id>
    <updated>2008-10-17T15:02:45.646Z</atom:updated>
    <link rel='self' type='application/atom+xml'
    href='https://apps-apis.google.com/a/feeds/orgunit/2.0/C03az79cb/EMEA/Sales'/>
    ;
        <link rel='edit' type='application/atom+xml'
       
    href='https://apps-apis.google.com/a/feeds/orgunit/2.0/C03az79cb/EMEA/Sales'/>
    ;
        <apps:property name="name" value="Sales" />
        <apps:property name="description" value="The EMEA sales
    organization" />
        <apps:property name="orgUnitPath" value="EMEA/Sales"/>
        <apps:property name="parentOrgUnitPath" value="EMEA" />
        <apps:property name="blockInheritance" value="false" />
    </entry>
    <entry>
     ...
    </entry>
     ...
    </feed>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveChildOrganizationUnits(String customerId, String orgUnitPath)
    
    This method takes 2 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUnitPath` argument contains the path to the organization unit.
    This method returns a `GenericEntry` object.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveSubOrgUnits(customer_id, org_unit_path)
    
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `org_unit_path` argument is the full path name of the organization.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveChildOrganizationUnits(String customerId, String orgUnitPath)
    
    This method takes 2 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUnitPath` argument contains the path to the organization unit.
    This method returns a `AppsExtendedFeed` object.

    Deleting an Organization Unit

    All child organization units and organization users must be deleted before an organization unit can be deleted.

    Protocol

    To delete an organization unit, send a `DELETE` request to the `orgunit` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    DELETE https://apps-apis.google.com/a/feeds/orgunit/2.0/the customerId/the organization unit's path
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient;
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.deleteOrganizationUnit(String customerId, String orgUnitPath)
    
    This method takes 2 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUnitPath` argument contains the path to the organization unit.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.DeleteOrgUnit(customer_id, org_unit_path)
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `org_unit_path` argument is the full path name of the organization.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.DeleteOrganizationUnit(String customerId, String orgUnitPath)
    
    This method takes 2 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUnitPath` argument contains the path to the organization unit.

    Managing Organization Users

    Organization users are arranged into logical and hierarchical organization units:

    • An organization user is a member of only one organization unit.
    • An organization user's pathname is unique. And, an organization user's name property follows the Character Usage naming guidelines.
    • A user has one primary email address which is the email address to use when moving a user from one organization unit to another.
    • Within the account's hierarchy, all policies apply to the user. The policies of the organization unit closest to the user takes precedence for that user.
    • Organization users are moved when their organization unit is moved up or down the account's hierarchy.
    • The data kept in organization user properties can be constantly changing. When making a request, properties returned for an entity are guaranteed to be consistent at the time the entity was retrieved. That is, you will not see "partial" updates. If a retrieval operation returns more than one entity, there is no consistency guarantee across entities. This is especially true when a response spans multiple pages in pagination.

    Creating an Organization User

    Creating an organization user has two steps:

    1. Create a user account as described in the Creating a User Account section.
    2. Move this new user account into the organization hierarchy by updating the new user's organization unit path using Updating an Organization User operation. If you forget to move a new user into an organization, within a few minutes, this user can be found in the Google Apps account's top-level organization. As a general rule, any domain user is in the organization hierarchy.

    Updating an Organization User

    To update an organization user's organization unit, call the following method.

    Protocol

    To update an organization user's organization unit, send a `PUT` request to the `orguser` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    PUT https://apps-apis.google.com/a/feeds/orguser/2.0/the customerId/the organization user's email
    
    For example, using the CO3az79cb customerId and liz@example.com:
    PUT https://apps-apis.google.com/a/feeds/orguser/2.0/CO3az79cb/liz@example.com
    
    Note: If the organization user's username has HTML reserved characters, use URL-encoding. For more information, see Percent-encoding. Below is an example of an update request using the optional `oldOrgUnitPath` property.
    <atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
        <apps:property name="oldOrgUnitPath" value="old
    organization unit path" />
        <apps:property name="orgUnitPath" value="new organization
    unit path" />
    </atom:entry>
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements:
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
        <apps:property name="orgUserEmail" value="liz@example.com"
    />
        <apps:property name="orgUnitPath" value="new_york/hr" />
    </entry>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.updateOrganizationUser(String customerId, String orgUserEmail, String oldOrgUnitPath, String newOrgUnitPath)
    
    This method takes four arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUserEmail` argument contains the email address of the user.
    • The `oldOrgUnitPath` argument contains the path to the old organization unit.
    • The `newOrgUnitPath` argument contains the path to the new organization unit.
    This method returns a `GenericEntry` object.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.UpdateOrgUser(customer_id, user_email, org_unit_path)
    This method takes the following arguments:
    • The `customer_id` argument contains the ID of the Google Apps customer.
    • The `user_email` argument contains the email address of the user.
    • The `org_unit_path` argument is the full path name.

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.UpdateOrganizationUser(String customerId, String orgUserEmail, String newOrgUnitPath, String oldOrgUnitPath)
    
    This method takes 4 arguments:
    • The `customerId` argument uniquely identifies the Google Apps account.
    • The `orgUserEmail` argument contains the email address of the user.
    • The `newOrgUnitPath` argument contains the path to the new organization unit.
    • The `oldOrgUnitPath` argument contains the path to the old organization unit.
    This method returns a `AppsExtendedEntry` object.

    Retrieving Organization Users

    Retrieving a Single Organization User

    To retrieve a single organization user call the following method.

    Protocol

    To retrieve a single organization user, send a `GET` request to the `orguser` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/orguser/2.0/the customerId/organization user's email
    
    Note: If the organization user's username has HTML reserved characters, use URL-encoding. For more information, see Percent-encoding. A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements:
    <?xml version='1.0' encoding='UTF-8">
    <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    ...
        <apps:property name="orgUserEmail" value="liz@example.com"/>
        <apps:property name="orgUnitPath" value="Sales/EMEA_Sales"/>
    </entry>
    
    The Retrieving a Single Organization User operation's parameters are:
    orgUserEmail
    Email address of the organization user. For example, liz@example.com.
    orgUnitPath
    Full path location of the organization user in the organization tree, including the organization unit's name. In the example above, liz@example.com is in the EMEA_Sales organization unit whose parent is the Sales organization unit.

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveOrganizationUser(String customerId, String orgUserEmail)
    
    This method returns a `GenericEntry` object.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveOrgUser(customer_id, user_email)
    

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveOrganizationUser(String customerId, String orgUserEmail)
    
    This method returns a `AppsExtendedEntry` object.

    This method takes 2 arguments:

    • The customerId argument uniquely identifies the Google Apps account.
    • The orgUserEmail argument contains the email address of the user.

    Retrieving All Organization Users

    To retrieve all organization users, call the following method.

    Protocol

    To retrieve all organization users, send a `GET` request to the `orguser` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating Requests:
    GET https://apps-apis.google.com/a/feeds/orguser/2.0/the customerId?get=all
    
    A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements:
    <?xml version='1.0' encoding='UTF-8'?>
    <feed xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
      <entry>
        <apps:property name="orgUserEmail" value="liz@example.com"
    />
        <apps:property name="orgUnitPath" value="new_york/hr" />
      </entry>
      <entry>
     ...
      </entry>
     ...
    </feed>
    
    Note: Depending on the size of your organization tree and number of users, retrieving all users could return a large amount of data. In these situations, the API "paginates" or breaks the response into pages of a maximum of 100 entries each. The API response will contain an tag for which the rel attribute has a value of next. The URL identified in that tag points to the next page of results for the request. For more information, see Results Pagination.

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveAllOrganizationUsers(String customerId)
    
    This method returns a `GenericEntry` object.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveAllOrgUsers(customer_id)
    
    To retrieve one page of Organization Units at a time, call the following method.
    import gdata.apps.organization.service
    ...
    ouclient = gdata.apps.organization.service.OrganizationService(email=email, domain=domain, password=password)
    ouclient.ProgrammaticLogin()
    ouclient.RetrievePageOfOrgUsers(customer_id, startKey=None)
    

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllOrganizationUsers(String customerId)
    
    This method returns a `AppsExtendedFeed` object.

    The only argument that you need to pass to the method is the customerId that identifies the Google Apps account.

    Retrieving An Organization Unit's Immediate Sibling Users

    To retrieve the immediate sibling users in a user's organization unit, call the following method.

    Protocol

    To retrieve the immediate sibling users in a user's organization unit, send a `GET` request to the `orguser` feed's URI. For the `customerId`, see Retrieving a customerId. Include the Authorization header as described in Authenticating to your Domain. This example is for the new_york/hr organization unit:
    GET https://apps-apis.google.com/a/feeds/orguser/2.0/the customerId?get=children&orgUnitPath=the URL-encoded full organization unit path
    
    Note: For URL-encoding information, see Percent-encoding. A successful response returns an HTTP `200` status code found in the Google Data API HTTP status codes documentation. Along with the status code, the response returns an AtomPub entry with the `entry` elements:
    <?xml version='1.0' encoding='UTF-8">
    <feed xmlns:atom='http://www.w3.org/2005/Atom'
    xmlns:apps='http://schemas.google.com/apps/2006'>
    <entry>
    ...
        <apps:property name="orgUserEmail" value="liz@example.com"/>
        <apps:property name="orgUnitPath" value="Sales/EMEA_Sales"/>
    </entry>
    <entry>
     ...
    </entry>
     ...
    </feed>
    

    Java

    import sample.appsforyourdomain.labs.provisioning.OrgManagementSampleClient; 
    ...
    OrgManagementSampleClient orgUnitClient = new OrgManagementSampleClient(adminEmail, adminPassword, domain, appName); 
    orgUnitClient.retrieveAllOrganizationUsersByOrgUnit(String customerId, String orgUnitPath)
    
    This method returns a `GenericEntry` object.

    Python

    import gdata.apps.organization.client
    ...
    ouclient = gdata.apps.organization.client.OrganizationUnitProvisioningClient(domain=domain)
    ouclient.ClientLogin(email=email, password=password, source ='apps')
    ouclient.RetrieveOrgUnitUsers(customer_id, org_unit_path)
    

    .NET

    using Google.GData.Apps;
    ...
    OrganizationService service = new OrganizationService(domain, applicationName);
    service.setUserCredentials(userName, password);
    service.RetrieveAllOrganizationUsersByOrgUnit(String customerId, String orgUnitPath)
    
    This method returns a `AppsExtendedFeed` object.

    This method takes 2 arguments:

    • The customerId (customer_id in Python) argument uniquely identifies the Google Apps account.
    • The orgUnitPath (org_unit_id in Python) argument contains the path to the organization unit.

    Deleting an Organization User

    Deleting the user account deletes the organization user. Follow the instructions in the Deleting a User Account section.

    Methods for Handling Errors

    Identifying Errors in API Responses

    When the Provisioning API can't successfully handle your request, it returns one of the GData Error Codes in the XML response. If you are using a client library, you can get these error codes using the methods described in this section.

    Java

    The Java client library will throw an `AppsForYourDomainException` when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an `AppsForYourDomainException`, we recommend that you call the `getErrorCode` method on that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an `AppsForYourDomainException` in the Provisioning API:
    try {
    // Some API actions
    } catch (AppsForYourDomainException e) {
    if (e.getErrorCode() == AppsForYourDomainErrorCode.EntityDoesNotExist ) {
    // Do some post-error processing or logging.
    }
    }
    

    Python

    The Python client library will throw an `AppsForYourDomainException` when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an `AppsForYourDomainException`, we recommend that you call the `e.error_code` method on that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an `AppsForYourDomainException` in the Provisioning API:
    try:
    
    """ Some API actions """
    
    except gdata.apps.service.AppsForYourDomainException , e:
    print e # or process the exception in some other way
    

    .NET

    The .NET client library will throw an `AppsException` when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log an `AppsException`, we recommend that you access the `ErrorCode` property of that object to determine the type of error that the Provisioning API returned. The sample code below demonstrates how you would catch an `AppsException` in the Provisioning API:

    try
    {
    // Some API actions
    }
    catch (AppsException e)
    {
    if (e.ErrorCode == AppsException.EntityDoesNotExist)
    {
    // Do some post-error processing or logging.
    }
    }
    

    PHP

    The PHP client library will throw a `ServiceException` when it receives an error response from the Provisioning API. Other types of exceptions may also be thrown for other types of errors. To process or log a `ServiceException`, retrieve the error array by calling the `$e->getErrors()` method, then calling `$error->getErrorCode()` or `$error->getReason()` on each element of that array to determine the type of errors that the Provisioning API returned. The presence of individual error codes can also quickly be determined by calling `$e->hasError($errorCode)`. The sample code below demonstrates how you would catch a `ServiceException` in the Provisioning API:
    try{
    // Some API actions
    } catch (Zend_Gdata_Gapps_ServiceException $e) {
    if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
    // If this is an ENTITY_DOES_NOT_EXIST error, return null
    return null;
    }
    else {
    // Outherwise, just print the errors that occured and exit
    foreach ($e->getErrors() as $error) {
    echo "Error encountered: {$error->getReason()} ({$error->getErrorCode()})\n"
    }
    exit();
    }
    }
    

    A complete list of error codes is provided in GData Error Codes.

    Authentication required

    You need to be signed in with Google+ to do that.

    Signing you in...

    Google Developers needs your permission to do that.