1. Audience
2. How the API Works
   1. XML Tag Definitions
   2. Results Pagination
3. GDATA Error Codes
4. Client Library Methods

Audience

Google Apps allows website administrators to offer a variety of personalized and co-branded 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 email groups.

It's a reference document; it assumes that you understand the concepts presented in the Developer's Guide, and the general ideas behind the Google data APIs protocol.

How the API Works

To execute an operation using the API, you need to submit an HTTP POST, GET, PUT or DELETE request to the URL that corresponds to the operation that you wish to perform. Each URL includes variables that identify your domain and, possibly, the resource that you are creating, retrieving, updating or deleting. For example, to retrieve information about the us-sales group in the example.com domain, you would submit an HTTP GET request to the following URL:

https://apps-apis.google.com/a/feeds/group/2.0/example.com/us-sales

The tables in the subsections below identify the URLs associated with each API operation. The tables also identify the type of HTTP request associated with each API request.

• Creating, Retrieving, Updating, and Deleting User Accounts
• Creating, Retrieving, Updating, and Deleting Nicknames
• Creating, Retrieving, Updating, and Deleting Groups
• Adding, Retrieving, and Removing Group Members
• Adding, Retrieving, and Removing Group Owners

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 section in the Developer's Guide explains those XML structures and provides samples for each.

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 exopnential backoff). For best results, parallelize operations across different groups, rather than adding or removing lots of members to one group simultaneously.

Creating, Retrieving, Updating and Deleting User Accounts

Creating, Retrieving and Deleting Nicknames

Creating, Retrieving, Updating, and Deleting Groups

Adding, Retrieving, and Removing Group Members

Adding, Retrieving, and Removing Group Owners

Results Pagination

If your API request produces a UserFeed, NicknameFeed, Property name response, the Provisioning API will return an Atom XML feed containing a maximum of 100 entries. If there are more than 100 entries in the feed, the API response will contain an <atom:link> tag for which the rel attribute has a value of next. The URL identified in that <atom:link> tag points to the next page of results for the request. If your API request produces a GroupFeed, MemberFeed, or OwnersFeed, the Provisioning API will return an Atom XML feed containing a maximum of 200 entries.

In the XML excerpt below, the <atom:link> tag that identifies the next page of results is highlighted in bold text:

<?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"/>
...

The time to complete requests to retrieve all users, nicknames, groups, members, or owners of a group will directly relate to the amount of data being retrieved. For example, if a group has 100 subscribers, the client library can obtain a complete subscriber list with a single HTTP request. However, if a group has 1,000 members, you must make 5 HTTP requests to obtain the full member list.

Note:If your API request produces a GroupFeed, MemberFeed, or OwnersFeed, the Provisioning API will return an Atom XML feed containing a maximum of 200 entries.

• If you are using the Java, .NET, PHP, or Python client library, the code provides you with the option of explicitly requesting additional pages of results or automatically requesting additional results until all results have been obtained. For example, the retrievePageOfUsers method makes a single HTTP request for up to 100 users or (200 group members), and the retrieveAllUsers method will automatically issue additional HTTP requests until all results have been obtained.

• If you write your own code to process API responses, you will need to ensure that your code requests additional pages of results as necessary.

XML Tag Definitions

This section contains definitions of the XML tags used in Provisioning API requests and responses.

Subtags Legend

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:

GData Error Codes

The following list (ordered by error code number) explains the different error codes that you may receive in a Google Apps XML response.

• UnknownError(1000) - The request failed for an unknown reason.

• ServerBusy(1001) - The server is busy and it could not complete the request.

• UserDeletedRecently(1100) - The request instructs Google to create a new user but uses the username of an account that was deleted in the previous five days.

• UserSuspended(1101) - The user identified in the request is suspended.

• DomainUserLimitExceeded(1200) - The specified domain has already reached its quota of user accounts.

• DomainAliasLimitExceeded(1201) - The specified domain has already reached its quota of aliases. Aliases include nicknames and email lists.

• DomainSuspended(1202) - Google has suspended the specified domain's access to Google Apps.

• DomainFeatureUnavailable(1203) -  This particular feature is not available for the specified domain.

• EntityExists(1300) - The request instructs Google to create an entity that already exists.

• EntityDoesNotExist(1301) - The request asks Google to retrieve an entity that does not exist.

• EntityNameIsReserved(1302) - The request instructs Google to create an entity with a reserved name, such as "abuse" or "postmaster".

• EntityNameNotValid(1303) - The request provides an invalid name for a requested resource.

• InvalidGivenName(1400) - The value in the API request for the user's first name, or given name, contains unaccepted characters. Learn more about accepted characters for this field.

• InvalidFamilyName(1401) - The value in the API request for the user's surname, or family name, contains unaccepted characters. Learn more about accepted characters for this field.

• InvalidPassword(1402) - The value in the API request for the user's password contains an invalid number of characters or unaccepted characters. Learn more about accepted characters for this field.

• InvalidUsername(1403) - The value in the API request for the user's username contains unaccepted characters. Learn more about accepted characters for this field.

• InvalidHashFunctionName(1404) - The specified query parameter value is not valid.

• InvalidHashDigestLength(1405) - The specified password does not comply with the specified hash function.

• InvalidEmailAddress(1406) - The specified email address is not valid.

• InvalidQueryParameterValue(1407) - The specified query parameter value is not valid.

• InvalidSsoSigningKey(1408) - The specified signing key is not valid.

• TooManyRecipientsOnEmailList(1500) - The request instructs Google to add users to an email list, but that list has already reached the maximum number of subscribers (1000).

• TooManyNicknamesForUser(1501) - The request instructs Google to add a nickname to an email address, but that email address has already reached the maximum number of nicknames.

• DuplicateDestinations(1601) - The destination specified has already been used.

• TooManyDestinations(1602) - The maximum number of destinations has been reached.

• InvalidRouteAddress(1603) - The routing address specified is invalid.

• GroupCannotContainCycle(1700) - A group cannot contain a cycle.

• InvalidDomainEdition(1800) - The domain edition is not valid.

• InvalidValue(1801) - An value specified is not valid.

Client Library Methods

The following table lists the function, input parameters, and return values for the GDATA Provisioning API.

Back to top