> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Data IO extension contract reference

> Learn how to implement the Docusign data IO extension.

The data IO (input/output) extension enables you to add data reading and writing steps to a custom [Workflow Builder workflow](/docs/workflow-builder-api/workflow-builder101/workflows).

You can include this extension when you [register an extension app](/extension-apps/build-an-extension-app/register). If you register the extension app [using a form](/extension-apps/build-an-extension-app/register/use-form), select the **Data Input Output** extension in the form-based UI, as shown in this figure:

![Creating a data IO extension app](/_fern-files/_img/4a1b88980e7d5c8307eccd7808051eb8b152193245c000c853c80b926ee4f731.webp)

If you register the extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), set the `extensions.template` value in your app manifest to `DataIO.Version6.DataInputOutput`.

This extension has five actions.  The action names you specify when you register an extension app depend on whether you register the app using a form or using an app manifest file. The app manifest file values listed here appear in the `actions.template` property.

| Form-based action name | App manifest file value              |
| ---------------------- | ------------------------------------ |
| Get Type Names         | `DataIO.Version6.GetTypeNames`       |
| Get Type Definitions   | `DataIO.Version6.GetTypeDefinitions` |
| Create Records         | `DataIO.Version6.CreateRecord`       |
| Patch Records          | `DataIO.Version6.PatchRecord`        |
| Search Records         | `DataIO.Version6.SearchRecords`      |

For details about what each action does and when it is invoked, see [Data IO extension overview](/extension-apps/extension-apps-101/supported-extensions/data-io).

You provide the details required for action execution when you register an extension app. See [Update extension and action settings](/extension-apps/build-an-extension-app/register/use-form/integration-details#update-extension-and-action-settings) for information about defining actions using the form-based registration process. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) for information about action properties in the app manifest file.

You can implement data input as a standalone capability without also implementing data output. To do this when registering an extension app using a form, select **Data Read** as the **Data Input Output Type**, as shown here:

![Create a read-only data IO extension app](/_fern-files/_img/e6999bb5eb364700d6663aa77dd0c8127793bd3fa44788fb19be7529f97ad1d2.webp)

To register an extension app that reads but does not write data in an app manifest file, implement only the `DataIO.Version6.SearchRecords`, `DataIO.Version6.GetTypeNames`, and `DataIO.Version6.GetTypeDefinitions` actions.

**Note:** You cannot implement data output as a standalone capability, because it uses the data input actions to find the records to update. If your extension must write data to your system of record, you must select **Data Read & Write** in the form-based UI, or implement all five data IO actions in the app manifest.

## Action contracts

#### Get Type Names (DataIO.Version6.GetTypeNames)

This action calls the external system of record to retrieve the names of the supported types. These types represent the data objects (or database table names) in your system of record. In Concerto nomenclature, these are referred to as *concepts*.

**Note:** The names of the types returned by this action will be used as input for the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) (`DataIO.Version6.GetTypeDefinitions`) action.

Get Type Names is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `DataIO.Version6.GetTypeNames`.

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{}
```

The input is an empty JSON object. There is no data specified, because this action returns all types supported by the external system of record.

### Response

```text
{
    "typeNames": [
        {
            "typeName": "dog",
            "label": "Dog",
            "description": "A friendly and fluffy creature"
        },
        {
            "typeName": "human",
            "label": "Human"
        }
    ]
}
```

| Property                  | Type       | Occurrence | Description                                                                |
| ------------------------- | ---------- | ---------- | -------------------------------------------------------------------------- |
| `typeNames`               | `Object[]` | Required   | A list of objects representing the types supported by the external system. |
| `typeNames[].typeName`    | `string`   | Required   | The name of the type.                                                      |
| `typeNames[].label`       | `string`   | Required   | A display-friendly name of the type that will be rendered in the UI.       |
| `typeNames[].description` | `string`   | Optional   | A description of the type.                                                 |

#### Get Type Definitions (DataIO.Version6.GetTypeDefinitions)

Type definitions are based on the [Concerto](https://concerto.accordproject.org/) data modeling language. In Concerto nomenclature, types are referred to as *concepts*. Given a list of types, the external system must return a list of [Concerto declarations](https://concerto.accordproject.org/docs/design/specification/model-classes/) representing the properties of each type. Your app proxy should initially fetch the schemas associated with these types and then convert them to Concerto’s [metamodel JSON format](https://concerto.accordproject.org/docs/design/specification/model-metamodel/)

. This enables Docusign to interpret your chosen system’s types consistently.

You can use [Concerto's CLI](https://concerto.accordproject.org/docs/tools/ref-concerto-cli/#concerto-parse) or [JavaScript API](https://concerto.accordproject.org/docs/reference/api/api-js-models-as-json) to convert your models.

**Get Type Definitions**  is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `DataIO.Version6.GetTypeDefinitions`.

**Note:** When creating a `RelationshipProperty`, ensure that the `type` that is being referred to is identified.

The following examples reflect an external system of record with two tables: **Dog** and **Human**.

The **Dog** type is defined as:

| Property | Type         | Label     | Constraints                                                               |
| -------- | ------------ | --------- | ------------------------------------------------------------------------- |
| Id       | String       | Dog ID    | * Required
* Read Only
* MaxLength = 18                                   |
| Name     | String       | Dog Name  | - Required
- Supports all CRUD operations
- MaxLength = 50                |
| Breed    | Breed (enum) | Dog Breed | * Optional
* Supports all CRUD operations                                 |
| Age      | Integer      | Dog Age   | - Optional
- Supports all CRUD operations
- MinValue = 0
- MaxValue = 100 |
| Owner    | Human        | Owners    | * Optional
* Array
* Doesn’t support any CRUD operations                  |

The **Breed** enum has the following values:

| Value          | Label           |
| -------------- | --------------- |
| Beagle         | Beagle          |
| GermanShepherd | German Shepherd |
| Other          | Other           |

The **Human** type is defined as:

| Property | Type   | Label       | Constraints                                                 |
| -------- | ------ | ----------- | ----------------------------------------------------------- |
| Email    | String | Human Email | * Required
* Supports Create, Read, Update
* MaxLength = 50 |
| Name     | String | Human Name  | - Optional
- Supports all CRUD operations                   |

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
    "typeNames": ["dog", "human", "cat"]
}
```

| Property    | Type       | Description                                                                                                                |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| `typeNames` | `string[]` | A list of names representing types in the external system. The client is requesting the converted schemas for those types. |

### Response

```text
{
  "declarations": [
    {
      "$class": "concerto.metamodel@1.0.0.ConceptDeclaration",
      "name": "dog",
      "isAbstract": false,
      "decorators": [
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Term",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Dog"
            }
          ]
        },
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Crud",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Createable,Readable,Updateable"
            }
          ]
        }
      ],
      "identified": {
        "$class": "concerto.metamodel@1.0.0.IdentifiedBy",
        "name": "Id"
      },
      "properties": [
        {
          "$class": "concerto.metamodel@1.0.0.StringProperty",
          "name": "Id",
          "isOptional": false,
          "isArray": false,
          "decorators": [
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Term",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Dog ID"
                }
              ]
            },
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Crud",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Readable"
                }
              ]
            }
          ],
          "lengthValidator": {
            "$class": "concerto.metamodel@1.0.0.StringLengthValidator",
            "maxLength": 18
          }
        },
        {
          "$class": "concerto.metamodel@1.0.0.StringProperty",
          "name": "Name",
          "isOptional": false,
          "isArray": false,
          "decorators": [
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Term",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Dog Name"
                }
              ]
            },
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Crud",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Createable,Readable,Updateable"
                }
              ]
            }
          ],
          "lengthValidator": {
            "$class": "concerto.metamodel@1.0.0.StringLengthValidator",
            "maxLength": 50
          }
        },
        {
            "$class": "concerto.metamodel@1.0.0.ObjectProperty",
            "name": "Breed",
            "isOptional": true,
            "isArray": false,
            "decorators": [
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Term",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Dog Breed"
                  }
                ]
              },
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Crud",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Createable,Readable,Updateable"
                  }
                ]
              }
            ],
            "type": {
                "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
                "name": "DogBreed_Enum"
            }
        },
        {
            "$class": "concerto.metamodel@1.0.0.IntegerProperty",
            "name": "Age",
            "isOptional": true,
            "isArray": false,
            "decorators": [
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Term",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Dog Age"
                  }
                ]
              },
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Crud",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Createable,Readable,Updateable"
                  }
                ]
              }
            ],
            "validator": {
              "$class": "concerto.metamodel@1.0.0.IntegerDomainValidator",
              "upper": 100,
              "lower": 0
            }
        },
        {
          "$class": "concerto.metamodel@1.0.0.RelationshipProperty",
          "name": "Owner",
          "isOptional": true,
          "isArray": true,
          "decorators": [
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Term",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Owners"
                }
              ]
            }
          ],
          "type": {
            "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
            "name": "Human"
          }
        }
      ]
    },
    {
        "$class": "concerto.metamodel@1.0.0.EnumDeclaration",
        "name": "DogBreed_Enum",
        "properties": [
          {
            "$class": "concerto.metamodel@1.0.0.EnumProperty",
            "name": "Beagle",
            "decorators": [
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Term",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Beagle"
                  }
                ]
              }
            ]
          },
          {
            "$class": "concerto.metamodel@1.0.0.EnumProperty",
            "name": "GermanShepherd",
            "decorators": [
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Term",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "German Shepherd"
                  }
                ]
              }
            ]
          },
          {
            "$class": "concerto.metamodel@1.0.0.EnumProperty",
            "name": "Other",
            "decorators": [
              {
                "$class": "concerto.metamodel@1.0.0.Decorator",
                "name": "Term",
                "arguments": [
                  {
                    "$class": "concerto.metamodel@1.0.0.DecoratorString",
                    "value": "Other"
                  }
                ]
              }
            ]
          }
        ]
    },
    {
      "$class": "concerto.metamodel@1.0.0.ConceptDeclaration",
      "name": "human",
      "isAbstract": false,
      "decorators": [
        {
          "$class": "concerto.metamodel@1.0.0.Decorator",
          "name": "Term",
          "arguments": [
            {
              "$class": "concerto.metamodel@1.0.0.DecoratorString",
              "value": "Human"
            }
          ]
        }
      ],
      "identified": {
        "$class": "concerto.metamodel@1.0.0.IdentifiedBy",
        "name": "Email"
      },
      "properties": [
        {
          "$class": "concerto.metamodel@1.0.0.StringProperty",
          "name": "Email",
          "isOptional": false,
          "isArray": false,
          "decorators": [
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Term",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Human Email"
                }
              ]
            },
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Crud",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Createable,Readable,Updateable"
                }
              ]
            }
          ],
          "lengthValidator": {
            "$class": "concerto.metamodel@1.0.0.StringLengthValidator",
            "maxLength": 50
          }
        },
        {
          "$class": "concerto.metamodel@1.0.0.StringProperty",
          "name": "Name",
          "isOptional": true,
          "isArray": false,
          "decorators": [
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Term",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Human Name"
                }
              ]
            },
            {
              "$class": "concerto.metamodel@1.0.0.Decorator",
              "name": "Crud",
              "arguments": [
                {
                  "$class": "concerto.metamodel@1.0.0.DecoratorString",
                  "value": "Createable,Readable,Updateable"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "errors": [
    {
      "typeName": "cat",
      "code": "SCHEMA_RETRIEVAL_FAILED",
      "message": "Failed to fetch the schema of cat from the external system of record"
    }
  ]
}
```

| Property       | Type                                                                                                                                                       | Occurrence | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `declarations` | [DeclarationUnion](https://github.com/accordproject/concerto/blob/main/packages/concerto-types/src/generated/unions/concerto.metamodel%401.0.0.ts#L90)`[]` | Required   | A list of schemas present in the external system. Each schema must be in the format of a Concerto `DeclarationUnion` object. This array contains schemas not only for the requested types, but also for any related types, subtypes, associated enums, and so on. In the example above, two definitions (`dog` and `human`) are fetched, along with the associated `DogBreed` enum. For more information about related types, see [Define related objects in a data model](/extension-apps/extension-apps-101/supported-extensions/data-io/related-objects). **Note:** Each concept and property must include a `Crud` decorator that indicates which CRUD operations can be applied. This is required for the Workflow Builder experience. CRUD operations can be used in any combination; however, certain operations are required for concepts and properties to appear in each step of the Workflow Builder UI. The required CRUD operations of each step are listed below. In a Workflow Builder data read scenario: - Step 1: `read` (concepts) - Step 2: `read` (properties) - Step 3: `read` (properties) In a Workflow Builder data write scenario: - Step 1: `create` or `update` (concepts) - Step 2: `read` (properties) - Step 3: `create` or `update` (properties) If no CRUD operations are intended for a property, there’s no need to include the CRUD decorator. |
| `errors`       | `GetTypeDefinitionError[]`                                                                                                                                 | Optional   | A list of errors associated with fetching or transforming the schemas.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

#### GetTypeDefinitionError

| Property   | Type     | Occurrence | Description                                                                                                                                    |
| ---------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `typeName` | `string` | Required   | The name of the type for which a declaration could not be returned.                                                                            |
| `code`     | `string` | Required   | An error code representing the issue. Must be one of the following values:- `unknown`
- `schemaRetrievalFailed`
- `schemaTransformationFailed` |
| `message`  | `string` | Required   | An error message providing more details about the issue.                                                                                       |

#### Create Record (DataIO.Version6.CreateRecord)

This action creates an object in the external system of record. The type (model) is specified by `typeName`, and the properties are specified in the `data` object.

Create Record is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `DataIO.Version6.CreateRecord`.

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
    "typeName": "dog",
    "idempotencyKey": "123-456-789",
    "data": {
        "Name": "Snoopy",
        "Breed": "Beagle"
    }
}
```

| Property         | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typeName`       | `string` | The type of the record to create.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `recordId*`      | `string` | An optional identifier of the new record. The external system may or may not accept this identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `idempotencyKey` | `string` | A unique key that is passed to the API to ensure that the request is processed only once, even if it is submitted multiple times. The idempotency key is unique for each call. If the same key is reused for identical requests, the server will recognize the repeated attempt and will not execute the operation. The server should store the state of the request associated with the idempotency key. When a request with a previously used key is received, the server should return the stored response instead of reprocessing the request. |
| `data`           | `object` | A key-value object representing the data to write to the new record. For information about the format for various data types, see [Data type standards](/extension-apps/extension-apps-101/supported-extensions/data-model#data-type-standards).                                                                                                                                                                                                                                                                                                   |

*\*Not always included in the JSON request. Your API proxy must handle the case in which this property is not present.*

### Response

```text
{
    "recordId": "abc-123-def-456"
}
```

| Property   | Type     | Occurrence | Description                                                                          |
| ---------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
| `recordId` | `string` | Required   | A unique identifier representing the record that was created in the external system. |

#### Patch Record (DataIO.Version6.PatchRecord)

This action updates an existing record. Only the attributes to be updated are included in the `data` object.

Patch Record is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `DataIO.Version6.PatchRecord`.

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
  "typeName": "dog",
  "idempotencyKey": "123-456-789",
  "recordId": "abc-123-def-456",
  "data": {
    "Name": "Marmaduke",
    "Breed": "Great Dane"
  }
}
```

| Property         | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typeName`       | `string` | The type of the record to update.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `idempotencyKey` | `string` | A unique key that is passed to the API to ensure that the request is processed only once, even if it is submitted multiple times. The idempotency key must be unique for each call. If the same key is reused for identical requests, the server will recognize the repeated attempt and will not execute the operation. The server should store the state of the request associated with the idempotency key. When a request with a previously used key is received, the server should return the stored response instead of reprocessing the request. |
| `recordId`       | `string` | The identifier of the existing record.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data`           | `object` | Represents the attributes to update in the existing record. This object includes only the attributes that should be updated. It does not include the existing attributes that will remain unchanged. For information about the format for various data types, see [Data type standards](/extension-apps/extension-apps-101/supported-extensions/data-model#data-type-standards).                                                                                                                                                                        |

### Response

```text
{
	"success": true
}
```

| Property  | Type      | Occurrence | Description                                            |
| --------- | --------- | ---------- | ------------------------------------------------------ |
| `success` | `boolean` | Required   | Indicates whether the record was successfully updated. |

#### Search Records (DataIO.Version6.SearchRecords)

This action searches for one or more records in the external system of record. It uses a [custom query filtering language](/extension-apps/extension-app-reference/extension-contracts/custom-query-language). Your app proxy must convert the provided query into one supported by your external system of record. Then apply the query and return the results.

Workflows use the Search Records action in **Read from** steps and **Writeback to** steps. For a **Read from** step, the action returns records that can be used in subsequent workflow steps, such as a **Collect Data with Web Forms** step that displays values from the system of record in a web form. For a **Writeback to** step that updates a record, a Search Records action identifies the record to be updated. For each step type, the number of records that Workflow Builder supports in the Search Records response is as follows:

| Step type        | Maximum number of records in a Search Records response | Workflow behavior if the maximum is exceeded                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read from**    | 5                                                      | Workflow Builder uses only the first five records in the response in subsequent processing. If the Search Records response contains fewer records than referenced in subsequent workflow processing, the missing record references will be populated with empty values. For example, if a web form includes fields for four emergency contacts, but the search returns only three records, then the web form fields for the fourth contact will be empty. |
| **Writeback to** | 1                                                      | The workflow instance execution fails with this error: <pre />                                                                                                                                                                                                                                                                                                                                                                                            |

Docusign recommends that extension app developers provide documentation guiding workflow process builders to use only search queries that retrieve the supported number of records.

**Note:** When configuring a Workflow Builder **Read from** step, process builders can use the preview feature to see which records the search will return. See [Configure a Read from Salesforce Step ](https://support.docusign.com/s/document-item?bundleId=qwr1706590641805\&topicId=idr1713985144297.html) for details about previewing query results.

Search Records is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `DataIO.Version6.SearchRecords`.

### HTTP method

This action initiates a POST request to the external API service.

### Example requests

#### Example request 1

This example request shows a query of `dog` objects where the breed attribute is `Beagle`.

```text
{
    "query": {
        "$class": "com.docusign.connected.data.queries@1.0.0.Query",
        "attributesToSelect": ["Id", "Name"],
        "from": "dog",
        "queryFilter": {
            "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
            "operation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "Breed",
                    "type": "STRING",
                    "isLiteral": false
                },
                "operator": "EQUALS",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "Beagle",
                    "type": "STRING",
                    "isLiteral": true
                }
            }
        }
    },
    "pagination": {
        "limit": 3,
        "skip": 0
    }
}
```

#### Example request 2

This example request shows a query of `dog` objects where the `age` attribute is greater than or equal to `8`.

**Note:** Although the data IO extension supports the `operator` value shown in this example, Workflow Builder supports only the **Equal to** operator.

```text
{
    "query": {
        "$class": "com.docusign.connected.data.queries@1.0.0.Query",
        "attributesToSelect": ["Id", "Name", "Age"],
        "from": "dog",
        "queryFilter": {
            "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
            "operation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "age",
                    "type": "INTEGER",
                    "isLiteral": false
                },
                "operator": "GREATER_THAN_OR_EQUALS_TO",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "8",
                    "type": "INTEGER",
                    "isLiteral": true
                }
            }
        }
    },
    "pagination": {
        "limit": 3,
        "skip": 0
    }
}
```

#### Example request 3

This example request shows a query of `dog` objects where the owner’s name is in the system.

**Note:** Although the data IO extension supports the `operator` value shown in this example, Workflow Builder supports only the **Equal to** operator.

```text
{
    "query": {
        "$class": "com.docusign.connected.data.queries@1.0.0.Query",
        "attributesToSelect": ["Id", "Name", "Owner"],
        "from": "dog",
        "queryFilter": {
            "$class": "com.docusign.connected.data.queries@1.0.0.QueryFilter",
            "operation": {
                "$class": "com.docusign.connected.data.queries@1.0.0.ComparisonOperation",
                "leftOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "Owner",
                    "type": "ARRAY",
                    "isLiteral": false
                },
                "operator": "CONTAINS",
                "rightOperand": {
                    "$class": "com.docusign.connected.data.queries@1.0.0.Operand",
                    "name": "Name",
                    "type": "STRING",
                    "isLiteral": true
                }
            }
        }
    },
    "pagination": {
        "limit": 3,
        "skip": 0
    }
}
```

| Property           | Type                                                                                                  | Description                                                                                                                                                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`            | [IQuery](/extension-apps/extension-app-reference/extension-contracts/custom-query-language#reference) | A query expression. See [Custom query language reference](/extension-apps/extension-app-reference/extension-contracts/custom-query-language) for the detailed schema.                                                            |
| `pagination`       | `object`                                                                                              | Represents pagination parameters used to control the number of records returned in a response. For example, if `limit` is set to `10` and `skip` is set to `5`, the response should include the sixth through fifteenth records. |
| `pagination.limit` | `number`                                                                                              | The maximum number of records to be returned per page.                                                                                                                                                                           |
| `pagination.skip`  | `number`                                                                                              | The number of records to bypass before taking the records to return.                                                                                                                                                             |

### Example responses

#### Example response 1

```text
{
    "records": [
        {
            "Id": "abc-123-def-456",
            "Name": "Snoopy"
        },
        {
            "Id": "aaa-000-aaa-111",
            "Name": "Francis"
        }
    ]
}
```

#### Example response 2

```text
{
    "records": [
        {
            "Id": "aaa-000-aaa-111",
            "Name": "Francis",
		"Age": "9"
        }
    ]
}
```

#### Example response 3

```text
{
    "records": [
        {
            "Id": "bbb-222-bbb-333",
            "Name": "Nami",
		"Owner": ["example1@email.com", "Hank"]
        },
        {
            "Id": "aaa-000-aaa-111",
            "Name": "Francis",
            "Owner": ["example2@email.com", "Eleanor"]
        }
    ]
}
```

| Property  | Type       | Occurrence | Description                                                                                                                                                                                                                                                                                                                                                                                             |
| --------- | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `records` | `object[]` | Required   | A list of objects representing each record. The properties are those specified by `query.attributesToSelect` in the request. If no matching record is found, the response should be an empty `records` array, not an error. For information about the format for various data types, see [Data type standards](/extension-apps/extension-apps-101/supported-extensions/data-model#data-type-standards). |

### Multi-level querying

Multi-level querying enables retrieving data beyond the top level of an object model by accessing deeply nested properties. Unlike basic queries that return only direct attributes, multi-level queries allow for structured traversal into objects, lists, and references to extract targeted information. This approach is essential when working with complex data models where objects contain deeply nested properties or maintain relationships with other entities.

For more information about relationships, see [Define related objects in a data model](/extension-apps/extension-apps-101/supported-extensions/data-io/related-objects).

To support multi-level querying, a structured format is required to define how data should be accessed at different depths. Queries must specify whether to return full objects, individual properties, or entire sets of related attributes. One effective method for structuring these queries is through a standardized format that outlines the selection path.

This dataset represents a structured object containing personal details, addresses, and associated property information, which will be used to demonstrate how multi-level queries can retrieve specific attributes, nested properties, and relational values.

### Person Table

| id         | name | age | country |
| ---------- | ---- | --- | ------- |
| person_001 | John | 30  | Japan   |

### Address Table

| id           | streetName         | houseNumber | zip_code | zip_extension |
| ------------ | ------------------ | ----------- | -------- | ------------- |
| add_xyz12345 | John Drive         | 145         | 12345    | 5723          |
| efg_alp94565 | DocuSign Tower St. | 567         | 34512    | 2357          |

### House Defects Table

| id         | address_id   | type        | description   | severity |
| ---------- | ------------ | ----------- | ------------- | -------- |
| defect_001 | add_xyz12345 | Ventilation | Food in ducts | Medium   |
| defect_002 | add_xyz12345 | Dry wall    | Mold          | High     |
| defect_003 | efg_alp94565 | Wall        | Too blue      | Low      |

### Causes Table

| id        | defect_id  | reason             | recommended       |
| --------- | ---------- | ------------------ | ----------------- |
| cause_001 | defect_001 | Blocked air filter | Replace filter    |
| cause_002 | defect_001 | Pest infestation   | Call exterminator |
| cause_003 | defect_002 | Leaky pipes        | Repair plumbing   |

```text
namespace "example"

concept Person {
	o String id
	o String name
	o Integer age
	o String country
	o Address[] addresses
}

concept Address {
	o String id
	o String streetName
	o Integer houseNumber
	o Zip zip
	o HouseDefect[] houseDefects
}

concept Zip {
	o Integer code
	o Integer extension
}

concept HouseDefect {
	o String id
	o String type
	o String description
	o String severity
	--> Cause[] causes //Relationship to Cause table
}

concept Cause {
	o String id
	o String reason
o String recommendedFix
---> HouseDefect defect //Relationship back to HouseDefect
}
```

This table details the supported query structures and provides concrete examples of how multi-level querying can be applied. Note that support for certain features may vary depending on the application, as some systems may not support all querying capabilities.

| Example type                                                            | Query   | Expected output |
| ----------------------------------------------------------------------- | ------- | --------------- |
| Query a Primitive Object (Existing Functionality)                       | <pre /> | <pre />         |
| Query a specific property inside an object                              | <pre /> | <pre />         |
| Query an Embedded Array                                                 | <pre /> | <pre />         |
| Query a specific property for each embedded object in an array          | <pre /> | <pre />         |
| Query a relationship property (return the ID)                           | <pre /> | <pre />         |
| Query a relationship property and get a specific property               | <pre /> | <pre />         |
| Query a Relationship Property and Retrieve All Properties               | <pre /> | <pre />         |
| Query a Relationship Property for Each and Retrieve a Specific Property | <pre /> | <pre />         |
| Query a Relationship Property for Each and Retrieve All Properties      | <pre /> | <pre />         |

## Error handling

If a data IO action encounters an error, it should return an HTTP error code 400, 404, or 500 along with a message describing the error.

Example error responses:

```text
HttpErrorCode: 404
{
   code: NOT_FOUND
   message: No record was found for the provided recordId
}
```

**Note:** A 404 error should not be returned if a Search Records request results in no matching records. Instead, return an empty `records` array.

```text
HttpErrorCode: 400
{
   code: BAD_REQUEST
   message: Cannot update age property of the record
}
```

```text
HttpErrorCode: 500
{
   code: INTERNAL_SERVER_ERROR
   message: Unknown error when trying to update record
}
```

This error structure applies to all actions. Developers are responsible for providing a code and message for each error.

## Next steps

* [Data IO extension workflow test](/extension-apps/build-an-extension-app/test/functional-tests/data-io-workflow)
* [Example extension app use cases](/extension-apps/build-an-extension-app/example-use-case)
* [Data IO extension overview](/extension-apps/extension-apps-101/supported-extensions/data-io)