Google Workspace API: Guide for HRIS Integration and Automation

Getting Started with Google Workspace API

The Google Workspace Directory API enables administrators to programmatically manage user accounts, relationships, and organizational data within a Google Workspace domain.

This guide focuses exclusively on the Users API, and gives the technical depth required to sync data.

Authentication and Secure Access

OAuth 2.0 Scopes

Google APIs use the OAuth 2.0 protocol for authentication and authorization. Here are the steps:

1. Obtain OAuth 2.0 credentials from the Google API Console.

2. Obtain an access token from the Google Authorization Server.

3. Examine scopes of access granted by the user: The Users API requires domain-wide delegation with these scopes:

<https://www.googleapis.com/auth/admin.directory.user>
<https://www.googleapis.com/auth/admin.directory.user.readonly>

4. Send the access token to an API.

5. Refresh the access token, if necessary.

‍

Deep Dive into Google Workspace Directory API Endpoints

Users Management Endpoints

The Google Workspace Directory API provides a range of endpoints that allow developers to manage employee data.

Here are the most commonly used endpoints, along with practical use cases.

1. GET /admin/directory/v1/users

• Description: Retrieves a paginated list of either deleted users or all users in a domain.
• cURL Request:

curl \
  'https://admin.googleapis.com/admin/directory/v1/users?maxResults=25&pageToken=[NEXT_PAGE_TOKEN]&key=[YOUR_API_KEY]' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --compressed

• Page Token Parameter:  A token that indicates the specific page of results you want. You get this token from the response of a previous request. Replace [NEXT_PAGE_TOKEN] with the actual token returned in the previous response.
• Use Case: Obtain employee data of an organization from Google Workspace into your system.

‍

2. GET /admin/directory/v1/users/{userKey}

• Description: Retrieves a user by unique identifier.
• cURL Request:

curl \
'https://admin.googleapis.com/admin/directory/v1/users/[USERKEY]?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--header 'Accept: application/json' \
--compressed

• Use Case: Obtain a specific employee’s data from Google Workspace into your system.

‍

3. POST /admin/directory/v1/users

• Description: Creates a user.
• cURL Request:

curl --request POST \
  'https://admin.googleapis.com/admin/directory/v1/users?key=[YOUR_API_KEY]' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

• Use Case: Automate employee onboarding directly from an Applicant Tracking System (ATS).

‍

Pagination and Rate limits

Pagination Patterns

When fetching large datasets, such as employee records, Directory API uses pagination to make requests more manageable.

Here’s how you can implement pagination:

next_page_token = None
while True:
    response = service.users().list(
        customer='my_customer',
        maxResults=500,
        pageToken=next_page_token
    ).execute()
    
    users = response.get('users', [])
    process_users(users)  # Your processing function
    
    next_page_token = response.get('nextPageToken')
    if not next_page_token:
        break

‍

Rate Limits

You cannot create more than 10 users per domain per second using the Directory API.

Exceeding this limit will result in a 429 code response rateLimitExceeded error. Implement an exponential backoff strategy to retry requests after a brief delay:

from time import sleep  

def safe_user_insert(user_data):  
    retries = 0  
    while retries < 5:  
        try:  
            return service.users().insert(body=user_data).execute()  
        except googleapiclient.errors.HttpError as e:  
            if e.resp.status in [500, 503]:  
                sleep(2 ** retries + random.random())  
                retries += 1  
            else:  
                raise  
    raise Exception("Max retries exceeded")  

Here is an exhaustive article that highlights the Directory API: Limits and Quotas.

‍

Troubleshooting Guide

Common Error Codes

Here is an exhaustive article that highlights the Directory API: Limits and Quotas.

‍

Missing AdminDirectory Service (Apps Script)

Error: ReferenceError: AdminDirectory is not defined

Solution:

1. Enable Admin SDK service:

Resources > Advanced Google Services > Enable Admin Directory API

2. Add OAuth scope in manifest:

"oauthScopes": ["<https://www.googleapis.com/auth/admin.directory.user>"]

‍

Get Started With with Google Workspace API Using Bindbee

Integrating with Google Workspace shouldn’t feel like a battle.But for most teams, it ends up being a major time sink—draining valuable engineering resources.

Why put your developers through the grind when Bindbee can get you live with Google Workspace in just minutes?

Setting up Google Workspace connector with Bindbee

• Sign up with Bindbee and navigate to the dashboard.
• Create a Connector:
  • Click on Create Connector from the dashboard.
  • Select HRIS as the type of integration. Enter customer details and give your connector a unique ID (e.g., Google_Workspace_Integration).
• Generate a Magic Link:
  • After setting up the connector, click Create Link to generate a magic link. This will allow the customer to authenticate the connection with Google Workspace.
  • Open the link and enter the necessary credentials. This step establishes the connection between Google Workspace and Bindbee.
• Sync the Connector:
  • Once the connection is made, the connector will begin syncing data from BambooHR. This may take a few minutes depending on the size of the data. You can track the sync status in the connector section.
• Access the Synced Data:
  • After syncing, go to the Employee section in the Bindbee dashboard and select Get Employees to retrieve employee data from BambooHR.
• Get the API Key and Connector Token:
  • Copy the API key and the x-connector-token from the Bindbee dashboard, which you will need to make authenticated API requests.

‍

Retrieving Employee Data with Bindbee

Once the Google Workspace data has been synced, you can retrieve employee data on to your application via the Bindbee API.

Here’s a step-by-step process for accessing synced data from BambooHR through Bindbee’s unified API:

1. Request Setup:
   • Use the Bindbee API to send a request for employee data. You’ll need both your Bindbee API token and the x-connector-token.
2. Example  cURL Request:

curl --request GET \
  --url https://api.bindbee.com/hris/v1/employees \
  --header 'Authorization: Bearer YOUR_BINDBEE_API_KEY' \
  --header 'x-connector-token: YOUR_CONNECTOR_TOKEN'

This request will return a list of employee objects, including details like the employee’s first name, last name, job title, department, and contact information.

1. Sample Response:

{
  "items": [
    {
      "id": "018b18ef-c487-703c-afd9-0ca478ccd9d6",
      "first_name": "Kunal",
      "last_name": "Tyagi",
      "job_title": "Chief Technology Officer",
      "department": "Engineering",
      "work_email": "kunal@bindbee.co"
    }
  ]
}

Bulk Employee Data Retrieval

For retrieving large datasets, Bindbee simplifies the process by allowing you to fetch bulk employee data from BambooHR.

The pagination feature helps manage large responses by returning results in pages.

• Pagination Parameters:
  • Use the cursor and page_size parameters to navigate through the results. By default, Bindbee returns 50 records per page.
  • Example of a paginated request:

url = "https://api.bindbee.com/hris/v1/employees?cursor=MDE4YjE4ZWYtYzk5Yy03YTg2LTk5NDYtN2I3YzlkNTQzM2U1&page_size=50"
response = requests.get(url, headers=headers)

• Querying for Specific Employee Data:
  • You can further refine your request by filtering based on specific fields, such as manager_id, remote_id, or company_id to get employees under a particular manager or company.

‍

Say hello to Bindbee.

Book a demo with our experts today.