Last updated July 14, 2009 (see recent changes)
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, nicknames, and groups.
Note: The Provisioning API is only available to Google Apps Premier Edition and Google Apps Education Edition customers. To enable the API, log in to your admin account, and click the Users and groups tab. Then click the Settings subtab, 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.)
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.)
|
Setup Managing User Accounts |
Managing Groups New!
Creating a Group
Updating a Group Retrieving a Group Deleting a Group Sample GroupEntry Request Sample GroupFeed Response Managing Group Members New! |
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.
Go to the home page for Google Apps and follow the instructions to sign up for Google Apps Premier Edition (for your enterprise) or Google Apps Education Edition (for your school).
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.
Complete the form to provide information about your organization and yourself to Google.
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.
Complete the signup process using Google Checkout.
Complete the form to set up your admin account.
Follow the instructions to verify that you own your domain.
Use the email address and password 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.
All of your API requests must be sent over HTTPS. Each API request that you send needs to contain an authentication token, which Google will use to authorize access to the operation specified in the API request. Authentication tokens are only available to users who have administrative rights in your domain, and those tokens only authorize operations within your domain.
The ClientLogin Interface provides additional information about programmatically logging users into their accounts.
To obtain an authentication token, submit an HTTP POST request to the following URL:
The following guidelines apply to the request:
The POST body needs to include a string in the following format:
You will need to make the following changes to this string:
Replace the string <email_address> with the email address for your admin account.
Replace the string <password> with the password for that account.
The email address and password values must be URL-encoded. For example, the URL-encoded form of the email address apps.test.account@example.com is apps%2Etest%2Eaccount%40example%2Ecom.
The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.
Google will return a response containing your authentication token in response to your POST request. The authentication token will be the Auth value on that page, and you need to extract the token from the page. When you submit an API request, you must set the Content-type and Authorization headers as shown in the example below.
Content-type: application/atom+xml Authorization: GoogleLogin auth=your-authentication-token
Note: Authentication tokens expire after 24 hours. As such, you will need to submit a request to the above URL at least once every 24 hours. We recommend that you keep the token in memory rather than writing it to a file. If you encounter a CAPTCHA challenge while obtaining an authentication token, the knowledge base provides instructions on how you can handle it.
The following Perl script demonstrates how to make an HTTP POST request for an authentication token.
#! /usr/bin/perl -w use strict; use LWP::UserAgent; # Create an LWP object to make the HTTP POST request my $lwp_object = LWP::UserAgent->new; # Define the URL to submit the request to my $url = 'https://www.google.com/accounts/ClientLogin'; # Submit the request with values for the Email, Passwd, # accountType and service variables. my $response = $lwp_object->post( $url, [ 'accountType' => 'HOSTED', 'Email' => 'admin_email@example.com', 'Passwd' => 'admin_password', 'service' => 'apps' ] ); die "$url error: ", $response->status_line unless $response->is_success; # Extract the authentication token from the response my $auth_token; foreach my $line (split/\n/, $response->content) { if ($line =~ m/^Auth=(.+)$/) { $auth_token = $1; last; } } print "authentication token is $auth_token\n";
Note that to use this code, you need to replace the Email and Passwd values with the email address and password for your hosted admin account.
All create and update requests – POST and PUT requests – also require you to submit an XML document that contains the information needed to fulfill the request. The content should be sent using the application/atom+xml content type. The XML Request Formats are explained in this document.
Note: If your query rate for provisioning requests is too high, you might receive HTTP 503 responses from the API server indicating that your quota has been exceeded. If you get these responses, use an exponential back-off algorithm to retry your requests (with examples of how to do exponential backoff). For best results, parallelize operations across different groups, rather than adding or removing lots of members to one group simultaneously.
To create a user account, use the following POST request in your XML document:
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 not available to everyone. Your agreement will indicate whether this feature is available for your domain. 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 UserEntry 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="123$$abc" suspended="false"/> <apps:quota limit="2048"/> <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.
Typically, the suspended attribute of the <apps:login> tag only appears in update requests. (By default, newly created accounts are active.)
To retrieve a specific user account, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/domain/user/2.0/(userName)
To retrieve all of the users in a domain, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/domain/user/2.0
To update a user account, use the following PUT request in your XML file:
PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
To rename a user, use the following PUT request in your XML file:
PUT https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
<?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/OldUserName</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#user"/> <atom:title type="text">OldUserName</atom:title> <atom:link rel="self" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/OldUserName"/> <atom:link rel="edit" type="application/atom+xml" href="https://apps-apis.google.com/a/feeds/example.com/user/2.0/OldUserName"/> <apps:login userName="NewUserName" 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>
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.
Note: Google Talk will lose all remembered chat invitations after renaming. The user must request permission to chat with friends again. Also, when a user is renamed, the old username is retained as a nickname to ensure continuous mail delivery in the case of email forwarding settings and will not be available as a new username. To remove the nickname, you should issue an HTTP DELETE to the nicknames feed after renaming.
To delete a user account, use the following DELETE request:
DELETE https://apps-apis.google.com/a/feeds/domain/user/2.0/userName
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</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>
When you submit a request to retrieve all users for a domain, 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 client libraries translate this feed into a UserFeed object, which contains a series of UserEntry objects.
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</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="2048"/> <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="2048"/> <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>
To create a nickname, use the following POST request in your XML file:
POST https://apps-apis.google.com/a/feeds/domain/nickname/2.0
To retrieve a particular nickname, use the following GET request in your XML file:
POST https://apps-apis.google.com/a/feeds/domain/nickname/2.0
To retrieve all nicknames for a particular user, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/domain/nickname/2.0?username=userName
To delete a nickname, use the following DELETE requrest in your XML file:
DELETE https://apps-apis.google.com/a/feeds/domain/nickname/2.0/nickname
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.
Note: This XML format contains all of the data that can be stored in a NicknameEntry 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#nickname"/> <apps:nickname name="Susy-1321"/> <apps:login userName="SusanJones-1321"/> </atom:entry>
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" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/> </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" suspended="false" admin="false" changePasswordAtNextLogin="false" agreedToTerms="true"/> </atom:entry> </atom:feed>
To create a group, use the following POST request in your XML file:
POST https://apps-apis.google.com/a/feeds/group/2.0/domain
To update a group, use the following PUT request in your XML file:
PUT https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId
To retrieve all the groups for a particular member, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain/?member=memberId[&[directOnly=]]
To retrieve all groups in a particular domain, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain[?[start=]]
To delete a group, use the following DELETE request in your XML file:
DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId
Note: Deleting a group does not delete the member user accounts.
The following HTTP request types have been deprecated in this release:
| Operation | HTTP Request Type and URL |
|---|---|
| Create Email List | POST https://apps-apis.google.com/a/feeds/domain/emailList/2.0 (Deprecated) |
| Retrieve Email List | GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName (Deprecated) |
| Retrieve All Email Lists in Domain | GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0 (Deprecated) |
| Retrieve All Email List Subscriptions for an Email Address | GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0?recipient=emailAddress (Deprecated) |
| Delete Email List | DELETE https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName (Deprecated) |
The following XML shows a sample request to create a group. The XML uses the "groupName" to specify the name of the group.
<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="groupId" value="us-sales"></apps:property> <apps:property name="groupName" value="US Sales"></apps:property> <apps:property name="description" value="United States Sales Team"></apps:property> <apps:property name="emailPermission" value="emailPermission"></apps:property> </atom:entry>
A newly created group does not have any subscribers. emailPermission is one of the following:
When you submit a request to create, retrieve, or update a group, the Provisioning API returns an XML response that identifies the group. The client libraries translate this response into a Group object. Following a request to create a group, this object does not serve any purpose except to confirm that the request was successful.
The XML below shows a sample API response for a request to create a group.
<atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales</atom:id> <atom:link rel="self" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales"/> <atom:link rel="edit" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales"/> <apps:property name="groupId" value="us-sales"></apps:property> <apps:property name="groupName" value="us-sales"></apps:property> <apps:property name="description" value="UnitedStatesSalesTeam"></apps:property> <apps:property name="emailPermission" value="Domain"></apps:property> </atom:entry>
When you submit a request to retrieve all groups for a domain or all groups to which a particular user subscribes, the Provisioning API returns an Atom XML feed containing a list of groups, each of which is identified in an <atom:entry> XML block. The client libraries translate this feed into a series of Group objects.
The XML below shows a sample API response for a request to retrieve all groups 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/">
<atom:id>https://www.google.com/a/feeds/group/2.0/example.com</atom:id>
<atom:updated>2008-12-03T16:33:05.260Z</atom:updated>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="http://schemas.google.com/g/2005#feed"></atom:link>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="http://schemas.google.com/g/2005#post"></atom:link>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com" type="application/atom+xml" rel="self"></atom:link>
<openSearch:startIndex>1</openSearch:startIndex>
<atom:entry>
<id>https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com</id>
<atom:updated>2008-12-03T16:33:05.261Z</atom:updated>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com" type="application/atom+xml" rel="self"></atom:link>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales%40example.com" type="application/atom+xml" rel="edit"></atom:link>
<apps:property name="groupId" value="us-sales@example.com"></apps:property>
<apps:property name="groupName" value="US Sales"></apps:property>
<apps:property name="emailPermission" value="Anyone"></apps:property>
<apps:property name="description" value="United States Sales Team"></apps:property>
</atom:entry>
<atom:entry>
<atom:id>https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com</atom:id>
<atom:updated>2008-12-03T16:33:05.260Z</atom:updated>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com" type="application/atom+xml" rel="self"></atom:link>
<atom:link href="https://apps-apis.google.com/a/feeds/group/2.0/example.com/Staff-2435%40example.com" type="application/atom+xml" rel="edit"></atom:link>
<apps:property name="groupId" value="Staff-2435@example.com"</apps:property>
<apps:property name="groupName" value="Staff 2435"</apps:property>
<apps:property name="emailPermission" value="Anyone"</apps:property>
<apps:property name="description" value=""></apps:property>
</atom:entry>
<atom:entry>
...
</atom:entry>
</atom:feed>
To add a member to a group, use the following POST request in your XML file:
POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member
Note: If you add a group as a member of another group, there may be a delay of up to 10 minutes before the child group's members appear as members of the parent group.
To retrieve all members of a group, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member[?[start=]]
To retrieve a particular member of a group, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId
To remove a group member, use the following DELETE request in your XML file:
DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/member/memberId
The following HTTP request types have been deprecated in this release:
| Operation | HTTP Request Type and URL |
|---|---|
| Add Address to Email List | POST https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/ (Deprecated) |
| Retrieve All Subscribers to Email List | GET https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/ (Deprecated) |
| Remove Address from Email List | DELETE https://apps-apis.google.com/a/feeds/domain/emailList/2.0/emailListName/recipient/emailAddress (Deprecated) |
The following XML shows a sample request to add a member to a group. The XML uses the "memberId" to specify the email address of a member.
<?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="memberId" value="susanjones@example.com"/>
</atom:entry>
Or, if you are adding a member that is itself a group, use the following 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"
xmlns:gd='http://schemas.google.com/g/2005">
<apps:property name="memberId" value="us-sales@example.com"/>
</atom:entry>
When you submit a request to add an email address to a group, the Provisioning API returns an XML response that identifies the newly added address. Following a request to add an address to a group, this object does not serve any purpose except to confirm that the request was successful.
The XML below shows a sample API response for a request to retrieve a particular member in a given group.
<atom:entry> <atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com</atom:id> <atom:link rel="self" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <atom:link rel="edit" type="application/atom+xml" href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/> <apps:property name="memberId" value="suejones@example.com"/> <apps:property name="memberType" value="User"/> <apps:property name="directMember" value="true"/> </atom:entry>
When you submit a request to retrieve all subscribers for a group, the Provisioning API returns an Atom XML feed identifying a list of member, each of which is identified in an atom:entry XML block. The client libraries translate this response into an MemberFeed object, which contains a list of Member objects.
The XML below shows a sample API response for a request to retrieve all members of a group.
<?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/">
<atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member</atom:id>
<atom:link rel="https://schemas.google.com/g/2005#feed" type="application/atom+xml"
href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member"/>
<openSearch:startIndex>1</openSearch:startIndex>
<atom:entry>
<atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com</atom:id>
<atom:link rel="self" type="application/atom+xml"
href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/>
<atom:link rel="edit" type="application/atom+xml"
href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/suejones%40example.com"/>
<apps:property name="memberId" value="suejones@example.com"/>
<apps:property name="memberType" value="User"/>
<apps:property name="directMember" value="true"/>
</atom:entry>
<atom:entry>
<atom:id>https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com</atom:id>
<atom:link rel="self" type="application/atom+xml
href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com"/>
<atom:link rel="edit" type="application/atom+xml
href="https://www.google.com/a/feeds/group/2.0/example.com/us-sales/member/ca-sales%40example.com"/>
<apps:property name="memberId" value="ca-sales@example.com"/>
<apps:property name="memberType" value="Group"/>
<apps:property name="directMember" value="true"/>
</atom:entry>
<atom:entry>
...more entries...
</atom:entry>
</atom:feed>
To add an owner to a group, use the following POST request in your XML file:
POST https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner
Note: Adding an owner to a group does not add the user to the member's feed.
To retrieve an owner of a particular group, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail
To retrieve all of the owners of a group, use the following GET request in your XML file:
GET https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner
To remove an owner from a group, use the following DELETE request in your XML file:
DELETE https://apps-apis.google.com/a/feeds/group/2.0/domain/groupId/owner/ownerEmail
The following XML shows a sample request to add an owner to a group. 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>