> 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 model

> Learn about the data model that Docusign extension apps use.

Docusign models definitions using the [Concerto](https://concerto.accordproject.org/docs/intro/) open-source schema language.  Both the [connected fields extension](/extension-apps/extension-apps-101/supported-extensions/connected-fields) and the [data IO extension](/extension-apps/extension-apps-101/supported-extensions/data-io) use this model. See [Why Concerto?](https://concerto.accordproject.org/docs/why-concerto) for details about the features and advantages of Concerto.

## Transform logic

If your system of record does not already use the Concerto data model, you must implement transform logic that maps your definitions to Concerto data types as part of your **Get Type Definitions** implementation. When **Get Type Definitions** is called, this transform will convert the definitions into a Concerto data model format before returning it to Docusign.

* For more information about Concerto, see the [Concerto](https://concerto.accordproject.org/docs/intro/) open-source documentation.
* For details about Concerto model use with extensions that require it, see:

  * [Connected fields extension contract reference](/extension-apps/extension-app-reference/extension-contracts/connected-fields)
  * [Data IO extension contract reference](/extension-apps/extension-app-reference/extension-contracts/data-io)

There are many ways to map your definitions to Concerto types. The following sections list each data source type and a mapping recommendation to a  supported Concerto type. Where applicable, each section also lists the type of value that each Concerto type will be rendered as in workflows (for data IO) and eSignature envelopes (for connected fields).

### Class declarations

**Concerto type:** [Concepts](https://concerto.accordproject.org/docs/design/specification/model-classes)

**Rendered in Workflow Builder read and write steps as:** A list of objects from which a preparer can choose one to read from or write to.

**Rendered in eSignature envelopes as:** Connected field groups that can be added to a document.

**Notes:** Concepts are similar to class declarations in most object-oriented languages, in that they may have a super-type and a set of typed [properties](/extension-apps/extension-apps-101/supported-extensions/data-model#properties).

### Properties

Class declarations contain properties, and each property has a unique name within its class declaration. A property takes one of the types listed in the sections below. Expand each section for details.

#### Boolean

**Concerto type:** [Boolean](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** Two variables are emitted for each boolean field:

* A boolean variable — for example, `IsActive`
* A `checkboxGroup` variable — for example, `IsActive` (Checkbox group). The `checkboxGroup` variable enables downstream steps such as Web Forms to render the field as a checkbox.

**Rendered in eSignature envelopes as:** Checkbox

**Notes:**

* In write steps and where clauses, both boolean and string variables can be mapped to a boolean field.
* When a process builder manually enters a value for a boolean field in a write step or where clause, Workflow Builder displays a free-form text input rather than a true/false dropdown. If a string is entered, it must match a valid boolean value.

#### DateTime

**Concerto type:** [DateTime](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** DateTime

**Rendered in eSignature envelopes as:** Text field with date validation

**Notes:** In eSignature, the date format defaults to `MM/dd/yyyy` format but can be changed. See [Validation Options for Text Fields ](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=fcx1578456356971.html) for the supported date formats.

#### Double

**Concerto type:** [Double](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** Double

**Rendered in eSignature envelopes as:** Text

**Notes:** In eSignature, template or envelope preparers can use [data validation](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=jgd1578456357365.html) to require users to enter text field values in specific formats, such as numeric values.

#### Foreign key relationship

**Concerto type:** [Relationship](https://concerto.accordproject.org/docs/design/specification/model-relationships)

**Rendered in Workflow Builder read and write steps as:** Related object

**Rendered in eSignature envelopes as:** Not supported

**Notes:** A Concerto relationship property should be used to define a foreign key relationship to any identifiable type, that is a type that has been declared with either the `identified by` or `identified` properties. These types must be defined within your own type system. Otherwise, these types will not be resolved and cause an error.

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

#### Integer

**Concerto type:** [Integer](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** Integer

**Rendered in eSignature envelopes as:** Text

**Notes:** In eSignature, template or envelope preparers can use [data validation](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=jgd1578456357365.html) to require users to enter text field values in specific formats, such as numeric values.

#### Long

**Concerto type:** [Long](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** Long

**Rendered in eSignature envelopes as:** Text

**Notes:** In eSignature, template or envelope preparers can use [data validation](https://support.docusign.com/s/document-item?bundleId=gbo1643332197980\&topicId=jgd1578456357365.html) to require users to enter text field values in specific formats, such as numeric values.

#### Object

**Concerto type:** [Object](https://concerto.accordproject.org/docs/design/specification/model-introduction/#objects)

**Rendered in Workflow Builder read and write steps as:** Object property

**Rendered in eSignature envelopes as:** Object property

**Notes:** An object property can be used to define a child relationship to any complex type (concepts or enumerations).

#### String

**Concerto type:** [String](https://concerto.accordproject.org/docs/design/specification/model-properties/#primitive-types)

**Rendered in Workflow Builder read and write steps as:** String

**Rendered in eSignature envelopes as:** Text

> **Note**
>
> Every name for a type declaration must be unique, and properties within declarations must be unique. If a data model in a **Get Type Names** or **Get Type Definitions** response violates either of these requirements, this will cause an error. You can use the [Concerto VSCode extension](https://concerto.accordproject.org/docs/tools/vscode/) to validate your data model and check for errors.

### Enumerations

**Concerto type:** [Enumerations](https://concerto.accordproject.org/docs/design/specification/model-enums)

**Rendered in Workflow Builder read and write steps as:** Three variables are emitted for each enum field:

* A dropdown variable — for example, State
* An API value variable (for example, State (API value)) — a string variable
* An option text variable (for example, State (Option text)) — a string variable.

**Rendered in eSignature envelopes as:** Radio buttons

**Notes:**

* In write steps and where clauses, both enum and string variables can be mapped to an enum field.
* When a process builder manually enters a value for an enum field, Workflow Builder displays a free-form text input rather than a dropdown.

### Decorators

In Concerto, [decorators](https://concerto.accordproject.org/docs/design/specification/model-decorators) are annotations that can be placed on declarations and properties to extend the metamodel definition.

For connected fields extensions, `term` decorators on concepts and properties appear as display names in eSignature. The `VerifiableType` decorator indicates that an object is verifiable from eSignature envelopes. The `IsRequiredForVerifyingType` decorator indicates that a property is required for verifying the object. See [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/connected-fields#get-type-definitions) for more information.

For data IO extensions, `term` decorators on concepts and properties appear as display names in Workflow Builder workflows. CRUD operations determine which workflow steps objects and fields appear in. If readable, they appear in the read step. If updateable/creatable, they appear in the write step. See [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) for more information.

## Data type standards

Docusign enforces standards for data values that it sends to and receives from external API services. The external service must be able to accept values in the format that Docusign sends. If the service requires a different format for back-end processing, the service must convert values internally to the required format. Data values that the external service provides in responses to Docusign must also adhere to these standards. If a response from an external service includes a value in an unsupported format, the value may not appear correctly in a Workflow Builder workflow step or in an eSignature envelope. For example, if a returned value for a data IO **Search Records** action is not in a supported format, the web form field that displays that value may be empty at workflow instance run time.

In the current release, data type standards apply to:

* [Date-time values](/extension-apps/extension-apps-101/supported-extensions/data-model#date-time-values)
* [Email addresses](/extension-apps/extension-apps-101/supported-extensions/data-model#email-addresses)
* [Phone numbers](/extension-apps/extension-apps-101/supported-extensions/data-model#phone-numbers)
* [Currency values](/extension-apps/extension-apps-101/supported-extensions/data-model#currency-values)

Standards for other data types will be implemented in future releases.

### Date-time values

> **Note**
>
> Date-time standards are currently applicable only for data IO extensions. The standards will be implemented for connected fields extensions in a future release.

#### Requests from Docusign to the API service

Docusign uses this ISO 8601 UTC format for date-time values in requests to external API services:

`YYYY-MM-DDTHH:mm:ss.SSSZ`

For example:

`2025-03-17T10:45:00.000Z`

The extensions and requests that use this format are:

* [Data IO](/extension-apps/extension-app-reference/extension-contracts/data-io)

  * [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-create-record)
  * [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record)
  * [Search Records](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records)

#### Responses from the API service

Docusign supports these ISO 8601 formats for date-time values in responses to the data IO extension [Search Records](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records) action:

| Format                         | Example                          | Notes                                                                         |
| ------------------------------ | -------------------------------- | ----------------------------------------------------------------------------- |
| `YYYY-MM-DD`                   | `2024-12-27`                     | For values in this format, Docusign defaults to a time value of midnight UTC. |
| `YYYY-MM-DDTHH:mm:ssZ`         | `2024-12-27T13:24:03Z`           |                                                                               |
| `YYYY-MM-DDTHH:mm:ss±HH:mm`    | `2024-12-27T13:24:03+12:00`      |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.SZ`       | `2024-12-27T13:24:03.9Z`         |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.SSZ`      | `2024-12-27T13:24:03.91Z`        |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.SSSZ`     | `2024-12-27T13:24:03.917Z`       |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.S±HH:mm`  | `2024-12-27T13:24:03.9Z+12:00`   |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.SS±HH:mm` | `2024-12-27T13:24:03.91Z+12:00`  |                                                                               |
| `YYYY-MM-DDTHH:mm:ss.SSS±HH:m` | `2024-12-27T13:24:03.917Z+12:00` |                                                                               |

### Currency values

For currency values, Docusign supports the [Accord Project](https://accordproject.org/) [MonetaryAmount](https://models.accordproject.org/money@0.3.0.html) type. The type includes these properties:

| Property     | Type         | Occurrence | Description                                                                                                                                     |
| ------------ | ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| doubleValue  | double       | Required   | The amount of currency.                                                                                                                         |
| currencyCode | CurrencyCode | Required   | The currency code. See [MonetaryAmount](https://models.accordproject.org/money@0.3.0.html) for the full list of supported currency code values. |

Using the Accord `monetaryAmount` type provides the following benefits:

* Workflow Builder recognizes this type in the extension app's data model and displays it in the UI as a currency amount, making it easier for process builders to configure workflows.
* You can read, create, and update for records containing currency values through the standard Data IO action model, rather than needing custom integration logic.
* The amount and currencyCode are stored together, giving extensions a consistent payload shape.

**Note:** The Accord `monetaryAmount` type is supported only for data IO extensions.

#### How to specify the Accord Project MonetaryAmount type

To include the Accord Project `MonetaryAmount` type as a property for an object in an extension app's data model, the response to the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) request must specify these values:

* **\$class:** `concerto.metamodel@1.0.0.ObjectProperty`
* **name:** `MonetaryAmount`
* **type.\$class:** `concerto.metamodel@1.0.0.TypeIdentifier`
* **type.name:** `MonetaryAmount`
* **type.namespace:** `org.accordproject.money@0.3.0`

For example:

```text
{
  "$class": "concerto.metamodel@1.0.0.ObjectProperty",
  "decorators": [
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Annual Revenue",
        },
      ],
      "name": "Term",
    },
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Createable,Readable,Updateable",
        },
      ],
      "name": "Crud",
    },
  ],
  "isArray": false,
  "isOptional": true,
  "name": "AnnualRevenue",
  "type": {
    "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
    "name": "MonetaryAmount",
    "namespace": "org.accordproject.money@0.3.0",
  },
}
```

#### MonetaryAmount type in requests from Docusign to the API service

If the external API service's response to the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) request specifies the Accord `MonetaryAmount` type for a property, Docusign will use this type for the property in these requests to the external service:

* [Data IO](/extension-apps/extension-app-reference/extension-contracts/data-io)

  * [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-create-record)
  * [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record)
  * [Search Records](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records)

An example **Create Record** request to the external service using the Accord `MonetaryAmount` type looks like this:

```text
{
  "typeName": "Account",
  "idempotencyKey": "a067f247-xxxx-xxxx-xxxx-3b960b71058e",
  "data": {
    "firstName": "Sally",
    "lastName": "Signer",
    "contractAmount": {
      "doubleValue": "123.45",
      "currencyCode": "USD"
    }
  }
}
```

#### MonetaryAmount type in responses from the API service

If the external API service's response to the **Get Type Definitions** request specifies the Accord `MonetaryAmount` type for a property, Docusign expects the external service to use this type for the property in responses to the **Search Records** action.

#### Adopt the MonetaryAmount type for production extension apps

If you adopt the Accord Project `MonetaryAmount` type for an extension app that is in production, Docusign recommends the following to avoid transition issues:

* After the external data source's data model has been updated with the Accord type, [refresh the connection](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=qkv1716320270335.html)  for each Docusign account that has the extension app installed.
* For each workflow that uses the extension app, [edit the workflow steps](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=zlm1698880256815.html) that reference the property, and replace the old string version of the property with the updated format.

To ensure backward compatibility for workflows that have not been updated, make sure that the external service logic can handle requests regardless of whether they format the property as a string or the Accord type.

### Email addresses

For email addresses, Docusign supports the [Accord Project](https://accordproject.org/) [EmailAddress](https://github.com/accordproject/models/blob/main/src/contact%401.0.0.cto) type. This type has a maximum length of 254 characters.

Using the Accord `EmailAddress` type provides these benefits:

* It adheres to Internet Engineering Task Force (IETF) standards. See the [type definition](https://github.com/accordproject/models/blob/main/src/contact%401.0.0.cto) for details.
* Workflow Builder recognizes this type in an extension app's data model and displays it in the UI as an email address, making it easier for process builders to configure workflows.

If you prefer not to use the Accord `EmailAddress` type, your extension app can define email addresses as strings.

**Note:** The Accord `EmailAddress` type is supported only for data IO extensions.

#### How to specify the Accord Project EmailAddress type

To include the Accord Project `EmailAddress` type as a property for an object in an extension app's data model, make sure that the response to the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) request specifies these values:

* **`$class:`** `concerto.metamodel@1.0.0.ObjectProperty`
* **`name:`** `EmailAddress`
* **`type.$class:`** `concerto.metamodel@1.0.0.TypeIdentifier`
* **`type.name:`** `EmailAddress`
* **`type.namespace:`** `org.accordproject.contact@1.0.0`

For example:

```text
{
  "$class": "concerto.metamodel@1.0.0.ObjectProperty",
  "name": "EmailAddress",
  "type": {
    "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
    "name": "EmailAddress",
    "namespace": "org.accordproject.contact@1.0.0"
  },
  "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"
        }
      ]
    }
  ]
}
```

#### EmailAddress type in requests from Docusign to the API service

If the external API service's response to the **Get Type Definitions** request specifies the Accord `EmailAddress` type for a property, Docusign will use this type for the property in these requests to the external service:

* [Data IO](/extension-apps/extension-app-reference/extension-contracts/data-io)

  * [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-create-record)
  * [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record)
  * [Search Records](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records)

An example **Create Record** request to the external service using the Accord `EmailAddress` type looks like this:

```text
{
  "typeName": "Contact",
  "idempotencyKey": "123-456-789",
  "data": {
    "firstName": "Sally",
    "lastName": "Signer",
    "EmailAddress": "sally.signer@email.com"
  }
}
```

For additional code examples including a data model definition and example search query, see the [data IO reference implementation](https://github.com/docusign/extension-app-data-io-reference-implementation).

#### EmailAddress type in responses from the API service

If the external API service's response to the **Get Type Definitions** request specifies the Accord `EmailAddress` type for a property, Docusign expects the external service to use this type for the property in responses to the **Search Records** action.

#### Adopt the EmailAddress type for production extension apps

If you adopt the Accord Project `EmailAddress` type for an extension app that is in production, Docusign recommends the following to avoid transition issues:

1. After the external data source's data model has been updated with the Accord type, [refresh the connection](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=qkv1716320270335.html) for each Docusign account that has the extension app installed.
2. For each Workflow Builder workflow that uses the extension app, [edit the workflow steps](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=zlm1698880256815.html) that reference the property, and replace the old string version of the property with the updated format.
3. To ensure backward compatibility for workflows that have not been updated, make sure that the external service logic can handle requests regardless of whether they format the property as a string or the Accord type.

### Phone numbers

For phone numbers, Docusign supports the [Accord Project](https://accordproject.org/) [PhoneNumber](https://github.com/accordproject/models/blob/main/src/contact%401.0.0.cto) type. The type includes these properties:

| Property           | Type     | Occurrence | Description                                                                                                                                                                                                                               |
| ------------------ | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number`           | `string` | Required   | The phone number. **Note:** Although the Accord definition allows special characters in this value, Docusign requires a normalized format with no special characters such as spaces, brackets, plus signs, or hyphens. Maximum length: 32 |
| `normalizedNumber` | `string` | Optional   | The phone number. Maximum length: 15                                                                                                                                                                                                      |
| `extension`        | `string` | Optional   | A phone extension. Maximum length: 6                                                                                                                                                                                                      |
| `countryCode`      | `string` | Required   | The country code. Maximum length: 7                                                                                                                                                                                                       |

Using the Accord `PhoneNumber` type provides the following benefits:

* It adheres to International Telecommunication Union (ITU) standards. See the [type definition](https://github.com/accordproject/models/blob/main/src/contact%401.0.0.cto) for details.
* Workflow Builder recognizes this type in the extension app's data model and displays it in the UI as a phone number, making it easier for process builders to configure workflows.
* Sending phone number components to the external system in separate properties makes it easier to apply business logic to the values.

If you prefer not to use the Accord `PhoneNumber` type, your extension app can define phone numbers as strings.

**Note:** The Accord `PhoneNumber` type is supported only for data IO extensions.

#### How to specify the Accord Project PhoneNumber type

To include the Accord Project `PhoneNumber` type as a property for an object in an extension app's data model, the response to the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) request must specify these values:

* **`$class:`** `concerto.metamodel@1.0.0.ObjectProperty`
* **`name:`** `PhoneNumber`
* **`type.$class:`** `concerto.metamodel@1.0.0.TypeIdentifier`
* **`type.name:`** `PhoneNumber`
* **`type.namespace:`** `org.accordproject.contact@1.0.0`

For example:

```text
{
  "$class": "concerto.metamodel@1.0.0.ObjectProperty",
  "name": "PhoneNumber",
  "type": {
    "$class": "concerto.metamodel@1.0.0.TypeIdentifier",
    "name": "PhoneNumber",
    "namespace": "org.accordproject.contact@1.0.0"
  },
  "isOptional": true,
  "isArray": false,
  "decorators": [
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "name": "Term",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Phone Number"
        }
      ]
    },
    {
      "$class": "concerto.metamodel@1.0.0.Decorator",
      "name": "Crud",
      "arguments": [
        {
          "$class": "concerto.metamodel@1.0.0.DecoratorString",
          "value": "Createable,Readable,Updateable"
        }
      ]
    }
  ]
}
```

#### PhoneNumber type in requests from Docusign to the API service

If the external API service's response to the [Get Type Definitions](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-get-type-definitions) request specifies the Accord `PhoneNumber` type for a property, Docusign will use this type for the property in these requests to the external service:

* [Data IO](/extension-apps/extension-app-reference/extension-contracts/data-io)

  * [Create Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-create-record)
  * [Patch Record](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-patch-record)
  * [Search Records](/extension-apps/extension-app-reference/extension-contracts/data-io#dataio-version6-search-records)

An example **Create Record** request to the external service using the Accord `PhoneNumber` type looks like this:

```text
{
  "typeName": "Contact",
  "idempotencyKey": "123-456-789",
  "data": {
    "firstName": "Sally",
    "lastName": "Signer",
    "phoneNumber": {
      "number": "4155551212",
      "normalizedNumber": "4155551212",
      "extension": "444",
      "countryCode": "1"
    }
  }
}
```

For additional code examples including a data model definition and example search query, see the [data IO reference implementation](https://github.com/docusign/extension-app-data-io-reference-implementation).

#### PhoneNumber type in responses from the API service

If the external API service's response to the **Get Type Definitions** request specifies the Accord `PhoneNumber` type for a property, Docusign expects the external service to use this type for the property in responses to the **Search Records** action.

In addition, `PhoneNumber` values must adhere to these requirements:

* `number` and `countryCode` must be included.
* If supplied in the response, the values for `normalizedNumber` and `number` must be the same.
* All `PhoneNumber` property values must be in a normalized format with no special characters such as spaces, brackets, plus signs, or hyphens.

#### Adopt the PhoneNumber type for production extension apps

If you adopt the Accord Project `PhoneNumber` type for an extension app that is in production, Docusign recommends the following to avoid issues with the transition:

1. After the external data source's data model has been updated with the Accord type, [refresh the connection](https://support.docusign.com/s/document-item?bundleId=ous1698169987748\&topicId=qkv1716320270335.html) for each Docusign account that has the extension app installed.
2. For each workflow that uses the extension app, [edit the workflow steps](https://support.docusign.com/s/document-item?bundleId=yff1696971835267\&topicId=zlm1698880256815.html) that reference the property, and replace the old string version of the property with the updated format.
3. To ensure backward compatibility for workflows that have not been updated, make sure that the external service logic can handle requests regardless of whether they format the property as a string or the Accord type.

## Define an array for use with dynamic recipients

Workflow Builder enables you to read in an array of recipients from your system of record and send envelopes to them in a **Send Documents for Signature** step. See [Add a List of Participants to a Workflow Step](https://support.docusign.com/s/document-item?bundleId=qwr1706590641805\&topicId=tskc3380b05-3536-4b1a-956b-ff5c7795ecfb.html) for details on the Workflow Builder setup.

To support this feature with a [data IO](/extension-apps/extension-apps-101/supported-extensions/data-io) extension app, your data model object that defines recipients must meet these requirements:

* It includes an array definition. For example, if the recipient information is in a `Contact` object, you can add a `ContactList` array to the object. When you set up your workflow, `ContactList` will appear as a related list for the `Contact` object, and you can select recipient properties from the list to retrieve from the system of record.
* It includes the properties listed below. When you set up your workflow, you map these properties to fields associated with a workflow participant.

| Property              | Type                                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------- |
| Participant role name | `string`                                                                                                       |
| Participant name      | `string`                                                                                                       |
| Participant email     | [EmailAddress](/extension-apps/extension-apps-101/supported-extensions/data-model#email-addresses) or `string` |
| Participant phone     | [PhoneNumber](/extension-apps/extension-apps-101/supported-extensions/data-model#phone-numbers)                |

Below is an example `Contact` object definition that meets the above requirements:

```text
@Term("Contact")
@Crud("Createable,Readable,Updateable,Deletable")
concept Contact identified by Id {
    @Term("Contact ID")
    @Crud("Readable")
    o String Id

    @Term("Full Name")
    @Crud("Createable,Readable,Updateable")
    o String fullName

    @Term("Role")
    @Crud("Createable,Readable,Updateable")
    o String role

    @Term("Email")
    @Crud("Createable,Readable,Updateable")
    o EmailAddress email optional

    @Term("Phone")
    @Crud("Createable,Readable,Updateable")
    o PhoneNumber phone optional

    @Term("ContactList")
    @Crud("Createable,Readable,Updateable")
    --> Contact[] ContactList optional
}
```

## Next steps

* Find out more about the [data IO extension](/extension-apps/extension-apps-101/supported-extensions/data-io).
* Get an overview of the [connected fields extension](/extension-apps/extension-apps-101/supported-extensions/connected-fields).
* Explore the options for [testing](/extension-apps/build-an-extension-app/test) an extension app.