Jul 19, 2024

Fetch all Employee Details from Rippling API


This article is a part of a series of articles covering the Rippling API in depth, and covers the specific use case of using the Rippling API to Fetch all Employee Details from Rippling API.
You can find all the other use cases we have covered for the Rippling API along with a comprehensive deep dive on its various aspects like authentication, rate limits etc here.

Fetch all Employee Details from Rippling API

Step 1: Get Current User Information

First, retrieve the current user information to ensure you have the correct access token and company ID.

import requests

url = "https://api.rippling.com/platform/api/me"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"

response = requests.get(url, headers=headers)
current_user = response.json()
company_id = current_user['company']

Step 2: Fetch All Employees Including Terminated

Next, use the company ID to fetch all employees, including terminated ones. Ensure pagination for optimal performance.

def fetch_employees(company_id, limit=100, offset=0):
    url = "https://api.rippling.com/platform/api/employees/include_terminated"
    headers = {
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    params = {
        "EIN": company_id,
        "limit": limit,
        "offset": offset
    response = requests.get(url, headers=headers, params=params)
    return response.json()

employees = []
offset = 0
while True:
    batch = fetch_employees(company_id, limit=100, offset=offset)
    if not batch:
    offset += 100

Step 3: Extract Required Employee Details

Finally, extract the first name, last name, email ID, and manager name for each employee.

employee_details = []
for employee in employees:
    details = {
        "first_name": employee.get("firstName"),
        "last_name": employee.get("lastName"),
        "email_id": employee.get("workEmail"),
        "manager_name": None
    manager_id = employee.get("manager")
    if manager_id:
        manager_response = requests.get(f"https://api.rippling.com/platform/api/employees/{manager_id}", headers=headers)
        manager = manager_response.json()
        details["manager_name"] = manager.get("name")


Knit for Rippling API Integration

For quick and seamless access to Rippling data, the Knit API offers a convenient solution. By integrating with Knit just once, you can streamline the entire process. Knit takes care of all the authentication, authorization, and ongoing integration maintenance, this approach not only saves time but also ensures a smooth and reliable connection to your Rippling data.

Jul 19, 2024

Get All Employees Details from Freshteam API


This article is a part of a series of articles covering the Freshteam API in depth, and covers the specific use case of using the Freshteam API to Get All Employees Details from Freshteam API.
You can find all the other use cases we have covered for the Freshteam API along with a comprehensive deep dive on its various aspects like authentication, rate limits etc here.

Get All Employees Details from Freshteam API


To retrieve the first name, last name, email ID, and employee ID of all employees from the Freshteam API, you can use the GET /api/employees endpoint. This endpoint allows you to list all employees and filter the response based on various query parameters.

Step-by-Step Guide

1. Set Up Authentication

Ensure you have your Freshteam API key. You will need to include this key in the authorization header of your requests.

2. Make the API Request

Use the GET /api/employees endpoint to retrieve the list of employees. You can filter the response using query parameters if needed.

3. Extract Required Information

From the response, extract the first name, last name, email ID, and employee ID of each employee.

Python Code Snippet
import requests

# Define the API endpoint and headers
url = "https://.freshteam.com/api/employees"
headers = {
    "accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"

# Make the API request
response = requests.get(url, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    employees = response.json()
    for employee in employees:
        first_name = employee.get('first_name')
        last_name = employee.get('last_name')
        email_id = employee.get('official_email')
        employee_id = employee.get('employee_id')
        print(f"First Name: {first_name}, Last Name: {last_name}, Email ID: {email_id}, Employee ID: {employee_id}")
    print(f"Failed to retrieve employees: {response.status_code}")

Knit for Freshteam API Integration

For quick and seamless access to Freshteam data, the Knit API offers a convenient solution. By integrating with Knit just once, you can streamline the entire process. Knit takes care of all the authentication, authorization, and ongoing integration maintenance, this approach not only saves time but also ensures a smooth and reliable connection to your Freshteam data.

Jul 9, 2024

Workday API Integration Guide (In-Depth)

Workday unlocks a powerful HR ecosystem, but integrating it with your existing tools can be complex. endeavor. This guide empowers developers to navigate those challenges and unlock the full potential of Workday integrations.

Benefits of Workday API Integration: 

  • Streamlined Workflows: Automate data exchange, saving HR professionals valuable time and boosting efficiency.
  • Real-Time Business Insights: Gain access to a unified view of your data, enabling data-driven decisions for business leaders.
  • Scalability and Flexibility: Integrate new applications as your needs evolve, ensuring your systems grow with your organization.

While this guide equips developers with the skills to build robust Workday integrations through clear explanations and practical examples, the benefits extend beyond the development team. You can also expand your HRIS integrations with the Workday API integration and automate tedious tasks like data entry, freeing up valuable time to focus on other important work. Business leaders gain access to real-time insights across their entire organization, empowering them to make data-driven decisions that drive growth and profitability. This guide empowers developers to build integrations that streamline HR workflows, unlock real-time data for leaders, and ultimately unlock Workday's full potential for your organization.

Overview of Workday

Ever wondered why Gartner named Workday  Leader for Cloud ERP for Service-Centric Enterprise and why top companies use it. Workday is a cloud-based enterprise management platform designed to simplify workforce management. From HR to Payroll to finance and analytics processes, all in one integrated system. Workday Integration API streamlines data exchange, enabling seamless integration between Workday and external systems.

Importance of Integrating with Workday

  1. Streamlined Processes: Manual data entry is a persistent challenge, but it can be very well tackled by Workday. It automates workflows, minimizes errors, and reduces manual data entry.
  2. Real-Time Data Sync: Real-time synchronization of data via integration helps improve decision-making.
  3. Enhanced Analytics and Reporting: Deeper insights into business performance is the heart of growth for an organization, which Workday can easily help you with.
  4. Scalability and Flexibility: Workday can scale with your needs, which allows easy addition of new features as per our requirements. 


The most basic requirement is to authenticate your Workday account. Proper authentication ensures secure and reliable access to Workday's APIs. 

To ensure a secure and reliable connection with Workday's APIs, this section outlines the essential prerequisites. These steps will lay the groundwork for a successful integration, enabling seamless data exchange and unlocking the full potential of Workday within your existing technological infrastructure.

  1. Workday Tenant Setup: Workday tenant (it is an instance of the Workday software) and its credentials such as name, username and password.
  2. API Access Configuration: Once the Workday tenant is set up, you will need to enable API access in it. It includes configuring API clients in workday system, appropriate security roles need to be assigned and also generating API Keys or tokens is necessary.
  3. OAuth 2.0 Authentication: Secured authentication is always necessary, therefore, Workday supports OAuth 2.0. You will just need to register your application in the Workday system to obtain client ID and client secret. Then just use these credentials to request access tokens, which are required for making API calls.

Preliminary Setup

Integrating with Workday requires a solid initial setup to ensure an easygoing process. Here are the steps:-

Setting Up a Developer Account with Workday

  1. Unlock Your Workday Resources: Sign up for a Worday developer account.
  2. Secure Your API Calls: Obtain API credentials (client ID & secret) to authenticate your application. Think of them as a secure handshake for API access.
  3. Define Granular Permissions: Create an Integration System User (ISU) within Workday Security. Assign this user the minimum permissions required to interact with the APIs your integration needs. This keeps things secure and avoids unauthorized access.
  4. Detailed Setup Steps: Refer to the "Implementation Guidelines" section for configuration instructions.

Overview of Workday API Documentation

1. API Types: Workday offers REST and SOAP APIs, which serve different purposes. REST APIs are commonly used for web-based integrations, while SOAP APIs are often utilized for complex transactions.

2. Endpoint Structure: You must familiarize yourself with the Workday API structure as each endpoint corresponds to a specific function. A common workday API example would be retrieving employee data or updating payroll information. You can find a comprehensive listing of the Workday API endpoints and directory here.

3. API Documentation: Workday API documentation provides a comprehensive overview of both REST and SOAP APIs. 

  • Workday REST API: The REST API allows developers to interact with Workday's services using standard HTTP methods. It is well-documented and provides a straightforward way to integrate with Workday.

  • Workday REST API Documentation: Workday's REST API documentation provides detailed information on using the API, including endpoints, parameters, and response formats. It is a valuable resource for developers looking to integrate with Workday.

  • Workday SOAP API Documentation: Workday's SOAP API documentation provides information on how to use the SOAP API for more complex transactions. SOAP APIs are often used for integrations that require a higher level of security and reliability.

  • Workday SOAP API Example: An example of using Workday's SOAP API could be retrieving employee information from Workday's HR system to update a payroll system. This example demonstrates the use of SOAP APIs for complex transactions.


Accessing Workday Sandbox

  1. Safe Testing: A sandbox creates a secure testing environment to avoid risks in production.
  2. Mimics Production: Configure the sandbox to mirror your real Workday environment with test data.
  3. Validates Integration: Test your integration's functionality within the sandbox, ensuring data exchange works as expected.
  4. Early Issue Detection: Identify and resolve any problems with your integration before impacting real data.
  5. Detailed Setup Steps: Refer to the "Setting Up and Using a Workday Sandbox" section for configuration instructions.

Important Terminology 

Understanding key terms is essential for effective integration with Workday. Let’s look upon few of them, that will be frequently used ahead - 

Workday Tenant: Imagine your Workday tenant as your company’s own secure vault within the workday system. It’s a self-contained environment, and it will contain all your company’s data and configuration. Companies typically have separate tenants for development, testing, and production.

Integration System User (ISU): An ISU is a user account in Workday specifically designed for integrations to access and manipulate data. Setting up an ISU involves creating the user, assigning security roles, and generating API credentials.

For more detailed information, you can refer to the official Workday documentation:

- Workday Tenant Overview

- Setting Up an ISU

Authentication and Authorization

Secure access in Workday integrations plays a crucial role in protecting sensitive employee and financial data. It ensures compliance with regulations and prevents unauthorized changes that could disrupt business functions. 

By implementing strong security measures, you safeguard data, adhere to legal standards, and maintain business stability.

To achieve this, follow these essential steps for your Workday integration: 

  1. Prep Your Workday Base: Ensure access to your Workday tenant, your company’s secured data zone.
  2. ISU : Create an ISU with specific permissions to access Workday APIs.
  3. Authentication : Use Workday’s built-in OAuth 2.0 to exchange credentials for an access token (your temporary pass) and get our ISU Username and Password.
  4. Test Playground (Sandbox): Develop and test your integration in the safe sandbox environment.
  5. Deployment (Production): Once tested, deploy to the production environment for real-world use.

Authentication Lingo:

Workday offers different authentication methods. Here, we'll focus on OAuth 2.0, a secure way for applications to gain access through an ISU (Integrated System User).  An ISU acts like a dedicated user account for your integration, eliminating the need to share individual user credentials.

Security Best Practices:

  1. Store Secrets Safely: Keep sensitive info like client secrets in environment variables, not in your code.
  2. Encryption is Key: Encrypting credentials for added protection is a must for integration.
  3. Rotate Regularly: Keep changing credentials periodically to reduce risk.
  4. Least Privilege: Assign the ISU only the minimum permissions needed.

SOAP vs. REST: Picking the Right Workday API for the Job

Choosing between SOAP and REST for your Workday integration can feel incredibly challenging. Let's break it down to help you decide:

The Structured Side: SOAP

  1. Security First: SOAP's rigid rules guarantee iron-clad reliability and top-notch security. Perfect for handling sensitive stuff like payroll.
  2. Extensible Powerhouse: Need extra security layers? SOAP's got your back with WS-Security. 
  3. Precise Communication: WSDL acts like a detailed contract, ensuring your app and Workday are always on the same page.

Working with SOAP:

  1. Grab the WSDL: This file is your roadmap to Workday's SOAP services, telling you everything available. You can find the WSDL documentation on the Workday community site.
  2. Craft Your Requests: Tools like SOAP UI let you send requests with authentication and data, following the WSDL specs.

The Flexible Friend: REST

  1. Simplicity is King: REST keeps things easy with standard HTTP verbs (GET, POST, PUT, DELETE) you already know and love.
  2. Stateless Speed: No need to sweat past requests – each one has everything the server needs. Plus, REST is generally faster due to its lightweight design.
  3. JSON Advantage: Responses are typically in JSON, a human-readable format that your application can easily understand.

Working with REST:

  1. Talk HTTP: Use familiar HTTP methods to interact with Workday's resources.
  2. Hit the Endpoints: Access Workday's REST endpoints directly using their URLs. You can find the REST API documentation for your specific Workday version on the Workday community site.  Tools like Postman are great for testing requests.

Pick what you need : 

  1. Performance Matters: SOAP's complex structure can lead to slower speeds. For web applications, REST's lightweight design is a clear winner.
  2. Use Cases in Mind: High-security transactions and complex operations like payroll are a perfect fit for SOAP. For web apps and simple data access, REST is the way to go.

Use Cases:

  • SOAP: Best for scenarios requiring high security, transactional reliability, and complex operations (e.g., financial transactions, payroll).
  • REST: Ideal for web and mobile applications, simpler integrations, and scenarios needing quick, lightweight data access.

When you need a feature-rich environment that empowers developers for complex tasks, SOAP is the ideal choice (and the one I opted for in this guide).

Performing Basic Operations with Workday APIs

Let's proceed to utilize Workday HCM APIs effectively. We'll walk through creating a new employee and fetching a list of all employees – essential building blocks for your integration.

Constructing a SOAP Request Body

SOAP requests follow a specific format and use XML to structure the data. Here's an example of a SOAP request body to fetch employees using the Get Workers endpoint:








                <wsse:Username>{ISU USERNAME}</wsse:Username>

                <wsse:Password>{ISU PASSWORD}</wsse:Password>





        <bsvc:Get_Workers_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v40.1">




SOAP requests use XML to structure data. They have a main envelope containing a header and a body. The header includes authentication details, while the body specifies the function being called (e.g., Get Workers) and any parameters it needs.

Creating a New Employee: Hire Employee API

Let's add a new team member. For this we will use the Hire Employee API! It lets you send employee details like name, job title, and salary to Workday. Here's a breakdown:

  1. What it Does: Adds a new employee to your Workday system.
  2. What it Needs: Employee details like name, job information.

Let's Code (cURL Example):

curl --location 'https://wd2-impl-services1.workday.com/ccx/service/{TENANT}/Staffing/v42.0' \

--header 'Content-Type: application/xml' \

--data-raw '<soapenv:Envelope xmlns:bsvc="urn:com.workday/bsvc" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">













        <bsvc:Hire_Employee_Request bsvc:version="v42.0">












                                        <bsvc:ID bsvc:type="ISO_3166-1_Alpha-3_Code">USA</bsvc:ID>








                            <bsvc:Email_Address_Data bsvc:Delete="false" bsvc:Do_Not_Replace_All="true">


                                <bsvc:Usage_Data bsvc:Public="true">

                                    <bsvc:Type_Data bsvc:Primary="true">


                                            <bsvc:ID bsvc:type="Communication_Usage_Type_ID">WORK</bsvc:ID>









                    <bsvc:ID bsvc:type="Position_ID">P-SDE</bsvc:ID>








1. We use `curl` to send a POST request (because we're creating something new).

2. The URL points to the specific Workday endpoint for hiring employees.We include our tenant name in the URL to point the API to our corresponding tenant.

3. We include the ISU Username and Password in the <wsse:Security> header in the SOAP envelope to authenticate our API call

4. The `Content-Type` header specifies we're sending xml data.

5. The actual employee data goes in the request body, including details like first name, position, work email.



xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="string">

<bsvc:Employee_Reference bsvc:Descriptor="string">

<bsvc:ID bsvc:type="ID">EMP123</bsvc:ID>



If everything goes well, you'll get a success message and the ID of the newly created employee!

Fetching All Employees: Get Workers API

Now, if you want to grab a list of all your existing employees. The Get Workers API is your friend!

  1. What it Does: Retrieves a list of all employees in your Workday system.
  2. What it Needs: Your ISU username and password
  3. Where it's Used: The Workday Get Workers API is part of the Workday Developer API suite, which allows developers to interact with Workday's Human Capital Management (HCM) system programmatically. These APIs are commonly used for integrating Workday data and functionality into other applications and systems.

Below is workday API get workers example: 

Let's Code (cURL Example):

curl --location 'https://wd2-impl-services1.workday.com/ccx/service/{TENANT}/Human_Resources/v40.1' \

--header 'Content-Type: application/xml' \

--data '<soapenv:Envelope












        <bsvc:Get_Workers_Request xmlns:bsvc="urn:com.workday/bsvc" bsvc:version="v40.1">












This is a simple GET request to the Get Workers endpoint. 


1. The URL points to the specific Workday endpoint for retrieving employees.We include our tenant name in the URL to point the API to our corresponding tenant.

2. We include the ISU Username and Password in the <wsse:Security> header in the SOAP envelope to authenticate our API call

3. The `Content-Type` header specifies we're sending xml data.

4. We include the Count and Page Number parameters in the request to paginate the results. This technique can be used to optimize the results so that we process a batch of data at once. 


<?xml version='1.0' encoding='UTF-8'?>

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">


        <wd:Get_Workers_Response xmlns:wd="urn:com.workday/bsvc" wd:version="v40.1">













                                    <wd:Name_Detail_Data wd:Formatted_Name="Logan McNeil" wd:Reporting_Name="McNeil, Logan">


                                            <wd:ID wd:type="WID">bc33aa3152ec42d4995f4791a106ed09</wd:ID>

                                            <wd:ID wd:type="ISO_3166-1_Alpha-2_Code">US</wd:ID>

                                            <wd:ID wd:type="ISO_3166-1_Alpha-3_Code">USA</wd:ID>

                                            <wd:ID wd:type="ISO_3166-1_Numeric-3_Code">840</wd:ID>








                                <wd:Address_Data wd:Effective_Date="2008-03-25" wd:Address_Format_Type="Basic" wd:Formatted_Address="42 Laurel Street&amp;#xa;San Francisco, CA 94118&amp;#xa;United States of America" wd:Defaulted_Business_Site_Address="0">


                                <wd:Phone_Data wd:Area_Code="415" wd:Phone_Number_Without_Area_Code="441-7842" wd:E164_Formatted_Phone="+14154417842" wd:Workday_Traditional_Formatted_Phone="+1 (415) 441-7842" wd:National_Formatted_Phone="(415) 441-7842" wd:International_Formatted_Phone="+1 415-441-7842" wd:Tenant_Formatted_Phone="+1 (415) 441-7842">








This JSON array gives you details of all your employees including details like the name, email, phone number and more.

Setting Up and Using a Workday Sandbox

To avoid risking any glitches in production, isn’t it amazing to first test our code on test data?  A sandbox is your safe zone to test your code before takeoff. As we already had a summarized view of the importance of using sandbox in our preliminary steps, let’s move to detailed steps to execute these steps.


  1. Request Your Sandbox:  Talk to your Workday admin and request a sandbox environment (specify the type you need).
  2. Prep Your Sandbox: Log in and configure your sandbox to mimic your production environment (company data, user roles).
  3. Create an ISU: In Security, create a special user (ISU) for your integration testing. Assign it the necessary permissions.
  4. Secure Your Calls: Register your application in the sandbox to get unique credentials (client ID & secret) for secure API calls.
  5. Test : Use tools like Postman to bombard your integration with test requests within the sandbox. Iron out any wrinkles before going live.
  6. Monitor & Debug: Keep an eye on your sandbox and use Workday logs to identify and fix any issues.

PECI: Streamline Your Workday Payroll

PECI (Payroll Effective Change Interface): lets you transmit employee data changes (like new hires, raises, or terminations) directly to your payroll provider, slashing manual work and errors. 



Web Services

Data Flow


Inbound and Outbound

Use Cases

READ (Employee data updates like new hires, raises or terminations)

CREATE, UPDATE, DELETE (Any CRUD operation on employee data)

Country Specificity

Up to 3 similar countries


Multi-Geography Support

Requires multiple PECI syncs (manual setup)

Single integration works for all geographies

Setup Complexity

Requires Workday expertise

Can be programmatic (easier setup)

Let's get started :-

  1. Enable PECI:  Talk to your Workday admin and get PECI activated for your tenant. 
  2. Set Up Your Payroll Provider:  Configure your external payroll system within Workday, including details and data transfer protocols.
  3. Define Your Data:  Identify the specific data your payroll provider needs (think employee details, compensation, etc.).
  4. Create an ISU: Just like other integrations, create a special user (ISU) with permissions to access and move payroll data.
  5. Transform Your Data:  Set up Workday to transform your data into the format your payroll provider expects. Think of it as translating languages!
  6. Schedule Transfers: Automate the process! Set up a schedule to regularly send payroll changes to your provider (e.g., daily or after each payroll run).
  7. Test It Out:  Before going live, use the Workday sandbox to thoroughly test the PECI integration. Make sure all changes get sent correctly.
  8. Monitor & Maintain: Keep an eye on things! Regularly monitor the integration and use Workday's reports to track data transfers and fix any errors.

Implementation Guidelines

Follow the detailed step-by-step process below to integrate with Workday.

Step-by-step Integration Process.

  1. Register for a Developer Account:  Sign up for a Workday developer account and get verified.
  2. Explore Workday's API Playground:  Get familiar with Workday API endpoints and resources. Download the API docs – they'll be your roadmap.
  3. Craft Your Integration System User (ISU):  Head to Workday Security and create a special ISU for your integration. Don't forget to assign it the permissions it needs to access the API.
  4. Secure Your Credentials:  Register your application within Workday to get a unique client ID and secret (like a secret handshake) for secure API calls.  Store these credentials safely!
  5. Go OAuth 2.0:  Set up OAuth 2.0 to securely connect your integration to Workday. Use your client ID and secret to obtain access tokens, which act as temporary passes for making API calls.
  6. Develop & Test Like a boss:  Use tools like Postman to test your API calls before going live.  Build your integration using the correct endpoints and data models. Make sure everything works as expected.
  7. Monitor & Maintain:  Keep an eye on your integration – implement logging and monitoring for API calls.  Review and update your integration settings as needed.

Security Matters:

  1. Craft Security Groups:  In Workday Security, create a security group specifically tailored for your integration.  Think of it as a club with specific access rules.
  2. Assign Permissions Wisely:  Add the necessary permissions to your security group.  Make sure your ISU has access to everything it needs, but nothing it doesn't.
  3. Set Up Security Policies:  Define security policies to control how data can be accessed and modified.  Assign these policies to your security group for an extra layer of protection.
  4. Activate & Audit:  Activate your newly defined security policies and regularly review their effectiveness.  Conduct security audits to ensure everything is running smoothly.

Common Hiccups & How to Fix Them:

  1. Facing Authentication Errors?  Double-check your OAuth setup – make sure your client ID, secret, and redirect URLs are all correct.
  2. Permission Denied?  Verify that your ISU has the necessary permissions and is assigned to the right security group.
  3. Data Not Matching Up?  Check your data mappings to ensure they align perfectly with Workday's data models.
  4. Fixing Your Issues:  If you run into authentication errors, adjust your OAuth configuration.  For permission issues, update permissions for the ISU and security groups.  And for data mismatches, correct your data transformations and mappings.

Common Pitfalls and Troubleshooting

Getting stuck with errors can be frustrating and time-consuming. Although many times we face errors that someone else has already faced, and to avoid giving in hours to handle such errors,We have put some common errors below and solutions to how you can handle them. 

Error Diffusion Toolkit:

  1. Authentication Woes: Error Message:  "Invalid client ID or secret."  Defuse:  Double-check your OAuth setup. Are your client ID, secret, and redirect URLs all correct?  Ensure your tokens aren't expired!
  2. Permission Denied: Error Message:  "Access denied!"  Defuse:  Verify your ISU has the right permissions. Check security group settings and policies. It might not have the key to the data vault!
  3. Data Mismatch Blues: Error Message:  "Incorrect or missing data fields."  Defuse:  Ensure your data mappings are on point and match Workday's data model. Validate your input data before making those API calls. Garbage in, garbage out!
  4. Rate Limiting Roadblock: Error Message:  "Whoa there! Too many requests!"  Defuse:  Implement throttling and retry logic in your integration. Respect Workday's API rate limits – don't be a data hog!

Pro Tips for Smooth Sailing:

  1. Log It All: Use detailed logs for API calls and responses. Logs are like breadcrumbs – they help you find your way back when you get lost. 
  2. Sandbox First: Always test in Workday's sandbox environment. Catch issues early on before your code goes live and wreaks havoc on real data.
  3. Monitor Your Performance: Keep an eye on your integration's performance. Use monitoring tools to track API response times and error rates. Don't let errors become silent assassins!
  4. The Power of Community: Connect with the Workday developer community. Forums and user groups can be lifesavers – share your war stories and learn from others' battles.

How can Knit help you with Workday Integration?

We know you're here to conquer Workday integrations, and at Knit (rated #1 for ease of use as of 2024!), we're here to help! Over 9,500 organizations have already used Knit for Workday integrations. Knit, as a unified HRIS API, ensures a high ROI for companies that seek to integrate their diverse HRIS applications to make their HR processes effective without sinking their organizational budgets.

Why Knit? We Speak Your Language:

  1. Unified APIs: Our APIs are like a Rosetta Stone for Workday – perform multiple integrations with just one set. Less code, less complexity, happy developer!
  2. Developer Friendly: We make things easy. Our APIs are clear, concise, and well-documented. No wrestling with cryptic instructions here.
  3. Rock-Solid Reliability: Robust error handling and comprehensive documentation ensure a smooth integration experience. We've got your back!
  4. Support When You Need It: Our crack support team is here to answer your questions and help you troubleshoot any issues. 
  5. Unified Integration Platform: We handle both SOAP and REST APIs, so you don't have to worry about the underlying protocol. Knit takes care of the complexities, allowing you to focus on building your integration


A. Key Terms

  • API:  Lets applications talk to Workday (RESTful or SOAP).
  • Authentication: Verifies you're who you say you are (login).
  • Authorization: Grants access to specific Workday data (permissions).
  • Client ID & Secret:  Uniquely identify your application (secure handshake).
  • Data Model:  Structure of Workday data (like fields in a form).
  • Endpoint:  Specific URL to access Workday functions (like a door to a room).
  • ISU:  Special user for integrations (low access, high security).
  • OAuth 2.0:  Secure way to get temporary access tokens (like a one-time pass).
  • REST API:  Flexible API using regular commands (GET, POST, PUT, DELETE).
  • Sandbox:  Test environment with dummy data (safe zone for experimentation).
  • SOAP API:  Structured API using XML (more complex, more secure).
  • Token:  Temporary permission to access Workday (like a short-term pass).
  • Workday Tenant:  Your company's secure space within Workday (separate for dev, test, production).

B. Sample Code

  • Adapted from Workday API documentation. Remember to replace placeholders like "your_workday_tenant", "isu_username", “isu_password” with your actual details. For comprehensive API reference and code samples, visit the Workday Developer Center

Jul 9, 2024

ADP API Integration Guide (In-Depth)

Overview of ADP

Automatic Data Processing (ADP) is a cloud-based software that provides services that cover all needs in human resource information systems (HRIS). Whether your company needs to manage payroll, hire new employees, track employee performance, calculate taxes, manage benefit information such as health insurance and retirement plans, or attract your employees to complete training on time, it has everything covered. The ADP system remains updated with all the latest HR regulations, so outdated information is not an issue here.

Managing payroll and HR manually can lead to many issues, such as high probability of manual data entry errors, issues due to duplicate data entry, difficulty of keeping up with changing labor laws and regulations is time-consuming and difficult which may also lead to compliance issues. Handling consistent payroll accurately for the employees can be challenging at times.

ADP API integration not just tackles these issues, but makes the process efficient so you can work on tasks that are more important.

Importance of ADP Integration

  1. Improved Efficiency and Automation: Automating tasks such as onboarding, offboarding, and status changes eliminates manual data entry errors, saving HR teams significant time.
  2. Real Time Data Sync & Streamlined Processes : Connecting ADP with other applications can automate workflows like payroll and benefits administration, and data flows between ADP and other systems reduce inconsistency by providing access to accurate employee information.
  3. Ensure Compliance : ADP takes care of latest labor laws. By integrating with ADP, you can ensure that you are HR practices are complaint.
  4. Simplify Complex Processes : Some processes are tedious and challenging like consistent payroll management, ADP automates payroll calculations ensuring accuracy and timely payments for all employees.

Developer Primer

This guide gets you started with the entire process of ADP API integration covering prerequisites, authentication, use case for this guide, operations, testing, deployment and troubleshooting—all the essentials.

You will find more about ADP API, use cases, endpoints in ADP API Events and Endpoints.

There are various modules for which ADP provides APIs for integration, you can find your specific use case for integration in ADP API Documentation.

In case you are looking for a quick and easy way to build your ADP API integration along with multiple other HRIS an payroll systems in one go, checkout Knit. Knit provides a unified HRIS API covering the ADP API along with 40+ other HRIS & Payroll connectors.

Prerequisites & Initial Steps

Setting Up ADP Developer Account

  • As a developer, you will register for a developer account. Your employer will have to provide you access for that. 
  • You will get your self-service registration code from your HR department or payroll administrator. 
  • You can now enter your registration code ADP registration page. If you already have an account with ADP, you can directly log in with your user ID and password login page.

Prerequisites for Obtaining Credentials & Setting Up Authentication

It is important that we establish a secure connection before we start our ADP API integration process. It involves the following: 

  • Obtain Credentials: You will need credentials like client ID, client secret and CSR.
  • Authentication: Understanding authentication process for API Integration is essential.

Use of Sandbox & Postman

It’s important to test your integration before making it live. You can use sandbox and postman.

The safe environment of sandbox will allow you to refine your integration wherever changes are needed, with sample data and thus not affecting your real data without risking security. 

Important Terminology & Use Case for This Guide

ADP Workforce Now API

  • ADP Workforce Now is a cloud based Human Capital Management (HCM) platform that streamlines HR processes from comprehensive reporting and analytics to payroll, benefits administration, payroll and much more. It works on a monthly subscription model.
  • ADP Workforce Now subscribers benefit from streamlined data flow between payroll and other HR functions, reducing manual data entry errors. 
  • Another benefit of ADP Workforce Now, is it integrates with other HR business applications and has flexible service options.
  • Being in the market from past 70 years and serving more than 90,000 clients, ADP has its strong base when it comes to needs related to overall HR management.
  • For this guide, we will focus on API integration with ADP Workforce Now subscription.


  • REST (Representational State Transfer) API is standardized software architecture style, which is used for communication between client and server. A few benefits of REST APIs are: some text
    • They are simple and standardized
    • They are scalable and stateless
    • The performance stays very high, and it supports caching.
  • ADP REST API uses event-based pattern for resource management. Retrieving resources (GET API), modifying resources (POST API) and staying informed by setting up alerts whenever there is a change in GET/POST requests.

API Integration Methods

There are three methods to integrate ADP Payroll Integration API: 

  1. Pre-built Data Connector: It is an available solution that can reduce development time, providing pre-configured settings and user-friendly interface ensuring faster setup.
  2. Customized Integration: If integration needs are very specific, requiring complete control over functionality and data, and have very specific security requirements, then customized integration is the best choice.
  3. Building own Integration for Workforce Now From Scratch: In this integration, you will directly integrate ADP Payroll API (likely the Payroll Data Input API v1) with your system. It requires higher development expertise.

ADP Integration Methods

Getting Started With ADP Payroll API

For this guide, we will work on building our own integration for ADP Workforce Now APIs for payroll. You will find several solutions under the Payroll Management section. ADP offers APIs for Earnings, Deductions, Tax Withholdings, and Payroll Results.

Getting Started With ADP HR API

We will also look into integration for ADP Workforce Now APIs for HR. APIs in HR are divided into various sections such as Workers, Workers Lifecycle, Data Integration Management, Workers Demographics, Compensation Management, Business Communication Management, and additional HR modules.

Obtain API Credentials & Set Up Authentication

Client Credentials

Follow the below steps to get client credentials:

  • ADP Marketplace Account: You will need to register for an ADP Marketplace account on registration page if you already don't have one.
  • Application Creation : Once registered, log in to your account and create a new application for your ADP API integration.some text
    • Define application name, description, target ADP Product (in our case Workforce Now), type of integration (ex: Data Integration).
  • Retrieve Credentials : In the application, find development API credentials.

All About CSR (Certificate Signing Request)

  • CSR is specifically required if you plan to use a client certificate for mutual TLS authentication with the ADP API server. In that case, you can generate it using OpenSSL Library. Specific commands to run on the command line, can be found OpenSSL Documentation.
  • The most common authentication method for Workforce Now API integrations involves OAuth 2.0. This will require a Client ID and Client Secret, which we can get by following this section.

OAuth 2.0 Authorization Flow & Access Tokens for Authorization.

  1. OAuth 2.0 Authorization Flow: Get Authorization Server URL from ADP Payroll Data Input API v1 documentation. Now your application will send a request with Client ID, Client Secret (Secure), and User Consent (if applicable). Upon user consent accepted (if asked), you will be redirected to a URL with an authorization code. 
  2. Access tokens for authorization : Now your application sends another request to Authorization Server URL with: Client ID, Client Secret (Secure), and Authorization Code (if applicable). The server responds an access token for authorized API access. 

Now this token can be used while accessing API of ADP Workforce Now resource server, by including token in authorization header.

Performing Basic Operations

Response & Request Exchange

  • API Endpoints: Specific endpoints for various operations (such as GET/POST) are provided in the ADP developer documentation for the Payroll Data Input API v1.
  • Request Response Exchange Format: The medium for communication between application and the ADP servers is JSON (JavaScript Object Notation). Request and Response data will be exchanged using JSON format.
  • You can check Sample Response JSON for [GET] /events/payroll/v1/pay-data-input.modify/meta Pay Data Input ADP Doc.
  • Note : You will need to enter the access token obtained from the OAuth 2.0 flow in the authorization header.

Setting Up Development Environment for Integration

  • Choose your development language: You can select any programming language and development environment as per your comfort (e.g., Python, Java, etc.).
  • Install libraries: Installation of necessary libraries or frameworks for making HTTP requests and handling JSON data is a must (e.g., requests library in Python).

Implementing ADP Payroll API Integration

Get API Credentials

You can get API Credentials that are Client ID and Client Secret by following this section. Once you have the API credentials, we can move on to the next step to understand the data structure, necessary for integration.

Data Mapping and Transformation for Integration Adaption

  • Review Data Structures: Review the data structures provided in the ADP API documentation and compare them to your own internal data structures.
  • Transformation Logic: If there are discrepancies, implement logic to transform your data to match the ADP API format before sending requests (e.g., converting dates or formatting names).
  • For Example : Pay Data Input - [Pay Data Input Modify] section
    [POST] /events/payroll/v2/worker-general-deduction-instruction.changesome text
    • Request JSON

 "events": [


      "data": {

        "eventContext": {

          "worker": {

            "associateOID": "{{employeeAOID}}"


          "payrollInstruction": {

            "payrollGroupCode": {

              "codeValue": "{{payrollGroupCode}}",

              "shortName": "94N"


            "payrollFileNumber": "{{payrollFileNumber}}",

            "payrollAgreementID": "{{payrollAgreementID}}",

            "itemID": "169749147863_1",

            "generalDeductionInstruction": {

              "deductionCode": {

                "codeValue": "M"





        "transform": {

          "effectiveDateTime": "2020-05-08",

          "payrollInstruction": {

            "generalDeductionInstruction": {

              "inactiveIndicator": true,

              "deductionRate": {

                "rateValue": "20"









Response JSON with status code 200

  "events": [


      "data": {

        "eventContext": {

          "worker": {

            "associateOID": "G34YJ69EMRR7N4VJ"


          "payrollInstruction": {

            "payrollGroupCode": {

              "codeValue": "94N",

              "shortName": "94N"


            "payrollFileNumber": "4567",

            "payrollAgreementID": "CC1_169737547546",

            "itemID": "169749147863_1",

            "generalDeductionInstruction": {

              "deductionCode": {

                "codeValue": "M"





        "transform": {

          "effectiveDateTime": "2020-05-08",

          "payrollInstruction": {

            "generalDeductionInstruction": {

              "inactiveIndicator": true,

              "deductionRate": {

                "rateValue": "20"









Basic Read, Write API Calls 

  • API Endpoints: In this documentation you will find various payroll management APIs. You will also get data formats for the desired operations (e.g., reading employee information, updating pay elements).
  • Construct Requests: Construct HTTP requests using the provided endpoints and request formats (typically JSON). Include the access token in the authorization header.
  • Parse Responses: Parse the JSON response data from the ADP API and handle it according to your needs.
  • In summary of the endpoint documentation of API you want to integrate, you will find important details for writing APIs like method path, content type, token type, and required scope.
  • For example : some text
    • Worker Pay Distributions - [Change Pay Distribution] section has one POST & GET API. 
    • [GET] /events/payroll/v1/worker.pay-distribution.change/meta : some text
      • Optional parameters : ADP-Acting-SessionID , Sm_transactionid, SiteMinder transaction ID, $filter
    • [POST] /events/payroll/v1/worker.pay-distribution.change : some text
      • Optional parameters : ADP-Acting-SessionID, sm_transactionid

Implementing ADP HR API Integration

Follow Similar Steps to Payroll

  • The steps to get API Credentials : Client ID and Client Secret can be found in this section
  • After getting the API Credentials, you can check for the API you are looking for ADP API Explorer.
  • For this guide, we will go ahead with Workers APIs of HR section. The worker's management section, looks into how application can manage and access information about the workers in ADP Workforce Now application.
  • One section of Workers is ‘Workers Data Retrieval’ and you can use the Workers v2 API to generate a full list of workers in your organization. It contains three GET request for retrieval of either single or collection of workers.

Examples of Read, Write API Calls With Data Transformation for HR API

Below are a few endpoints and information related to them : 

  • [GET] /hr/v2/workers some text
    • Optional parameters : $skip, $top, ADP-Acting-SessionID, $filter, $select, $count, sm_transactionid.
  • [POST] /events/hr/v1/worker.photo.uploadsome text
    • Optional parameters : ADP-Acting-SessionID , sm_transactionid

Response :

  "events": [


      "data": {

        "transform": {

          "worker": {

            "photo": {

              "nameCode": {

                "shortName": "photo",

                "longName": "photo"


              "links": [


                  "href": "/hr/v2/workers/G310YGK80NSS9D2N/worker-images/photo",

                  "mediaType": "image/jpg",

                  "method": "GET"





          "effectiveDateTime": null



      "links": []




Important Last Steps: Testing and Deployment

Testing API in Sandbox.

  • ADP Sandbox Environment: Testing API in sandbox before making it live is important for several reasons such as : some text
    • Performance Check & Safety :When you test your integration with fake data, you ensure your real data is safe, and you can also check the performance of your API. If you find that the integration is slow, you can optimize your integration before deployment.
  • Error detection: While testing in the sandbox you can easily catch bugs and other error early on, thus fixing them before deployment to the live environment.
  • Simulate Scenarios: Sandbox environment very well mimic the live environment, and thus it gives a clear picture of how your integration will behave in live environment.

Testing API in Postman

  • API Testing: It provides a user-friendly interface, where you can easily test your GET, POST, PUT API’s request and response exchanges. This helps you get more clear picture of what get missed in your request and response and thus can lead to quick fixes.
  • Automation: One widely used feature of Postman is automated test cases, reducing repeated actions of testing API behavior and thus reducing chances of human error.
  • Collaboration: Postman allows team members to access same API collections, allowing your team to test API’s ensuring everyone is on same page.

Deployment Initiation of API’s

  • Deployment Strategy: Your deployment strategy depends on your environment in which you have built the integration and other needs specific to your integration. 
  • Configuration Management: It is always a good practice to use configuration management tools, this ensures fewer chances of bugs in production (e.g., development, staging, production).
  • Security Measures: Security should not be compromised, ensure security by implementing necessary security measures during deployment, for example: restricting access to sensitive data and APIs.

Troubleshooting and Support

Common Errors and Their Resolutions

  • 401 Unauthorized: You are likely to receive this error due to issues with your access token. Check the following again:some text
    • Client ID and Client Secret: Chances can be that they got expired or are wrong, ensure they are correct and haven't expired.
    • OAuth 2.0 Flow: If you have more than one application in your marketplace, it is easy to get access token of wrong application, verify you’ve obtained valid access token.
    • Token Expiration: Access tokens are temporary and expires in minutes or hours (for security purposes). Refresh them before they expire.
    • 403 Forbidden: You will face this error when your application lacks the necessary permissions to access specific data or perform actions.
    • Review API Scopes: Incomplete permissions for your application are very common issues faced by developers.
  • 400 Bad Request: This indicates a problem with your request structure or data.some text
    • Data Validation: Most of the time you will receive specific error messages regarding the data format or missing required fields.
    • API Endpoints: Ensure you're using the correct API endpoint URL for the desired operation.
  • 4xx or 5xx Errors: These can indicate various issues on the ADP server side.some text
    • ADP Documentation: Refer to the ADP documentation for specific error code meanings and suggested resolutions.

Common Debugging Techniques

  • Logging: It is always a good idea to do logging, it captures request/response details to track integration flow.
  • Breakpoints: Sometimes errors can be logical, step through code to identify such errors.
  • Network Inspection: Verify requests and responses using network tools.
  • Postman: Isolating and testing APIs can be very useful in finding errors when you are working with a complex integration.
  • ADP Support: If any of above doesn’t work, you can seek help from ADP Developer support.

Ensure Integration Smoothness

Integration Smoothness depends upon how well you are aware of issues you are facing while integration, if the issues are standard you will mostly be able to find their resolution in this section.

If you face specific errors, you can reach out to ADP developer support for clarification on error messages encountered during testing or deployment.


A. Key Terms

  • API: Lets applications talk to Workday (RESTful or SOAP).
  • Authentication: Verifies you're who you say you are (login).
  • Authorization: Grants access to specific Workday data (permissions).
  • Client ID & Secret: Uniquely identify your application (secure handshake).
  • Endpoint: Specific URL to access Workday functions (like a door to a room).
  • OAuth 2.0: Secure way to get temporary access tokens (like a one-time pass).
  • REST API: Flexible API using regular commands (GET, POST, PUT, DELETE).
  • Sandbox: Test environment with dummy data (safe zone for experimentation).
  • Token: Temporary permission to access Workday (like a short-term pass).
  • Workforce Now : HR Software suite that helps businesses with HR, time, benefits, payroll

B. References

  1. Login & Registration for ADP Account
  2. ADP Restful API
  3. ADP Workforce Now products
  4. Workforce Now ADP API Integration
  5. Payroll Data Input API
  6. Payroll Data Input API Guide for ADP Workforce Now
  7. Oauth documentation
  8. Access Tokens
  9. Pay Data Input
  10. Forbes ADP Workforce Review

Jul 9, 2024

How to get employee data from BambooHR API

If you are looking to connect with multiple apps, try Knit universal API to integrate with 20+ HRIS apps with a single API key. Sign up for free trial by clicking here. If you are looking to do connect with BambooHR API yourself, keep reading

BambooHR is a popular cloud-based human resource management software that helps businesses manage their HR operations, including employee data management, onboarding, performance tracking, and more. In addition to its user-friendly interface, BambooHR also provides an API that allows developers to programmatically access and update employee data.

Employee data is a critical component of HR operations, providing valuable insights into employee performance, engagement, and overall organizational health. 

With the increasing emphasis on data-driven decision making, businesses are looking for ways to harness the power of employee data to drive growth and productivity.

In this article, we will provide a comprehensive guide to using the BambooHR API to retrieve and manage employee data in more than one way.

BambooHR API Rate Limit and Documentation Reference

When working with the BambooHR API, it's essential to understand the rate limits and have access to comprehensive documentation to ensure smooth integration and usage. While specific details on the API rate limit for BambooHR were not explicitly found, we encourage you to refer to the official documentation for the most accurate and up-to-date information.

BambooHR API Documentation

For detailed guidance and reference, you can access the BambooHR API documentation through the following URLs:

These resources provide extensive information on how to use the BambooHR API, including endpoints, request formats, and examples. Whether you are looking to integrate employee data, manage hours, or perform other HR-related tasks, the documentation will be invaluable.

For any specific queries or further assistance, it is always a good idea to reach out to BambooHR support or consult the community forums.

Overview of BambooHR API endpoints for employee data

BambooHR uses a RESTful API, which is a web-based architectural style and approach to communications that is often used in web services development. The BambooHR API provides various endpoints for employee data, including:

  • Employee information: this includes data such as the employee's name, email address, job title, department, and other personal information.
  • Job information: This includes data such as the employee's job title, job description, start date, and other job-related information.
  • Time off: This includes data such as the employee's vacation, sick days, and other time off.
  • Company directory: This includes data on all employees in the company, including their contact information and job titles.
  • Reports: This allows you to generate reports on employee data, such as a report on employee turnover or employee performance.

Authorization in BambooHR API

When working with the BambooHR API, understanding the authorization mechanism is crucial for ensuring secure and efficient access to the data and functionalities provided by the API. This step-by-step guide will walk you through the process of authorizing your application to interact with the BambooHR API.

Step-by-Step Guide to Authorization in BambooHR API
  1. API Key Generation:
    • The first step in the authorization process is generating an API key. This key acts as a unique identifier that allows your application to authenticate with the BambooHR API.
    • To generate an API key, log in to your BambooHR account and navigate to the API settings. Here, you can create a new API key specifically for your application.
  2. Include API Key in Requests:
    • Once you have your API key, you need to include it in the header of every API request you make. The API key should be included as a Basic Authentication header.
    • The format for the header is as follows:Authorization: Basic {base64encoded_api_key}
    • Note that the API key must be base64 encoded before being included in the header.
  3. Base64 Encoding:
    • To encode your API key in base64, you can use various online tools or programming libraries. For example, in Python, you can use the base64 library:
      import base64

      api_key = 'your_api_key_here'

      encoded_key = base64.b64encode(api_key.encode('utf-8')).decode('utf-8')
    • This encoded key is then used in the Authorization header of your API requests.
  4. Making Authorized Requests:
    • With your API key properly encoded and included in the header, you can now make authorized requests to the BambooHR API.
    • Here is an example of how to structure an authorized GET request using Python's requests library:
      import requests

      url = 'https://api.bamboohr.com/api/gateway.php/your_company_domain/v1/employees'

      headers = {

         'Authorization': f'Basic {encoded_key}',

         'Accept': 'application/json'


      response = requests.get(url, headers=headers)

      if response.status_code == 200:

         print('Request was successful')



         print('Failed to retrieve data')


  5. Handling Errors and Permissions:
    • Ensure that your API key has the necessary permissions to access the endpoints you are targeting. If you encounter authorization errors, double-check the permissions associated with your API key.
    • Common HTTP status codes to watch for include:
      • 401 Unauthorized: Indicates that the API key is missing or incorrect.
      • 403 Forbidden: Indicates that the API key does not have permission to access the requested resource.

By following these steps, you can securely authorize your application to interact with the BambooHR API, ensuring that your data transactions are both secure and efficient.

Setting Up BambooHR Account

To get started with using the BambooHR API, you'll first need to set up a BambooHR account and enable API access. Here's how:

Sign up for a BambooHR account

To sign up for a BambooHR account, go to the BambooHR website and click on the "Try It Free" button. 

Follow the step-by-step instructions to set up your account. You'll need to provide some basic information, such as your company name, email address, and password. You'll also need to select a pricing plan based on the number of employees in your organization and the features you need.

However, in this demo, we are “trying it for free” so we do not have to select the pricing plan. Once you have filled in the information click on “Get Free Trial”.

When you see this screen, click on “We’re Ready!” button.

From here, follow the subsequent instructions (provide a strong password, accept terms and conditions) to finish your sign up process using the email and password you supplied earlier.

When you see the following screen, click next.

Check all of these or at least what you need and click“Done” button.

If you have followed the necessary steps of signing up for your BambooHR account, you should land here:

How to create a BambooHR API key

Once you have a BambooHR account, you can create an API key to access the data associated with your BambooHR API. To create the API key, log in to your BambooHR account and navigate to the "API Keys" page in the "Account" section.

Click on the "Add a New Key" button.

You will need to provide a name for your API key, which will help you identify it later and click “Generate Key”.

A key will be displayed. You can copy it and save it somewhere safe. After successfully saving your key, click “Done”.

After successfully saving your API key, your API key would be listed under My API Keys:

In the next section, we will discuss multiple use cases for the the BambooHR API.

Get employee data using BambooHR API

BambooHR allows you to access and update employee data for individual employees as well as in bulk. 

Retrieve All Employees Information

Copy to clipboard
import requests
subdomain = 'syncflowsolutions'
# Replace {subdomain} with your BambooHR credentials
url = f"https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/employees/directory"
headers = {
    "Accept": "application/json",
    "Authorization": "Basic ZTgyOGU3YzUyNGRlNmNkMmMxZTc0YWUxNDY1YmI0NDQ5NmY0YjVhNTpKRDg2UXA4ZS4qTHNKUXA="
response = requests.get(url, headers=headers)
if response.status_code == 200:
    employee_data = response.json()
    # Do something with the employee data
    print('Error retrieving employee data')

The code snippet above will retrieve records for all employees from the feature called directory.

Pitfall to avoid

One common pitfall to avoid here involves the use of the Company Directory feature. While this feature can be managed and disabled by individual companies in their account settings, it can lead to issues when calling the corresponding endpoint. This is because the feature may be disabled, or its behavior may vary across different companies.

Instead, the recommended approach is to use the "request a custom report" API to retrieve bulk employee data, which is a more reliable and consistent method.

Retrieve information for one employee

To retrieve information about a specific employee, you can make a GET request to this endpoint:

Copy to clipboard

 where {id} is the ID of the employee you want to retrieve and {companyDomain} is the company subdomain.

This endpoint allows you to retrieve employee data by specifying a set of fields. It is ideal for retrieving basic employee information, including current values for fields that are part of a historical table such as job title or compensation information.

Extract data from BambooHR API using Python

Copy to clipboard
 import requests
# Set the API URL and headers
subdomain = 'syncflowsolutions'
# Replace {subdomain} with your BambooHR credentials
id = 0
url = f"https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/employees/{id}/"
headers = {
    "Accept": "application/json",
    "Authorization": "Basic ZTgyOGU3YzUyNGRlNmNkMmMxZTc0YWUxNDY1YmI0NDQ5NmY0YjVhNTpKRDg2UXA4ZS4qTHNKUXA="
# Specify the fields to retrieve and only retrieve current data
params = {
    "fields": "firstName,lastName",
    "onlyCurrent": "true"
# Send the GET request and print the response
response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    employee_data = response.json()
    print("Error retrieving employee data")

This retrieves the data for the employee with ID 0. Make sure to replace {subdomain} with your actual BambooHR credentials.

How to create a new employee with BambooHR API

To create a new employee, you can make a POST request:

Copy to clipboard

The endpoint allows for the addition of a new employee. It is mandatory to provide at least the first and last names of the new employee. Upon successful creation, the ID of the newly created employee can be found in the response's Location header.

Create a new employee with BambooHR API using Python

Copy to clipboard
import requests
subdomain = 'syncflowsolutions'        	
# Replace {subdomain} with your BambooHR credentials
url = f"https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/employees/"
payload = {
    "firstName": "Tiberius",
    "lastName": "Mairura"
headers = {               	
    "content-type": "application/json",
    "authorization": "Basic ZTgyOGU3YzUyNGRlNmNkMmMxZTc0YWUxNDY1YmI0NDQ5NmY0YjVhNTpKRDg2UXA4ZS4qTHNKUXA="
    response = requests.post(url, json=payload, headers=headers)
except requests.exceptions.HTTPError as error:
    print(f"HTTP error occurred: {error}")
except Exception as error:
    print(f"An error occurred: {error}")

This creates a new employee with the specified data. Make sure to replace `{subdomain}` with your actual BambooHR credentials.

Update employee data from BambooHR API using Python

To update an existing employee's data, you can make a PUT request to the `/employees/{id}` endpoint with a JSON payload containing the updated employee data.

Here's an example using Python requests library:

Copy to clipboard
import requests
id = 134
url = f"https://api.bamboohr.com/api/gateway.php/syncflowsolutions/v1/employees/{id}/"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic ZTgyOGU3YzUyNGRlNmNkMmMxZTc0YWUxNDY1YmI0NDQ5NmY0YjVhNTpKRDg2UXA4ZS4qTHNKUXA="
payload = {
    "firstName": "Tiberius .O",
    "lastName": "Mairura"
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
    print('Employee updated successfully!')
    print(f"Error: {response.status_code} - {response.text}")

This updates the data for the employee with ID 134 with the specified data. Make sure to replace {subdomain} with your actual BambooHR credentials.

How to handle pagination

Pagination for BambooHR API is case-specific. 

  • BambooHR does not support pagination in the employee directory API, so when retrieving employee data, the BambooHR API will return all the results in one go. The default number of records per response is 50, but you can specify a different number of records using the limit query parameter.
  • However, for some other APIs in BambooHR, such as the time-off requests and time-off balances APIs, pagination is supported. To handle pagination, you can use the page and per_page query parameters. The page parameter specifies which page of results to return, and the per_page parameter specifies the number of results per page.

To navigate to the next page of results, you can use the next URL provided in the Link header of the response.

Get started with BambooHR API

In conclusion, the BambooHR API is a valuable tool for any organization looking to streamline their HR and employee data management processes. By leveraging the power of the API, organizations can improve their operations, reduce manual data entry, and gain deeper insights into their workforce.

If you need to quickly get access to BambooHR data, Knit unified API can make it easier for you. Knit is a unified API that connects 40+ HR and ATS APIs via a single, unified API. All you need to do is to integrate once with Knit, and all the authentication, authorization and integration maintenance will be done by Knit.

Talk to our sales team to learn more or get you free API key today

Sep 21, 2023

How to Build and Deploy a Microsoft Teams Bot

Using Knit's Communication APIs, you can send text as well as interactive messages to any Teams channel or user either using Knit's Bot or your own Bot. In this guide, we will help you understand which kind of bot to use for development and production.

Using Knit's Teams Bot

The Knit Unified API's Teams Bot is for only testing and getting familiar with communication APIs. For the production use cases, organizations must setup their own bots.

Using Knit MS Teams bot for communication purpose mainly requires two steps-

Step I: Adding the Teams link during setup

  1. First, you click on the MS Teams icon in the communication section of Knit apps.
  2. On clicking the MS Teams icon you have to add your Teams link in which the bot needs to be installed [Check this out How to get teams link]
how to build a MS Teams Bot

Step II: Installing Knit's Bot in the team

1. The Knit Bot will be installed via a package file provided by us. Click on the _**Upload an app**_

2. Then choose_**Upload a custom app**_ . Add Knit's Package here. [Knit's Bot Package]

3. After successful upload a pop-up will open where you click on - _**Add to a team**_

4. Then select the _**General**_ channel in the populated channels list.

👍 Congratulations your setup is complete. You can use this Bot for development or testing purpose.

Using Your own Bot

You should use your own Bot in production. Do not use Knit's Bot for production use cases.

This involves a two step process -

  1. Create your Bot with the MS Teams.
  2. Provide OAuth credentials to knit using [Register OAuth Cred]

Create your Bot with MS Teams

1. First, you need _Developer Portal_ App from Microsoft Teams Store to build MS Teams Bot.

create your own bot with Microsoft Teams

2.After Installing it, open and navigate to the _ Apps_ section.

3. Now, select the **+** icon to create a new app.

4. When you add the name of your app, you will be asked to provide the Developer name, terms of use etc in the _Basic Information_ section. Fill out all the details carefully and then click on the  _Save_ button.

 5. Next, visit the _Branding_  section to add your icon and other display information.

6. Click on the _App Features_ section and select _Bot_.

7. Next, create one Bot by selecting _Create a new Bot_.

create MS Teams bot

8. Here, you will see the **+** icon to add a new Bot.

9. After giving Name to the Bot, you need to configure the endpoint address. Set this to [Teams Bot End Point]

10. Click on the _Client Secrets_ option and then _Generate Client Secret_. (Keep this information handy it will be required during OAuth Registration with Knit.)

11. Now, copy this key as it is a one time secret. After clicking _OK _ you will be shown the below screen and your Bot would have been configured.

MS teams bot

12.Now you need to link this bot to your newly created App in _Step 6_. You will see this bot in the dropdown. Select this Bot, then select _Team_ scope and click on _Save_ button.

Distributing your app to clients

1. Click on the _Publish_ button on the top right corner in the app home page.

2. You will see the following options.

To use within your org, select publish to org. For distributing to clients download the package.

3. If you have followed the right steps and filled in all the necessary information correctly, you will be able to download it.

If you have missed any of mandatory fields, errors will be listed for missing fields shown in the image below

4. In the example above, the developer website URL, privacy terms etc. are missing. You need to fix all errors before you can download the package. It can be used to install in any team using steps described in the section _Using Knit's Teams Bot_.

Sep 21, 2023

What Should You Look For in A Unified API Platform?

Every SaaS company knows the difficulty of building and managing all integrations in-house. It  not only puts unnecessary strain on your engineering teams and resources but also leads to (avoidable) financial cost. 

Using a unified API platform can help you achieve integration success without spending unnecessary bandwidth or money. Let’s have a look at what a unified API platform is and what things you must check to make the right choice.

What is a unified API?

A unified API platform helps companies integrate the various applications, systems and software they use in a single, centralized platform. Such a platform makes the communication and exchange of data between the different applications seamless, quick and effective. With a unified API, data flow gets extremely streamlined, and it eliminates the need to manage multiple points of contacts for integrations. 

Of course, building all integrations in-house  is an alternative solution, when the number of integrations increase exponentially, individual connections can be difficult (and impractical) to manage and maintain from a technical standpoint. A unified API platform takes the friction out of such integration management with low-code or no-code solutions to reduce complexities and centralize integration management.  

Why do you need a unified API

 In any SaaS company, developers should focus on the core product roadmap – enhancing its features and usability Everything else, including building and maintaining integrations, becomes a non-core activity. 

Before we move onto the factors that should influence your unified API choice, let’s look at some of the real life advantages: 

1. Ease of extraction & transformation 

An integral part of data exchange that integrations rely on revolves around ETL or extraction, transformation and load. When performed manually for disparate applications, the processes can be highly time consuming. However, a unified integration platform can centralize the processes together and enable real-time data insights. It can automatically facilitate the extraction of data from operating systems like the ERP or the CRM and simultaneously transform it for effective use by different applications and systems within the platform. It reduces the burden on engineering teams to extract legacy data and automates the process of cleansing it to improve data quality and consistency for use by different applications. 

2. Improved efficiency

In addition to the ease of extraction and transformation, a unified API platform adds efficiency to the way businesses or developers leverage integrations. On the one hand, as it automates the process and reduces manual data entry, the incidence of errors and data contamination become significantly low. On the other hand, unified APIs facilitate data flow in real-time in different formats and protocols  while maintaining accuracy and timeliness, allowing applications and systems to exchange and access different data sets instantly. Companies no longer have to focus on data format similarity.

3. Reduced time-to-market and costs

A unified API  can help companies significantly reduce their time to market with new integrations that are needed with changing business realities. It can enable business agility by ensuring that new applications and systems are integrated in real-time with pre-built connectors without the need to build the integration API from scratch.

At the same time, costs associated with integrations also come down when companies use unified APIs. On the one hand, the cost of manual data entry and costs associated with errors is significantly reduced with automated data exchange. On the other hand, without a unified API , companies have to bear the monetary burden of maintaining multiple point-to-point connectors for data exchange between applications. Building an in-house integration can take anywhere between 2 weeks to 3 months. With a developer salary ranging from USD 80K to USD 125K, each integration can cost USD 10K to companies. At the same time, building it in-house can delay your core product offering by 3-6 months, putting you at a market disadvantage. 

What to look for in  a unified API solution 

Now that you understand how a unified integration platform can assist your product roadmap journey and facilitate business success, let’s look at some of the features your unified API tool must have .

1. Security and resilience

Start by understanding the security protocols in place for the unified API to ensure the confidentiality and security of your and your client’s data. 

Since the API tool  will have access to all the data that goes through your different applications, you need to ensure that the platform has robust security measures like risk based security, data encryption at rest/ in transit, least privilege security, continuous logging and access controls. Lack of effective security measures can render you vulnerable to security threats and data breaches. 

At the same time, check out whether or not the platform meets the security norms and compliances for your industry. Check the necessary certifications. Additionally, you must understand the security considerations and data access the platform has for your end customers, for how long it stores their data, what data it stores, etc. 

From a security lens, focus on the security posture of the platform for your as well as your end customer’s data, as they may not consent to data storage by a third-party application. Thus, be cognizant of these considerations and understand the security measures to address the same. 

2. Scalability

The main purpose behind using a unified APIis to ensure that you are able to efficiently manage large numbers of integrations and high volumes of data. Therefore, a key feature to look out for is scalability. There are two forces at play here. 

First, you need to check if the platform is able to take the load of your current and future integrations. This suggests you must ensure if it can manage the complexities of managing multiple integrations, a situation that may arise when you add a lot of integrations based on customer expectations. At the same time, you should gauge the number of integrations it is able to manage at once and the potential to add more as time passes. 

Second, the scalability test must understand the volume of data being processed by the platform. As data comes in from diverse sources at a high pace, the platform must support processing of high volume data in seconds. This can be accomplished with batch processing. You must ensure that the platform can easily support high volume requests. 

3. Compatibility 

When you use multiple applications and systems, the data and protocols you receive can be in a variety of types and formats. To facilitate real-time processing and data flow, the unified API platform must be compatible with different formats and should be able to process information accurately. Various protocols could include HTTP, FTP, and SFTP, and there can be different data formats, such as XML, CSV, and JSON. The objective is to ensure that while the sources of data might be different, leading to differences in the types of data you receive, the data which is loaded to other applications must be compatible with their understanding for processing and decision making. 

4. Ease of use and customer experience

The unified API platform that you choose should be easy to deploy, use and manage with a user-friendly and intuitive interface. If the tool requires a lot of technical knowledge to run, it will again eat into the bandwidth of your engineering team. Look for an API that is extremely low-code or nearly no-code to ensure that you don’t have to hire an entire technical team to run your integrations. Most unified APIs have a drag and drop UI, which makes the implementation of integrations very easy and reduces the dependency on technical teams for execution. 

Another factor is the customer experience that the unified API brings along. Since your end customers will be using the integrations, the experience they have will make a lot of difference when it comes to choosing the right platform. How well the customers are able to engage with the integrations and how well the integrations serve their business purposes via the unified platform can be a big defining factor.

At the same time, in case an integration breaks down, i.e. when either the API key becomes invalid or API experiences time out, your unified API platform must be able to seamlessly manage the customer experience flow. Before making a decision, you need to check how well the API tool in consideration ensures uninterrupted customer business even in times of integration breakdown or how quickly it is able to resolve the breakdown. 

Thus, when it comes to choosing the right unified API, make sure that it is easy to use, with low or no-code functionalities and preferably with a drag and drop interface. And look for options that have a proven track record of great customer experience to get an idea of whether or not the platform is able to meet expectations. 

5. Cost 

Another important parameter to look out for while choosing a unified API is the cost. There are several cost components for any platform and you need to check how much will the platform cost you in total, from deployment to end customer use. 

  • Some of the costs include an upfront cost for set up and implementation. 
  • Next, there may be subscription or monthly charges that you will pay to the platform vendor for using the services for providing integrations to your customers. 
  • Finally, there might be some additional or incremental charges for some integrations that you might wish to add later in your product journey. At the same time, you might want to check if the platform has extra costs or charges for providing technical support that your team, especially non-technical persons, might need. 

The cost can be based on connectors being used or CPU usages or data volume or number of users. Understand the pricing structure of the platform and do an in-depth study of your needs as well. Depending on the pricing structure, select the one which suits your budget the most. In general, it is a good practice to choose the platform which does not have constraints on the data volume or where cost is not a direct function of the data volume. 

Also Read: ROI of Unified API and Build vs Buy: What is the ideal approach to SaaS integration (for you)

6. API / SDK documentation

The platform should provide adequate API or SDK (software development kit) documentation. The SDK documentation is important to ensure that your engineering team has the right information to get started. While the unified API tool  is likely to be low-code with a drag and drop interface, you will still need information about the APIs, other components and even simple example codes to help you get started. 

The SDK documentation will help you understand how you can use the various components and functionalities of the API platform to run the various integrations you need. It will also have information on how to configure the platform and integrations as well as the APIs. 

7. Customer support 

A unified API solution  must offer robust support to help you address any challenges that you might face with the various integrations you use. There are many examples of this support here. 

  • First, if there is any error during any process for any integration, the error message should be displayed very clearly and appropriately. It should be in a language you understand and should be easy to communicate to others in the team as well. 
  • Second, once the error becomes clear, the customer support should help you with very clear solutions. It should have crisp directions or guidance on the next steps to address the challenges. The idea is to ensure that all errors are addressed quickly without any lag to ensure good customer experience.
  • Third, the dashboard must have adequate technical resources and documents which can help you stay on top of common errors and ways to resolve them on your end without contacting the customer support team every time. This will help reduce glitches and bugs in minimum time. 
  • Finally, the platform’s technical assistance must be present 24/7 as reliable customer support to assist you in case the shared solution is unclear or your team is unable to implement it. 

Thus, the customer support should ensure that you do not have to deploy additional engineering bandwidth and any error is solved without any friction in a timely manner to reduce lag or delays. 

8. Future roadmap and past record

At a macro level, the unified API solution is itself an application or a software that will get upgraded from time to time. You need to understand the impact of such upgrades on your business. Consider two major factors here. 

First, try to understand the future roadmap of the product. As a platform, are there any expansion plans on the map? Check if the platform has any plan to add more functionalities or support any new integrations that you might want to implement for your company as well. You would want to choose a platform that has a robust plan for growth in the future and not one which has reached its potential, since the market and customer expectations will keep growing. Furthermore, you might want to check if you can influence the product roadmap for the platform in some way to better meet your business needs. 

Second, you need to be equally focused on the historical records of the platform whenever it underwent an upgrade. When an application adds new functionalities or upgrades, there is a chance that existing processes or functionalities get impacted. It could be the addition of new connectors or security upgrades, etc. However, the best platforms ensure negligible or no impact on existing integrations. Therefore, choose a platform which has had a successful history of upgrades to prevent any negative impact on integrations you are using. 

These are some of the things you should look out for while choosing a unified integration platform. You can fall back on customer reviews, case studies and delve into technical assistance for better decision making. Try to research which successful companies are using the unified integration platform in question and how it has enabled them to scale their business with integrations. Also, check which platforms are being used by companies in your domain or the ones that use applications like yours. Finally, it is always best to try and see it for yourself. So, opt for API tools that offer free trials to review and recheck everything you have seen or read about the tool so far.

Wrapping up: TL:DR

As we conclude, it is clear that a unified API platform helps organizations deploy, manage and use different applications and systems from a single, centralized dashboard. It enables:

  • Easy data extraction and transformation
  • Improved efficiency by real-time and error free data exchange
  • Reduced time to market and cost savings

However, the key to integration success lies in choosing the right API tool. When choosing one, look out for:

  • Security and resilience to ensure that the data exchange for your company and your customers is safe and secure and is not vulnerable to unauthorized access
  • Scalability to check if the platform can meet high volume processing for your current and future integration needs
  • Compatibility with different types of data formats and protocols to ensure accuracy during data exchange
  • Ease of use for deployment and implementation with a drag and drop interface and low to no-code functionalities
  • Pleasant customer experience for your end users
  • Overall costs including upfront set up, monthly subscription and additional costs for future integrations/ customer support
  • SDK documentation with information of APIs and other components to successfully configure and use platform without reliance on technical skills
  • Robust customer support with online resources, technical assistance and clear error messages with appropriate solutions to prevent any lag
  • Future roadmap and records to ensure that platform upgrades lead to no or minimal impact on existing integrations

If you keenly look out for these factors, you will easily be able to compare the various platforms and select the right one for your needs. Make sure you have a clear idea of the integrations you need for your customers to map the scope for factors like cost, documentation, scalability, security, etc.

Sep 21, 2023

How to Create a Slack Bot in 5 Minutes: A to Z Guide

Using Knit's Communication APIs, you can send text as well as interactive messages to any Slack channel or user either using Knit's Bot or your own Bot. In this guide, we will help you understand which kind of bot to use for development and which one to use for production.

Using Knit's Slack Bot

Knit Slack Bot is meant for testing only. It will help you get familiar with the communication APIs. For the production use cases, you must setup your own bots.

If you wish to use Knit Slack Bot then it is a simple one step process. You just need to select Slack, after which a typical question (similar to other apps) will be asked. You need to follow the OAuth flow and the app will be installed in your workspace. 

However, this should be done only for development/testing. **Please do not use Knit's Bot in production!**

Using your own Bot

You should use your own Bot in production. Do not use Knit's Bot for production use cases.

There are two simple steps to get started with your own Bot.

  1. Create your Bot with Slack.
  2. Register the OAuth creds like client ID and secret of your Bot with Knit.

1. Create your Bot with Slack

Follow these steps below to create a Bot on Slack.

1. Visit Your Apps and sign in with your account to create App.

2. Click on the option: _Create new App_

create a slack bot

3. Select the option: _From scratch_

4. You will be asked to provide a Name of App. You can choose a workspace linked to the signed in account in which you wish to create the app. Click on: _Create App_

5. On clicking _Basic Information_ in the left panel, at the end of page you can add _Display Information_ such as App Image, Description etc.

6.Now, configure the redirect URL .

Things to consider:

1. Use https://app.getknit.dev/oauth/authorize for Production

2. Use https://app.sandbox.getknit.dev/oauth/authorize for Sandbox

3. Do not forget to click on _Save URLs_

building a slack bot

7. Now, add the following scopes

  • channels:read
  • chat:write
  • chat:write.customize
  • chat:write.public
  • groups:read
  • users:read
  • users:read.email
slack bot scopes

8. If you want to subscribe to other Slack events, click here and do the steps mentioned in this guide.

9. Congratulations! Your Bot setup is done. Next, you must enable public distribution of the Bot for your users to discover and use this new Bot. To begin, click on _Manage Distribution_ on the left panel

create a slack bot distribution

10. To finally enable public distribution, just tick the checkbox for _I’ve reviewed and removed any hard-coded information_ and then click on _Activate Public Distribution_ button

11. Congratulations! Your Bot is now available for others to install.

launch your own Slack bot

You have now created your own Slack Bot! However, there's one small step to do before you can use Knit's API on your new Bot.

2. Register the OAuth creds like client ID and secret of your Bot with Knit

Share Bot's client ID and client secret with Knit via Register OAuth Cred API and that's it. You're all set to use Knit's API! 😀