# Xero for Docusign IAM

> Bridge your accounting data with your agreement workflows. Pull contact records, invoice details, and financial data from Xero into Docusign Workflow Builder to automate document preparation and keep your books and agreements in sync.

- Web page: https://fluidlabs.com/documentation/xero-for-docusign
- Published by: Fluidlabs
- Status: Live on the Docusign App Center
- Docusign App Center listing: https://apps.docusign.com/app-center/app/47f8edd6-db0d-4415-aed0-a21b21814203
- App page: https://fluidlabs.com/integrations/xero-for-docusign
- Last updated: 2026-06-04
- Support: docusign-support@fluidlabs.com

## Contents

- [Xero Quick Start](https://fluidlabs.com/documentation/xero-for-docusign#xero-quick-start)
- [Known Behaviors & Limitations](https://fluidlabs.com/documentation/xero-for-docusign#known-behaviors--limitations)
- [Installation and Configuration](https://fluidlabs.com/documentation/xero-for-docusign#1-installation-and-configuration)
- [How to Use the App](https://fluidlabs.com/documentation/xero-for-docusign#2-how-to-use-the-app)
- [Configuring "Read from Xero"](https://fluidlabs.com/documentation/xero-for-docusign#3-configuring-read-from-xero)
- [Configuring "Writeback to Xero"](https://fluidlabs.com/documentation/xero-for-docusign#4-configuring-writeback-to-xero)
- [File Upload to Xero](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero)
- [FAQ & Troubleshooting](https://fluidlabs.com/documentation/xero-for-docusign#faq--troubleshooting)

---

## Xero Quick Start

#### 1. Installation

* [**Install the Xero app**](https://fluidlabs.com/documentation/xero-for-docusign#1-installation-and-configuration) from the Docusign App Center.
* During installation, grant the required permissions.
* After installing, click Connect Account to link your Xero organization.

#### 2. Creating a Connection

* You will be prompted to choose a** **[**connection type**](https://fluidlabs.com/documentation/xero-for-docusign#1-installation-and-configuration):

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

* Give your connection a clear name (e.g., "Xero Demo Company").

* Log in to Xero to authorize the connection.

#### 3. Creating a Workflow

* Navigate to Agreements > Workflows.
* Click Create Workflow to start building.

#### 4. Available Xero Actions

The app provides three main actions to use inside your workflow:

* [**Read from Xero**](https://fluidlabs.com/documentation/xero-for-docusign#3-configuring-read-from-xero) — retrieve data from the Xero system (e.g., Contact details).
* [**Writeback to Xero**](https://fluidlabs.com/documentation/xero-for-docusign#4-configuring-writeback-to-xero) — update existing records or create new data in Xero.
* [**File Upload**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero) — attach a specific file (like a signed agreement) to a Xero Contact.

#### 5. Important File Upload Configuration Nuances

* File Upload Location: When configuring the File Upload step, you must set the[ **Drive to Contacts**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero).
* How to set it: Click [**New Subfolder**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero)** **> Add Variable and select the ID retrieved from the "Read from Xero" step.
* New Sub Folder Variable: For the New Folder, you must use the [**Contact ID variable**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero) (not the name).


## Known Behaviors & Limitations

This page covers important behaviors and limitations of the Xero integration in Workflow Builder that you should be aware of when building your workflows. Understanding these nuances will help you avoid common configuration mistakes and set up your workflows correctly from the start.

### “OR” operator

The "OR" operator has important limitations:

* If the "IF" condition matches a contact → that contact is used
* If "IF" doesn't match → falls back to "OR" conditions, the first matched record is used
* If all "OR" conditions point to the same contact → works correctly
* If "OR" conditions match different contacts → the workflow fails with `400: "Found multiple records for the given search query"`.
* If an "OR" field value is empty at runtime → the workflow will fail. Make sure all fields used in "OR" conditions are always populated. If a field might be empty (e.g., optional web form fields), avoid using it as an "OR" condition

### Case Sensitivity

Although Xero itself is not case-sensitive when searching contacts, we recommend always using the exact name as it appears in Xero. This ensures consistent and predictable behavior across all workflow steps.

### Special Characters in Contact Names

The following special characters are confirmed to work correctly in contact names: `/`, `&`, `'`, `@`, `+`, `,`, `.`, `-`, `?`, `(`, `)`

If a contact name contains other special characters not listed above, unexpected errors may occur. In such cases, please contact support.


## 1. Installation and Configuration

### Prerequisites

Before starting, ensure that:

* You are logged in to a Xero account with the required permissions.
* You are logged in to a Docusign account with Admin rights to install and manage applications.

### How to Install the App

1. Open the [Docusign App Center](https://apps.docusign.com/app-center/extensionapps).
2. Search for and locate the Xero application.
3. Click the Install App button to begin.
   ![Web page showing the Xero Staging app with an install button and description.](https://fluidlabs.com/images/documentation/xero-for-docusign/a13576b4b7baecfd020891071805b34e.webp)
4. During installation, grant the required permissions when prompted.

### Connecting Your Account

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

1. Initiate Connection: After installation, click the Connect Account button on the app screen.
    ![Xero Staging app interface showing a mouse cursor hovering over the 'Connect Account' button.](https://fluidlabs.com/images/documentation/xero-for-docusign/4af36caef70b37cdd3fa374b3415b96c.webp)

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

   * Shared (Recommended): The connection is accessible by the whole team in Docusign. This is best for collaborative workflows.
   * Private: The connection is accessible only by you.
     ![Screenshot showing Xero account connection, with 'Shared' access type selected for team use.](https://fluidlabs.com/images/documentation/xero-for-docusign/638be256064383f1754953a81e646def.webp)

3. Name the Connection: Enter a clear name for your connection (e.g., "Xero Demo Company"). This name will be displayed later in Workflow steps, so make it easily identifiable.
    ![User interface for naming a Xero Staging account, with 'Xero Demo Company' entered.](https://fluidlabs.com/images/documentation/xero-for-docusign/b29a16a1964ba25bf9830b01eb804e8a.webp)

4. Authorize with Xero: Click Login to proceed to Xero.

   * Select the organization you want to connect.

   * **Troubleshooting**: If you are already logged in and your organization appears "greyed out" or inactive in the list, click "Continue with \[N] organisations" or select "Select another organisation" from the dropdown menu to re-authorize access.

     ![A software consent screen showing a user selecting an organization and continuing data access.](https://fluidlabs.com/images/documentation/xero-for-docusign/f1e0536ab97ef0aa27efb1ecd61a8943.webp)
     ![Screen showing two Xero organizations to select: 'DocuSign Test Org' and 'Demo Company'.](https://fluidlabs.com/images/documentation/xero-for-docusign/bed7036bad45b26e2cc02b10b8592a6d.webp)

5. Completion: You will be redirected back to the Docusign App Center. The app status should now show as Installed, and the connection is ready to use.

### Managing Connections

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

To access connection settings:

1. Go to the Docusign App Center > Installed Apps.
2. Find the Xero app and click the Manage dropdown or the three dots menu.
3. Select Manage Connections.
   ![Xero Staging app interface showing the 'Manage' dropdown menu with 'Manage Connections' selected.](https://fluidlabs.com/images/documentation/xero-for-docusign/0ff995cef77e1c639120e0e126c20c7e.webp)

####  Available Actions:

* Edit Name: Rename the connection for better clarity.
* Reconnect: Force a reconnection to refresh tokens or update permissions.
* Delete: Remove the connection (Warning: This may break workflows using this connection).
  ![Xero Staging connections with an active link and menu to edit, reconnect, or delete.](https://fluidlabs.com/images/documentation/xero-for-docusign/fb05b9f432a3090e0298217fc35f3666.webp)

### Adding a New Connection

If you need to connect to a different Xero company (e.g., for a different workflow), click + Add New Connection inside the Manage Connections screen. Follow the same setup steps as the initial installation.
![UI screen displaying the Xero Staging application with an "Add New Connection" button.](https://fluidlabs.com/images/documentation/xero-for-docusign/ba7687b485bc90c89c4bfe8861e56017.webp)


## 2. How to Use the App

he Xero app enables you to work with Xero data directly within Docusign Workflows. Using this app, you can create workflows that read data from Xero, update Xero 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.

1. Log in to Docusign.
2. Navigate to Agreements → Workflows.
3. Click Create Workflow.
   ![Workflow management user interface with navigation bar, agreements tab, and create workflow button.](https://fluidlabs.com/images/documentation/xero-for-docusign/ea213edb72091170a1a4ef222056c8e0.webp)
4. Build your workflow using the available steps, including Xero actions provided by the app.
5. Publish the workflow when ready.

### Available Xero Actions

Within the Workflow Builder, the Xero app provides actions to interact with your data. These actions allow Xero to act as both a source and a destination within the same workflow.

The following actions are available:

* [**Read from Xero**](https://fluidlabs.com/documentation/xero-for-docusign#3-configuring-read-from-xero): Retrieve data from the Xero system (e.g., Contact details).
* [**Writeback to Xero**](https://fluidlabs.com/documentation/xero-for-docusign#4-configuring-writeback-to-xero): Update existing records or create new data in Xero based on the workflow setup.
* [**File Upload**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero): Attach a specific file (e.g., a signed agreement or W-9 form) to a Xero Contact.
  ![Add New Step dialog showing a search bar and a list of connected applications.](https://fluidlabs.com/images/documentation/xero-for-docusign/577f3b8da24ddf88728ed3c06c1996ba.webp)

#### Configuring Actions: Workflow Start

In this documentation, we will 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:

1. Select From an API Call as the workflow start method.
   ![User selects 'From an API Call' to initiate a new workflow in the application interface.](https://fluidlabs.com/images/documentation/xero-for-docusign/271d2d3e632c1aef2e8c6ba8488c2b72.webp)
2. Create a variable named `object_id` (Type: Text).
   ![Screenshot of a workflow setup page showing an 'object\_id' variable input field.](https://fluidlabs.com/images/documentation/xero-for-docusign/fe9c93bb30d281b383de7d354801e1a2.webp)
3. Choose Automated process as the trigger type.
   ![Workflow start configuration panel showing selection for an automated API call initiation process.](https://fluidlabs.com/images/documentation/xero-for-docusign/56eb0749d02fa06a251906b148dc7c2f.webp)

This configuration allows external systems to trigger the workflow and pass a specific identifier (like a Xero Contact ID) into the `object_id` variable. This variable can then be used in subsequent steps (like "Read from Xero") to identify which record to process.


## 3. Configuring "Read from Xero"

The Read from Xero step allows a workflow to retrieve data for a specific Xero Contact. To do this correctly, the workflow must be able to identify which Xero entity it should work with.

### Step Overview

Configuring this step involves three main stages:

1. Selecting the Xero connection and object.
2. Choosing which fields to read (retrieve).
3. Defining the rule to identify the target record.

---

### 1. Add the Step to Workflow

1. In your workflow builder, click + Add Step.
   ![UI element showing 'From an API call' with an 'Add a step' button hovered by a cursor.](https://fluidlabs.com/images/documentation/xero-for-docusign/71c79afd62ba3c65a61100a539e94e72.webp)
2. Search for and select Read from Xero.
   ![Add New Step dialog showing 'xero' search results for Xero Data IO Extension Staging.](https://fluidlabs.com/images/documentation/xero-for-docusign/1dece605b39eed29d6e5d5f03d607d5f.webp)
3. Once the block appears, click Configure to start the setup.
   ![Workflow card shows 'Read from Xero Staging' with a cursor hovering over 'Configure' button.](https://fluidlabs.com/images/documentation/xero-for-docusign/0a30e251668b9869b891a580ea2b3930.webp)

### 2. Configure Connection and Object

You will be prompted to select where to read data from.

1. Connection: Choose the Xero connection you created earlier (e.g., "Xero Demo Company").
2. Object: Select the entity type you want to work with. In this example, select Contact.
   ![Xero connection form showing "Contact" selected as the staging object with a red arrow.](https://fluidlabs.com/images/documentation/xero-for-docusign/aa5f4e44335573205ef3a70c4b5cd709.webp)
3. Click Next.

### 3. Select Fields

Choose the specific data points you want to retrieve from the Xero Contact.

1. Click Add or Remove Fields.
2. Select fields like _Name, Email Address, Contact Number, etc._.
   ![Interface showing workflow field selection with Add or Remove Fields button.](https://fluidlabs.com/images/documentation/xero-for-docusign/dccf493a1021bdb1dba51453c3472cd4.webp)
3. These fields will become available as Workflow Variables for use in later steps.
4. Click Next.

### 4. Identify the Record

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

Create a rule that matches a Xero field to a workflow variable:

* Xero Field: Select a unique identifier field in Xero (e.g., `Account Number` or `Contact ID`).
* Operator: Select `Equal to`.
* Workflow Field: Select the variable that contains the identifier (e.g., `object_id`, which we configured at the workflow start).
  ![User interface displaying a data mapping rule connecting Xero Staging 'Account Number' to 'object\_id'.](https://fluidlabs.com/images/documentation/xero-for-docusign/ee035ec51c2f5ce8b6bcd065e949f206.webp)

> Example Logic: This rule tells the system: _"Find the Xero Contact whose Account Number matches the object\_id provided when the workflow started."_

Note: You can use other fields for identification (e.g., Email, Name), provided they are unique enough to identify a single record.

Once configured, this step will find the correct Contact in Xero, and pull the selected data into the workflow. You can now use these variables (e.g., to pre-fill a document) in subsequent steps.


## 4. Configuring "Writeback to Xero"

The Writeback to Xero action allows a workflow to update existing Xero records or create new ones using data generated during the workflow execution (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 Xero. A common pattern:

1. Read Client data from Xero.
2. Send documents for signature using that data.
3. Receive updated information from the signer.
4. Writeback: Update the client record in Xero with the new data.

### 1. Add the Step to Workflow

1. In your workflow builder, click + Add Step.
   ![An 'Add New Step' dialog box displays search results for 'xero' integration.](https://fluidlabs.com/images/documentation/xero-for-docusign/cfe2a369e75a835081ff097d743d4fa3.webp)
2. Search for and select Writeback to Xero.
3. Click Configure to open the settings.

### 2. Configure Connection and Object

1. Connection: Select your Xero connection.
2. Object: Choose the entity you want to write to (e.g., Contact).
   ![Configuration screen for 'Writeback to Xero Staging', selecting connection and Contact object.](https://fluidlabs.com/images/documentation/xero-for-docusign/36cdd48320af36b26b42c51a9feb4a4e.webp)

### 3. Choose Write Settings

Decide how the system should handle the data writing process:

* Update: Updates an existing record. Fails if no matching record is found.
* Create: Always creates a new record regardless of whether one already exists.
* Update or Create (Recommended): Smartly checks if a record exists. If yes, it updates it; if not, it creates a new one.
  ![Form showing Xero Staging object, Contact dropdown, and selected "Update or Create" option.](https://fluidlabs.com/images/documentation/xero-for-docusign/1509377e7a6036a25aecf1711174e9eb.webp)
* Click Next.

### 4. Map Fields

Select which fields in Xero you want to populate with workflow data.

> ⚠️ Important: The Name field is mandatory in the Xero API. It is the key field used to find or create records.

1. Map the Name Field: Ensure you map the Xero `Name` field to a valid workflow variable (e.g., a "Name" field collected from a Web Form or the `Name` variable from the Read step).
   ![Digital form showing field setup, with red arrow highlighting the 'Name\*' field.](https://fluidlabs.com/images/documentation/xero-for-docusign/ff7f8f0cc7e64603fe17fbbaa00f04af.webp)
   ![Workflow field mapping interface showing a search bar and the 'Status' field highlighted.](https://fluidlabs.com/images/documentation/xero-for-docusign/f27577f36f8bfc010c38ebac553862bf.webp)
2. Map Other Fields: Map any other data points you wish to update (e.g., Email, Phone).
3. Click Next.

### 5. Identify the Record

Finally, you must define the rule for identifying which record to write to.

Configure the rule as follows:

* Xero Field: Select Name (since it's the API key field).
* Operator: Select `Equal to`.
* Workflow Field: Select the corresponding workflow variable that contains the Name (e.g., `Name` from your Web Form).
  ![Digital interface showing Xero Staging field "Name" mapped to Workflow field "Name".](https://fluidlabs.com/images/documentation/xero-for-docusign/abe0f8ff12ca1b474e350f8ebf6a576d.webp)

Click Done. The step is now configured to automatically update or create Xero records when the workflow runs.


## 5. File Upload to Xero

The File Upload action allows a Workflow to upload and attach a file to a Xero Contact.

### 1. Add the File Upload Step

Add the File Upload to Xero action to your Workflow and open its configuration.
![A workflow node titled 'File Upload Staging' with a configure button and blue X icon.](https://fluidlabs.com/images/documentation/xero-for-docusign/4fe1366331ac3d78e16a044d06e53e7d.webp)

### 2. Select the File to Upload

You need to specify which file from the workflow should be uploaded.

Select File: Choose Combined Envelope File (or another file variable generated by previous steps).
![Form for 'File Upload Staging' shows 'Combined Envelope File' selected as input.](https://fluidlabs.com/images/documentation/xero-for-docusign/b58c2d26fbe5b4a2924d6e32b37b084d.webp)

> 💡 Note: If no file is available for selection, it usually means that the file was not generated in previous workflow steps. Verify that your workflow includes steps such as document preparation and signing before File Upload.

### 3. Choose the Upload Location

> ⚠️ Important: The UI uses standard "Folder/Subfolder" terminology, but in the context of Xero, this structure represents the Xero Entity Hierarchy.

![File upload configuration form with highlighted dropdowns for connection, drive, and folder selection.](https://fluidlabs.com/images/documentation/xero-for-docusign/34ab7595c15448a9460393928d1da6b5.webp)

To attach a file, you must first select the Drive as Contacts. Then, for the Folder, you have two ways to choose the destination:

#### Method A: 

Select contact from List.
![User interface showing an open dropdown menu to select a folder with 'Test Contact' highlighted.](https://fluidlabs.com/images/documentation/xero-for-docusign/13aaae429145f0aae81e51b13866a395.webp)

You can select a specific Contact manually from the dropdown list.

* Result: The file will _always_ be attached to this specific Contact, regardless of who is processed in the workflow.
* Use case: Useful if you want all files to go to a single central record (e.g., a generic "Admin" contact).

#### Method B: 

Attach to the Current Workflow Contact (Dynamic method).
![UI dropdown for folder selection showing 'New Subfolder' highlighted, indicated by a red arrow.](https://fluidlabs.com/images/documentation/xero-for-docusign/7eed54d9d0a3349742fd96e1752d6e76.webp)

You can configure the New Subfolder using a variable (Contact ID).

Please check below "[**How to configure**](https://fluidlabs.com/documentation/xero-for-docusign#5-file-upload-to-xero)" for more information.

* Result: The file will be attached to the _specific_ contact involved in the current workflow run.
* Use case: Essential for universal workflows where you want the signed document to go to the correct client's record automatically.

### How to configure Contact ID in New Subfolder:

Step 1 — Select Drive In the Select Drive dropdown, choose Contacts.
This sets the target entity type for the upload.
![Form showing 'Select drive' dropdown with 'Contacts (Use Contact ID as new folder name)' selected.](https://fluidlabs.com/images/documentation/xero-for-docusign/7597cd0ea4a17162bed717e431e234b3.webp)
Step 2 — Add Folder Variable
![UI displaying a form to select connection, choose area, and add a new folder.](https://fluidlabs.com/images/documentation/xero-for-docusign/241565628baf8f3618ab2e4ac700e05e.webp)
Under Select Folder, click New Subfolder.
![Form for creating a new offer, selecting organization "My New Company" and custom titles.](https://fluidlabs.com/images/documentation/xero-for-docusign/adf8324ad5594266a2c6f3f9a3995e6a.webp)
In the dialog (New Folder), click Add Variable.
![Dialog box to create a new folder, showing options to add variable or text.](https://fluidlabs.com/images/documentation/xero-for-docusign/5c253182c3ca414a56b2fe6b5bdc5ce2.webp)
Select the variable source. Remember, we should select Contact ID! You can receive it from the Xero Read step.
Choose: ID.
![New folder dialog with an open dropdown menu showing 'contacts()/ Id' and other variable options.](https://fluidlabs.com/images/documentation/xero-for-docusign/07642abcfa487242ca9bb410a68a15a3.webp)
Click Add.
![New folder modal with 'contacts\[/\]/id' in folder name field and 'Add' button.](https://fluidlabs.com/images/documentation/xero-for-docusign/2298919a63ceb4f765a38adc1ddaee66.webp)
✅ Result: The Folder entry will appear in the File Upload location UI and will contain the ID variable.
![User interface for selecting drive 'Contacts' and folder '\[contacts\[1\]/id\]' with red arrows.](https://fluidlabs.com/images/documentation/xero-for-docusign/67e8d8bfca3e37c06b44e90250fb7c0e.webp)

##### Final Expected Structure

After completing the steps above, your File Upload location should look like:

* Drive: Contacts
* Folder: `[contacts[1] / Id]`

This configuration attaches the uploaded file to the specified Contact.

### 4. Name the File

1. Click Next.
2. File Name: You can combine text with variables from previous steps to create a custom file name (e.g., `[Contact Number] - W-9 Form`).
   ![User interface for creating a custom filename using 'Contact Number' and 'w-9 Form' variables.](https://fluidlabs.com/images/documentation/xero-for-docusign/4a7166b7a2a36745a31c107be259a00c.webp)
3. Click Save.

### 5. Verification

If everything is set up correctly, the file will be attached to the selected contact ID.

1. Open the Contact in Xero.
2. Navigate to the Files tab to see the uploaded document.
   ![Web interface displaying a 'Files' tab with a 'Signed e-0.pdf' document attached.](https://fluidlabs.com/images/documentation/xero-for-docusign/c2905983eb25fa0ef125b1d2d4988edc.webp)


## FAQ & Troubleshooting

Here are the most common configuration issues and how to resolve them.

#### File Upload Issues

**Q: Why must I use the "Contact ID" for the Folder name?**

A: The Xero API requires a unique identifier to attach files to specific records. Names are not reliable because they can be duplicates. You must map the Folder to the `ID` variable (retrieved from the "Read from Xero" step). If you use a static text name for the folder, the upload will fail or go to the wrong location.

**Q: I don't see any files available in the "Select File" dropdown.**

A: This usually happens if the upload step is placed incorrectly in the workflow.

* Cause: The workflow hasn't generated a file yet at this stage.
* Solution: Ensure that a "Sign Document" step exists _before_ the File Upload step .

---

Xero for Docusign IAM is published by Fluidlabs. Docusign is a trademark of Docusign, Inc.