Data model

Docusign models definitions using the Concerto open-source schema language. Both the connected fields extension and the data IO extension use this model. See 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 open-source documentation.

• For details about Concerto model use with extensions that require it, see:

  • Connected fields extension contract reference
  • Data IO extension contract reference

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

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.

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.

Enumerations

Concerto type: Enumerations

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 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 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 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
• Email addresses
• Phone numbers
• Currency values

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

Date-time values

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

  • Create Record
  • Patch Record
  • 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 action:

Currency values

For currency values, Docusign supports the Accord Project MonetaryAmount type. The type includes these properties:

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

{
  "$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 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

  • Create Record
  • Patch Record
  • Search Records

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

{
  "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 for each Docusign account that has the extension app installed.
• For each workflow that uses the extension app, edit the workflow steps 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 EmailAddress 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 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 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:

{
  "$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

  • Create Record
  • Patch Record
  • Search Records

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

{
  "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.

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 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 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 PhoneNumber type. The type includes these properties:

Using the Accord PhoneNumber type provides the following benefits:

• It adheres to International Telecommunication Union (ITU) standards. See the type definition 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 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:

{
  "$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 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

  • Create Record
  • Patch Record
  • Search Records

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

{
  "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.

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 for each Docusign account that has the extension app installed.
2. For each workflow that uses the extension app, edit the workflow steps 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 for details on the Workflow Builder setup.

To support this feature with a 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.

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

@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.
• Get an overview of the connected fields extension.
• Explore the options for testing an extension app.