After installation, click Connect Account.
Choose the connection type:
Give your connection a clear name (e.g., "BambooHR - Demo").
Enter your BambooHR company domain, the part before .bamboohr.com, then sign in to BambooHR as an administrator and approve the access request.
object_id variable (Type: Text) and select Automated process.The app provides three actions to use inside your workflow:
The Read step covers plain employee fields, the historical tables Job Information, Compensation and Employment Status, and the custom fields and custom historical tables configured in your BambooHR account. Docusign loads that field catalog when the connection is made, so a field or a table added in BambooHR afterwards needs a Reconnect under Manage Connections before it appears in the picker.
Custom fields load with two exceptions: the field types List: Multiple Answers and State (Location) are not exposed. Custom tables load only when they have a date column, and their columns appear as Table name: Column name. How the app picks the entry from a table is under Reading Employee Data.
Job Information, Compensation and Employment Status keep history in BambooHR. Writing to any of them adds a dated entry instead of changing the current one.
| Table | Fields | Date field |
|---|---|---|
Job Information | Job Title, Department, Division, Location, Reports To | Job Information Date |
Compensation | Pay Rate, Pay Type, Paid Per, Overtime Status | Pay Rate Effective Date |
Employment Status | Employment Status | Employment Status Date |
Two rules, the same for all three tables:
In Compensation, an entry dated one day after the previous one does not become a new entry: the previous entry is overwritten and keeps its date. Do not rely on this, keep the two-day gap.
A date field on its own stops the step: it needs at least one field of its table.
⚠️ Map every field of the table, the fields listed above plus its date field, in one step. A partial write to
Compensationstops the step: Pay Rate needs Paid Per, and Pay Type or Overtime Status need Pay Rate.
Address Line 1, Address Line 2, City, State and Zip Code write together with Country. A state that does not belong to the country stops the step. British Columbia reads back as BC.
| Field | What to know |
|---|---|
| Pay Rate | A plain number: 98765.43. Currency and period come from your BambooHR settings. |
| Reports To | Takes an Employee #. A name such as Jennifer Caldwell also resolves, but can pick the wrong manager or fail. Do not pass an Employee ID: it is read as an Employee # and assigns a different person. |
| Employee # | Unique. Writing a number that another employee already has stops the step and the workflow fails. |
| Work Email, Home Email | Unique. Writing an address that another employee already has stops the step and the workflow fails. |
| Date fields | The date picker in the step works as is. A date coming from a text variable has to be YYYY-MM-DD. |
A value written to a list field has to match your BambooHR account exactly. A value that does not match is dropped, the field is cleared, and the step still reports success. The list fields and their values are in Field Values Reference.
Employee ID is the only key that guarantees one match. Without it, narrow the rule down to a single employee: first name plus last name plus department, email plus location, or a phone number.
Fourteen fields work as criteria. Their labels carry a (Searchable) suffix in the picker:
Employee ID, First Name, Last Name, Display Name, Hire Date, Status, Job Title, Department, Division, Location, Work Email, Home Email, Work Phone Extension, Mobile Phone.
Any other field in the rule stops the workflow with an error. The run shows the step as failed without the reason, so check the rule against this list first.
Equals is exact: Ash does not match Ashley.05 does not match 5.Job Information, Compensation, Employment Status and custom tables report a single entry, not the history: the newest one dated on or before today, the one BambooHR marks with a green dot in the employee record. When every entry is future-dated, the app reports the nearest upcoming one. When a table has more than one date column, the app picks the entry by the first date column it finds in the table.
| Type | Reads as |
|---|---|
| Date | Date-time pinned to 12:00 UTC: 2019-01-07T12:00:00.000Z |
| Checkbox | yes or no |
Values must match your BambooHR account exactly.
| Field | Accepted values |
|---|---|
| Gender | Male, Female |
| Marital Status | Single, Married, Domestic Partnership |
| Pay Type | Salary, Hourly, Commission Only |
| Paid Per | Day, Week, Month, Quarter, Year, Pay Period, Piece |
| Overtime Status | Exempt, Non-exempt |
| Pay Schedule | Every other week, Twice a month. Read only. |
| Department, Division, Location, Job Title, Employment Status, Secondary Language, Shirt size | Configured in your BambooHR account, so the values are your own. A standard account has Employment Status as Full-Time, Part-Time, Contractor, Intern, Furloughed, Terminated. |
Pay Type and Paid Per sit next to each other and their values look interchangeable. Swapping them clears both fields.
This section explains how to install and configure the BambooHR integration for use with Docusign Workflow Builder.
Before starting, ensure that:
.bamboohr.com.Open the Docusign App Center.
Search for BambooHR in the search bar.
Click the BambooHR app card to open its detail page.
Click the Install App button to begin.
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.
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.
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.
Enter your company domain: Type the part before .bamboohr.com. For acme.bamboohr.com, enter acme.
Authorize with BambooHR: Sign in to BambooHR and approve the access request. The screen lists the data groups the app uses.
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.
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.
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:
To connect an additional BambooHR account, you can either:
Follow the same setup steps as the initial installation.
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.
Log in to Docusign.
Navigate to Agreements - Workflows.
Click Create Workflow.
Build your workflow using the available steps, including BambooHR actions provided by the app.
Publish the workflow when ready.
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.
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:
Select From an API Call as the workflow start method.
Create a variable named object_id (Type: Text).
Choose Automated process as the trigger type.
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.
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.
Configuring this step involves three main stages:
In your workflow builder, click + Add Step.
Search for and select Read from BambooHR.
Once the block appears, click Configure to start the setup.
Connection: Choose the BambooHR connection you created earlier (e.g., "BambooHR-Demo (Shared)").
BambooHR object: Select BambooHR Employees - this is the only available object.
Click Next.
Choose the specific employee data points you want to retrieve.
Click Add or Remove Fields.
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.).
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.
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).
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).
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).
This step is typically used at the end of a workflow to save results back to BambooHR. A common pattern:
In your workflow builder, click + Add Step.
Search for and select Writeback to BambooHR.
Once the block appears, click Configure to start the setup.
Connection: Select your BambooHR connection (e.g., "BambooHR-Demo (Shared)").
BambooHR object: Select BambooHR Employees - this is the only available object.
Write settings: Choose how the system should handle the data:
Click Next.
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.
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).
Fields available for writing:
First Name and Last Name are required on create. Read-only fields are not in this list: Employee ID, Display Name, Status, Termination Date and Pay Schedule. All of them read.
Update changes the fields you map and leaves the rest untouched. Writing to Job Information, Compensation or Employment Status adds a dated entry: map the whole table and its date field, and keep two days between entries. The rules are in Implementation Guide & Known Behaviors.
Click Next.
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).
Operator: Select Equal to.
Workflow field: Select the corresponding workflow variable (e.g., Work Email from the Read from BambooHR step).
💡 You choose which field identifies the record. It has to be unique per employee in your BambooHR account. This example uses Work Email; any field that identifies the employee in your use case works.
Click Done.
The step is now configured and will automatically update or create the BambooHR employee record when the workflow runs.
The File Upload action allows a Workflow to upload and attach a file directly to a specific employee record in BambooHR.
Add the File Upload BambooHR action to your Workflow and open its configuration.
Specify which file from the workflow should be uploaded.
Select File: Choose Combined Envelope File (or another file variable generated by a previous step). BambooHR accepts files up to 20 MB.
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.
Select connection: Choose your BambooHR connection (e.g., "BambooHR-Demo (Shared)").
Select drive: Choose the employee file category the document should land in. A standard BambooHR account offers four:
Categories renamed or added in your BambooHR account appear here as well.
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.
In the New Folder dialog, click Add Variable.
Select the variable source, Read from BambooHR, and choose Employee ID.
Click Add.
After completing these steps, the folder field will contain the Employee ID variable.
Final Expected Structure:
This configuration attaches the uploaded file to the specific employee involved in the current workflow run.
Note: The folder picker does not list employees. Adding the Employee ID as a new subfolder is the only way to target an employee, and it keeps one workflow working for every employee.
Click Next.
File Name: Combine text with variables from previous steps to create a custom file name (e.g., [Employee ID] - Signed Agreement).
Click Save.
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.
Job Title, Department, Division or Location did not change.
The value has to match a list item in your BambooHR account exactly. A value that does not match is dropped, the field is cleared, and the step still reports success. Check the list in BambooHR under the field's dropdown.
Pay Rate did not change.
Pass a plain number,
50000.00, not50000.00 GBP, and map Paid Per in the same step.
Pay Type and Paid Per are empty.
The two values were swapped. Pay Type takes
Salary,HourlyorCommission Only; Paid Per takesYear,Month,Weekand so on. See Field Values Reference.
Reports To points to the wrong person.
Reports To takes an Employee #. An Employee ID from a Read step is read as an Employee # and points to someone else. Pass the manager's Employee #.
A field I can see in BambooHR is missing from the field picker.
Open Manage Connections, click Reconnect on the connection, then reopen the step.
Pay fields read empty, but BambooHR shows them.
The connection sees what the BambooHR user who approved it sees. Reconnect signed in as an administrator.
A pay change updated the previous Compensation entry instead of adding one.
Entries in
Compensationneed at least two days between them. Set Pay Rate Effective Date at least two days after the last entry.
A date field fails with Invalid date value.
A date from a text variable has to be
YYYY-MM-DD. The date picker in the step is always accepted.
[New Features]
Writeback
Employment Status and the three date fields Job Information Date, Pay Rate Effective Date and Employment Status Date. See Implementation Guide & Known Behaviors.Read
Table name: Column name.[Updates]
Connection
Read
Job Information, Compensation and Employment Status. Field labels follow BambooHR's own names, for example Birth Date and Address Line 1.Writeback
Job Information, Compensation and Employment Status record a new dated entry instead of overwriting the current one. Fields you do not map carry over from the current entry.File Upload
[Compatibility]
[Bug Fixes]
Book a free 30-minute setup call with a solution consultant. Most setups finish inside the call: the connection, the field mapping, the first run. A larger setup becomes a separate engagement, with a fixed price in writing.
Tell us what happens and we take it from there. The message goes to docusign-support@fluidlabs.com.
Name the app. We answer with the app that already covers it, or a scoped plan for the connection.