Quick Start

1. Installation

• Open the Docusign App Center and search for BambooHR.
• Click the BambooHR app card, then click Install App.

2. Creating a Connection

• After installation, click Connect Account.

• Choose the connection type:

  • Shared — accessible by the whole team (recommended).
  • Private — accessible only by you.

• Give your connection a clear name (e.g., "BambooHR - Demo").

• Complete the BambooHR authorization flow to grant Docusign access.

⚠️ Before clicking Connect Account, make sure you are already logged in to your BambooHR account in a separate browser tab. If you are not, the connection will fail with a 500 error.

3. Creating a Workflow

• Navigate to Agreements → Workflows.
• Click Create Workflow to start building.
• Choose launch method to From an API Call (we will use this in our example), create an object_id variable (Type: Text), and select Automated process.

4. Available Actions

The app provides three actions to use inside your workflow:

• Read from BambooHR — retrieve employee data from BambooHR (name, contact details, job information, etc.).
• Writeback to BambooHR — update existing employee records or create new ones in BambooHR.
• File Upload BambooHR — attach a signed document to a specific BambooHR employee record.

5. Key Things to Know

• Writeback: You decide which field to use as the identifier for the record — choose a value that is unique per employee (e.g., Work Email). For a full list of available fields and important field group rules, refer to the Implementation Guide & Known Behaviors.
• File Upload: In the Select Folder dropdown, choose New Subfolder → Add Variable and select the Employee ID from the Read from BambooHR step. This dynamically attaches the file to the correct employee record for each workflow run.

Implementation Guide & Known Behaviors

Known Behaviors

Connection Requirement

⚠️ To successfully connect your BambooHR account in the Docusign App Center, you must already be logged in to your BambooHR account in a separate browser tab before initiating the connection flow. Attempting to connect without an active BambooHR session will result in a 500 error.

Solution: Open your BambooHR account in a separate tab and ensure you are logged in before clicking Connect Account in Docusign.

Writeback 

Tabular Fields Create New History Rows

BambooHR stores certain data in historical tables (e.g., Job Information and Compensation). Each Writeback operation to these fields creates a new history row rather than overwriting the existing value. This is native BambooHR behavior.

The affected field groups are:

• Job Information: Job Title, Department, Division, Location
• Compensation: Pay Rate, Pay Type, Pay Schedule, Overtime Status

⚠️ When writing to any field within these groups, all fields in the same group must be included in the same Writeback step. Sending only one field from the group (e.g., Job Title alone) will create an incomplete history row with empty values for the other fields in that group.

Compensation

Effective Date Uniqueness Constraint

BambooHR does not allow two Compensation history rows with the same Effective Date. If a Writeback step attempts to create a Compensation entry with a date that already exists in the employee's Compensation history, the workflow will return a 500 error.

The following fields are affected (they all write to the Compensation table):

• Pay Rate
• Pay Type
• Pay Schedule
• Overtime Status

How Effective Date is set: BambooHR uses the hireDate field value as the Effective Date for new Compensation and Job Information rows. There is no separate Effective Date input — updating hireDate in the Writeback step controls which date the new history row is created under.

Important constraints:

• The new hireDate value must be at least 2 days after (for example from 12th of April to 14th of April) the most recent existing Effective Date in the employee's Compensation history. A difference of only 1 day will result in a 500 error from BambooHR.
• If the same hireDate value is used twice (e.g., running the same workflow twice for the same employee without changing the date), the second run will fail with a 500 error.

Recommendation: When updating any of the fields above via Writeback, always include hireDate with a value that is at least 2 days ahead of the employee's current most recent Compensation entry. In standard hiring workflows this is naturally satisfied since each new employee has a unique hire date.

Note: This constraint applies to the Compensation table only. The Job Information table (Job Title, Department, Division, Location) accepts multiple rows with the same Effective Date without error.

Installation and Configuration

This section explains how to install and configure the BambooHR integration for use with Docusign Workflow Builder.

Prerequisites

Before starting, ensure that:

• You are logged in to your BambooHR account in a separate browser tab.
• ⚠️ This is required — if you are not already logged in to BambooHR when initiating the connection, you will receive a 500 error.
• You are logged in to a Docusign account with Admin rights to install and manage applications.

How to Install the App

• Open the Docusign App Center.

• Search for BambooHR in the search bar.

  

  • [App Center search results showing the BambooHR app by Fluidlabs]

• Click the BambooHR app card to open its detail page.

• Click the Install App button to begin.

  

  • [BambooHR app page with the Install App button in the top right corner]

Connecting Your Account

Once the app is installed, you need to authorize the connection between Docusign and BambooHR.

• Initiate Connection: After installation, the app page will show an Installed status. Click the Connect Account button to begin linking your BambooHR account.

  

  • [App page showing "Installed" badge and the Connect Account button]

• Select Account Type: You will be prompted to choose the connection visibility:

  • Private: The connection is accessible only by you in Docusign.

  • Shared: The connection is accessible by multiple users or the whole team in Docusign. Best for collaborative workflows.

    

  • [Select Account Type screen showing Private and Shared options]

• Name the Connection: Enter a clear name for your connection (e.g., "BambooHR - Demo"). This name will appear in Workflow steps, so make it easily identifiable.

  

  • [Name Connection screen with "BambooHR - Demo" entered in the field]

• Authorize with BambooHR: You will be redirected to the BambooHR authorization screen. Complete the authorization to grant Docusign access to your BambooHR data.

  

  • [BambooHR authorization screen]

• Completion: You will be redirected back to the Docusign App Center. The app status will show as Installed and the connection is ready to use in workflows.

Managing Connections

You can edit, delete, or add new connections at any time without reinstalling the app.

To access connection settings:

• Go to the Docusign App Center and open the BambooHR app page.

• Click the Manage dropdown in the top right corner.

• Select Manage Connections.

  

  • [Manage dropdown showing: Add New Connection, Manage Connections, Manage Apps, Uninstall App]

You will be taken to the Connections page, which lists all active connections with their type, status, and the user who created them.

To manage an individual connection, click the three dots (⋮) menu next to it:

• [Connections list showing BambooHR-Demo as Shared/Active, with three-dot menu open showing Edit connection name, Reconnect, Reload Objects, Delete Connection]

Available Actions:

• Edit connection name: Rename the connection for better clarity.
• Reconnect: Force a reconnection to refresh tokens or update permissions.
• Delete Connection: Remove the connection.
• ⚠️ Warning: This may break existing workflows that use this connection.

Adding a New Connection

To connect an additional BambooHR account, you can either:

• Click the Manage dropdown on the app page and select Add New Connection, or
• Click the + Add New Connection button directly on the Connections page.

Follow the same setup steps as the initial installation.

How to Use the App

The BambooHR app enables you to work with BambooHR employee data directly within Docusign Workflows. Using this app, you can create workflows that read employee data from BambooHR, update BambooHR records, and automatically attach signed documents as part of an automated process.

Create a Workflow Builder To start using the integration, you first need to create a Workflow in Docusign.

• Log in to Docusign.

• Navigate to Agreements - Workflows.

• Click Create Workflow.

  

  • [Docusign Workflows screen with Create Workflow button]

• Build your workflow using the available steps, including BambooHR actions provided by the app.

• Publish the workflow when ready.

Available BambooHR Actions

Within the Workflow Builder, the BambooHR app provides actions to interact with your employee data.

The following actions are available:

• Read from BambooHR - Retrieve employee data from BambooHR (e.g., name, contact details, job information).

• Writeback to BambooHR - Update existing or create new BambooHR employee records based on the workflow output.

• File Upload to BambooHR - Allows a Workflow to upload and attach a file directly to a specific employee record in BambooHR.

  

• ["Add New Step" dialog with "BambooHR" searched, showing both BambooHR actions]

Configuring Actions: Workflow Start

In this documentation, we use object_id as the workflow startup variable. This is a common pattern when triggering workflows from an external system via API.

To configure the workflow trigger:

Step 1 - Select Trigger Type

Select From an API Call as the workflow start method.

• ["Add workflow start" dialog with "From an API Call" selected in the dropdown]

Step 2 - Create the object_id Variable

Create a variable named object_id (Type: Text).

• ["Set up variables" step showing object_id variable of type Text]

Step 3 - Select Process Type

Choose Automated process as the trigger type.

• [Step 3 showing "Automated process" selected]

This configuration allows external systems to trigger the workflow and pass a specific identifier (such as a BambooHR Employee ID) into the object_id variable. This variable can then be used in subsequent steps (like Read from BambooHR) to identify which employee record to process.

Read from BambooHR

The Read from BambooHR step allows a workflow to retrieve employee data from BambooHR. To do this correctly, the workflow must be able to identify which specific employee record it should work with.

Step Overview

Configuring this step involves three main stages:

• Selecting the BambooHR connection and object.
• Choosing which fields to read.
• Defining the rule to identify the target employee record.

1. Add the Step to Your Workflow

• In your workflow builder, click + Add Step.

• Search for and select Read from BambooHR.

• Once the block appears, click Configure to start the setup.

  

  • ["Read from BambooHR" step block in the workflow builder with the Configure button]

2. Configure Connection and Object

• Connection: Choose the BambooHR connection you created earlier (e.g., "BambooHR-Demo (Shared)").

• BambooHR object: Select BambooHR Employees - this is the only available object.

  

  • [Object dropdown showing "BambooHR Employees" as the selected option]

Click Next.

3. Select Fields

Choose the specific employee data points you want to retrieve.

• Click Add or Remove Fields.

  

  • [Fields step showing the Add or Remove Fields button]

• A field browser will open showing all available fields. Select the fields you need (e.g., Employee ID, First Name, Last Name, Work Email, Job Title, Department, etc.).

  

  • ["Add or Remove Fields" browser showing the Employees field list with multiple fields selected]

• The selected fields will become available as workflow variables for use in later steps.

• Click Next.

Note: For information on specific field behaviors and known data formatting nuances, refer to the Implementation Guide & Known Behaviors.

4. Identify the Record

In this step, you define which specific BambooHR employee record the workflow should read. You do this by creating a matching rule.

• BambooHR field: Select Employee ID.

• Operator: Select Equal to.

• Workflow field: Select the variable that contains the identifier (e.g., object_id, configured at the workflow start).

  

  • [Step 3 "Which records are you reading from?" showing Employee ID matched to object_id variable]

Example Logic: "Find the BambooHR Employee whose Employee ID matches the object_id provided when the workflow started."

Click Done. The rule is now saved.

Once configured, this step will find the correct employee record in BambooHR and pull the selected field data into the workflow as variables. You can now use these variables in subsequent steps (e.g., to pre-fill a document or pass data to a Writeback step).

Writeback to BambooHR

The Writeback to BambooHR step allows a workflow to update existing BambooHR employee records or create new ones using data collected during the workflow (e.g., from a signed document or a web form).

Step Overview

This step is typically used at the end of a workflow to save results back to BambooHR. A common pattern:

• Read employee data from BambooHR.
• Receive updated information from the signer.
• Writeback: update the employee record in BambooHR with the new data.

1. Add the Step to Your Workflow

• In your workflow builder, click + Add Step.

• Search for and select Writeback to BambooHR.

• Once the block appears, click Configure to start the setup.

  

  • ["Writeback to BambooHR" step block in the workflow builder with the Configure button]

2. Configure Connection and Object

• Connection: Select your BambooHR connection (e.g., "BambooHR-Demo (Shared)").

• BambooHR object: Select BambooHR Employees - this is the only available object.

  

  • [Object selection showing BambooHR Employees]

• Write settings: Choose how the system should handle the data:

  • Update or Create - checks if a matching record exists; updates it if found, or creates a new one if not.
  • Update - updates an existing record only. Fails if no match is found.
  • Create - always creates a new record, regardless of whether one already exists.

• Click Next.

3. Map Fields

IMPORTANT - Check Known Behaviors before map fields!

In this step, you map workflow data to the corresponding BambooHR employee fields.

• Click Add or Remove Fields to select which BambooHR fields you want to populate.

  

  • [Fields step showing the field list]

• For each field, select the source variable from your workflow. Data can come from any previous step - for example, from a Send Documents for Signature step (i.e., data filled in by the signer).

  

  • [Field mapping dropdown showing variables from a previous workflow step]

Warning - Tabular Field Groups: BambooHR stores Job Information and Compensation data in historical tables. Each update to these fields creates a new history row. If you are writing to any field in one of these groups, include all fields from the same group in the same step. For details, refer to the Implementation Guide & Known Behaviors.

Click Next.

4. Identify the Record

In this step, you define which specific BambooHR employee record the workflow should write to by creating a matching rule.

• BambooHR field: Select the field you want to use to identify the employee (e.g., Work Email (CREATE UPDATE)).

• Operator: Select Equal to.

• Workflow field: Select the corresponding workflow variable (e.g., Work Email from the Read from BambooHR step).

  

[Step 3 "Which record are you writing to?" showing Work Email matched to Work Email workflow variable]

💡 You decide which field to use as the identifier — it should be a value that is unique per employee in your BambooHR account. We used Work Email, but you can usefield that uniquely identifies the employee in your specific use case.

Click Done.

The step is now configured and will automatically update or create the BambooHR employee record when the workflow runs.

File Upload BambooHR

The File Upload action allows a Workflow to upload and attach a file directly to a specific employee record in BambooHR.

1. Add the File Upload Step

Add the File Upload BambooHR action to your Workflow and open its configuration.

• ["File Upload BambooHR" step block in the workflow builder with the Configure button]

2. Select the File to Upload

Specify which file from the workflow should be uploaded.

• Select File: Choose Combined Envelope File (or another file variable generated by a previous step).

  

  • [Step 1 "What are you storing?" with Combined Envelope File selected in the dropdown]

Note: If no file is available in the dropdown, it means no file has been generated yet at this point in the workflow. Make sure a Send Documents for Signature step (or another step that generates a document) exists before the File Upload step.

3. Choose the Upload Location

• Select connection: Choose your BambooHR connection (e.g., "BambooHR-Demo (Shared)").

  

  • [Step 2 "Where are you storing it?" with connection selected]

• Select drive: Choose Employees as the target entity type for the upload.

  

  • [Drive dropdown with Employees selected]

4. Configure the Folder — Attach Dynamically via Employee ID

To attach the file to the correct employee record for each workflow run, you need to configure the folder using the Employee ID variable from the Read from BambooHR step.

• Under Select Folder, click New Subfolder.

  

  • [Select Folder dropdown with New Subfolder highlighted]

• In the New Folder dialog, click Add Variable.

  

  • [New Folder dialog with Add Variable button]

• Select the variable source — Read from BambooHR — and choose Employee ID.

  

  • [Variable selector showing Read from BambooHR as source and Employee ID selected]

• Click Add.

  

  • [New Folder dialog showing the Employee ID variable added as folder name]

After completing these steps, the folder field will contain the Employee ID variable.

Final Expected Structure:

• Drive: Employees
• Folder: [employees[1] / Employee ID]

This configuration attaches the uploaded file to the specific employee involved in the current workflow run.

Note: Unlike some other integrations, BambooHR does not support selecting an employee directly from a list. The dynamic method via New Subfolder is the only available approach — and the recommended one for universal workflows.

5. Name the File

• Click Next.

• File Name: Combine text with variables from previous steps to create a custom file name (e.g., [Employee ID] - Signed Agreement).

  

  • [Step 3 "What will you call it?" showing a custom file name with a variable]

• Click Save.

6. Verification

If everything is set up correctly, the file will be attached to the corresponding employee record in BambooHR.

• Open the employee record in BambooHR.

• Navigate to the Files tab to see the uploaded document.

  

  • [BambooHR employee record Files tab showing the uploaded document]

FAQ & Troubleshooting

500 error when connecting BambooHR account

Symptom: You receive a 500 error when trying to connect your BambooHR account in the Docusign App Center.

Cause: BambooHR requires an active session before the connection flow can complete.

Solution: Open your BambooHR account in a separate browser tab and make sure you are logged in before clicking Connect Account in Docusign.

Writeback returns 500 — duplicate Effective Date in Compensation

Symptom: Writeback step fails with a 500 error when trying to update Pay Rate, Pay Type, Pay Schedule, or Overtime Status.

Cause: BambooHR does not allow two Compensation history rows with the same Effective Date. The hireDate field is used as the Effective Date for new rows — if a row with that date already exists, the request fails.

Solution: Ensure the hireDate value is at least 2 days after the most recent existing Compensation entry for that employee. In standard hiring workflows this is naturally satisfied since each new employee has a unique hire date.

Writeback does not update Job Title, Department, Division, or Location

Symptom: Writeback completes successfully but Job Title, Department, Division, or Location are not updated in BambooHR.

Cause: These fields are backed by predefined lists in BambooHR. If the value passed does not exactly match an existing list item, BambooHR silently ignores it.

Solution: Use only values that exist in your BambooHR account's predefined lists for these fields. You can check available values directly in BambooHR under the relevant dropdown menus.

Pay Rate not updating in BambooHR

Symptom: Writeback completes successfully but Pay Rate is not updated, or the update fails.

Cause: Pay Rate must be passed as a number only — without currency code. Passing "50000.00 GBP" instead of "50000.00" may cause the update to fail or be ignored.

Solution: Pass Pay Rate as a plain number: "50000.00". Currency is taken automatically from the account settings.