Bulk ingest agreements in production | Docusign

Bulk ingestion enables you to upload large volumes of agreements into Docusign Agreement Manager so that they can be processed, classified, and made available for AI extraction. Ingestion makes your organization’s contract data available in Agreement Manager for your users to find, report on, and manage obligations.

For a walkthrough of the bulk ingestion process, see this video:

Include metadata with agreements

The Docusign CLI supports including metadata with agreements during ingestion. This option is useful for supplying:

Agreement-specific data that is not present in the agreement text. For example, your organization may associate an ID with each agreement, but the agreement itself does not include the ID.
Values that are required to be associated with all agreements, such as organization or business unit information
Corrections to inaccurate or outdated agreement values. Metadata supplied during bulk ingestion override values in the agreement text. For example, if the contact information in an agreement has changed, you can supply the updated information as metadata.
Associations between ingested agreements and records in an external data source, such as Salesforce. Data source record information can be retrieved using Agreement Manager API requests. See Associate agreements with external data source records for details.

With the Docusign CLI, you can supply metadata during initial agreement ingestion. To update metadata for agreements that already reside in Agreement Manager, use the Agreement Manager UI. See Bulk Metadata Editing for more information.

See Bulk ingest agreements with metadata for details about the Docusign CLI process.

Bulk ingestion prerequisites

Before running a bulk ingestion with the Docusign CLI, make sure that the following prerequisites are met:

You have a Docusign production account with the permissions required to upload agreements to Agreement Manager.
You are authenticated to the production environment. See Authenticate for details.
Your agreements are stored in a directory accessible from your local filesystem or a mounted network drive.

If you are bulk ingesting agreements with metadata, see Bulk ingest agreements with metadata for additional requirements.

Bulk ingest agreements

To bulk ingest agreements, run the following command: $ ds agm ingest [options]

Command options

Option	Description	Default value
`--files <files...>`	One or more specific document files to upload. Multiple files can be specified, separated by spaces.	N/A
`--directory <dirs...>`	One or more directories to scan for supported document files. All matching files in the directory are queued for upload.	N/A
`--recursive`	When used with `--directory`, scans subdirectories recursively.	`false`
`--dry-run`	Displays all files that would be uploaded, including duplicate detection results, without actually uploading anything. Use this to preview an ingest run before committing.	`false`
`--bypass, -y`	Skips the confirmation prompt before uploading.	`false`
`--generate-metadata-template`	Generates a template file in which you supply metadata to associate with ingested agreements. When this option is included, the command does not upload files. See Bulk ingest agreements with metadata for details.	N/A
`--with-metadata`	Initiates a bulk ingestion of agreements along with a metadata file.	N/A

Supported file formats

The following file formats are supported for bulk ingestion via the Docusign CLI:

PDF
Word: DOC, DOCX, RTF
Excel: XLS, XLSX, XLSB
PowerPoint: PPT, PPTX, PPSX
HTML
Images: JPG, PNG, TIF, TIFF

Example commands

These commands upload agreements without additional metadata. To supply metadata with the uploaded files, see Bulk ingest agreements with metadata.

Upload specific files:

$ ds agm ingest --files agreement1.pdf agreement2.pdf

Upload all supported documents in a directory:

$ ds agm ingest --directory ./agreements

Upload documents from a directory and all its subdirectories:

$ ds agm ingest --directory ./agreements --recursive

Preview what would be uploaded without uploading:

$ ds agm ingest --directory ./agreements --dry-run

Bulk ingest agreements with metadata

The bulk ingestion process enables you to supply missing or corrected agreement data along with the uploaded files. You can also identify applicable records in an external data source. See Associate agreements with external data source records for details.

Metadata prerequisites

Any agreement fields for which you will supply metadata must meet the requirements listed below.

Note: These requirements do not apply to metadata that associates agreements with records in an external data source.

The fields must exist in your account, as either standard or custom fields. Use the get catalog command to retrieve standard and custom fields. See Define custom fields for details about adding custom fields.
The fields must be associated with the standard agreement type Miscellaneous. If any metadata field is not associated with this agreement type, the Docusign CLI will display a validation error when you launch an ingestion. See Extend standard agreement types for steps to add fields to a standard agreement type.
If you will always use metadata to populate a field instead of AI extraction, set the field’s customExtractionEnabled property to false in the manifest. See Manifest reference for more information.

Steps to bulk ingest agreements with metadata

To bulk ingest agreements with metadata:

Run this command to generate a template file for the metadata:
ds agm ingest --directory <directory path> --generate-metadata-template
For the --directory option, supply the directory that contains the files to be ingested.

This command does not ingest files. It creates a metadata template CSV file at {workspaceName}/{projectName}/agreement-manager/metadata/metadata.csv
The template file contains a row for each file to be ingested and columns for every standard and custom field defined in your account.
Populate the CSV file with the metadata values that you want to associate with each agreement. If metadata is not being supplied, you can either leave the fields blank or delete the columns. If you supply metadata for a field that has customExtractionEnabled set to true in the manifest, the metadata value will override the AI-extracted value for the field.

The next section explains how to add external data source record information to the CSV file.
Run this command to bulk ingest the files, along with the metadata that you supplied in the CSV file:
ds agm ingest --directory files/bulk-ingest --with-metadata
The Docusign CLI validates the CSV file and agreements, uploads the files, and applies the metadata.

Associate agreements with external data source records

To associate agreements with records in an external data source, add a linked_data column to metadata.csv. For each agreement to be associated with data source records, populate the linked_data column with a JSON array in the format shown below. Each array element represents a data source record. In this example, an agreement is associated with records in three Fontara Data Source objects: Account, Contact, and Payment.

[
  {
    "application_name": "Fontara Data Source",
    "object_name": "Account",
    "record_id": "342"
  },
  {
    "application_name": "Fontara Data Source",
    "object_name": "Contact",
    "record_id": "85"
  },
  {
    "application_name": "Fontara Data Source",
    "object_name": "Payment",
    "record_id": "4810"
  }
]

The JSON array element properties are described below.

Property	Description	Type	Required
`application_name`	A name for the external data source.	String	Yes
`object_name`	The data source object that contains the record associated with the agreement.	String	Yes
`record_id`	The ID of the record associated with the agreement.	String	Yes

These behaviors and restrictions apply to data source record metadata:

The CLI accepts any string value for the application name, object name, and record ID and does not perform any validation based on the values. For example, the CLI does not check whether the supplied objects and record IDs exist in the data source.
The data source record array must be in valid JSON format.
The array can contain up to 10 elements.
You are not required to populate the linked_data column in metadata.csv for every agreement that’s being ingested.
You can add the linked_data column at any position in metadata.csv.

These Agreement Manager API requests can be used to retrieve data source record metadata for ingested agreements:

Note: You must supply the include_linked_data query parameter with these requests in order to return the data source record metadata.

Metadata validation errors

Validation errors will occur when you initiate a bulk ingestion with metadata under any of these conditions:

You included the --with-metadata option, but no metadata CSV file was found.
One or more file names listed in the CSV file could not be found in the specified bulk ingestion directory.
One or more field names in the CSV file do not exist in the account.
One or more custom field names in the CSV file are not associated with the Miscellaneous standard agreement type.
One or more values in the CSV file are not of the correct data type. For example, a number field contains a string value.

Duplicate detection

The CLI automatically detects and skips files that have already been uploaded, preventing duplicate agreements from being ingested. Before each ingest run, the CLI computes a hash for each file and checks it against a local tracking file that records the hash and filename of every agreement that has been successfully uploaded. Files identified as duplicates are listed as [DUPLICATE] in the pre-upload summary and are automatically excluded from the upload.

Duplicate detection applies only to files uploaded from the same machine and account. If you run the ingest command from a different machine, or authenticate with a different account, the CLI will not recognize previously uploaded files as duplicates and may reingest them.

Bulk ingestion results

After a successful ingest run, the CLI displays an upload summary in the command-line interface.

The summary fields are defined as follows:

Field	Description
Total Agreements Scanned	Total number of files discovered across all specified sources.
Duplicates Skipped	Number of files skipped because they were previously uploaded from this machine and account.
New Agreements	Number of files queued for upload after duplicate filtering.
Successful	Number of files successfully uploaded to Agreement Manager.
Failed	Number of files that failed to upload. This field is only shown if one or more failures occurred.
Job ID	The Agreement Manager job ID associated with this ingest batch.
Job Status	The final status of the ingest job returned by Agreement Manager.

After ingestion, Agreement Manager processes the uploaded agreements and runs AI extraction on them. See Processing Agreements for information about processing time. Once processing is complete, the agreements and their extracted field values are available in the Agreement Manager UI.

Other upload methods

In addition to the Docusign CLI, Docusign provides two other methods for uploading agreements. See the table below for a comparison.

Method	Best for	Supported file volume
Docusign CLI	Uploading large volumes of agreements stored in a local or network directory.	More than 100,000 files. The exact upper limit depends on your network bandwidth, filesystem performance, timeout limits, and other environment factors.
Agreement Manager API	Integrating ingestion into your own pipelines or automating uploads as part of a larger workflow.	Approximately 10,000 files per job. Uses presigned Azure URLs, allowing files to be uploaded in parallel directly from your own pipeline for faster throughput.
Agreement Manager UI	Smaller, one-time uploads or for users who prefer a guided experience.	1,000 files per bulk upload job.

Frequently asked questions

Can I ingest agreements from a network drive?

Yes. The CLI supports any directory accessible via a filepath in your terminal, including local directories and network drives mounted to your local filesystem. Cloud storage directories, such as SharePoint and Google Drive, are supported if they are mounted and accessible as a local filesystem path.

What happens if some files fail to upload?

The CLI reports the number of failed files in the upload summary. Successfully uploaded files are still ingested even if some files in the batch fail. You can rerun the ingest command for the same directory. The CLI will skip files that were already successfully uploaded (from the same machine and account) and retry only the files that have not yet been ingested.

Is there a maximum number of files I can ingest in a single run?

The Docusign CLI supports ingestion of more than 100,000 files. The practical upper limit depends on factors specific to your environment, including network bandwidth, filesystem performance, and timeout configurations. For very large ingestions, consider splitting files across multiple directories and running the ingest command separately for each one.

Will rerunning the ingest command on the same directory reupload already ingested files?

No, as long as you are running the command from the same machine and using the same Docusign account. The CLI’s duplicate detection mechanism tracks successfully uploaded files by hash and filename, and automatically skips them on subsequent runs. Files uploaded from a different machine or account are not tracked and may be reingested.

Can I supply missing or corrected agreement data during the upload?

Yes. The Docusign CLI supports bulk ingestion with metadata. You can populate missing or corrected agreement data in a CSV file. See Bulk ingest agreements with metadata for details. To supply metadata for agreements that already reside in Agreement Manager, see Bulk Metadata Editing.

Does the CLI support record linkage with Salesforce and other data sources?

Yes. During bulk ingestion, you can supply metadata that associates each agreement with up to 10 records in Salesforce or any other external data source. This metadata can be retrieved via Agreement Manager API calls. See Associate agreements with external data source records for details.

Next steps

Explore the AI tools available to help you build and manage your Agreement Manager configuration more efficiently.
Join the open beta to access new features early and provide feedback to the Docusign team.