> 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 # Bulk ingest agreements in production > Learn how to bulk ingest agreements into Agreement Manager using the Docusign CLI. Compare ingestion methods, understand duplicate detection, learn how to include metadata, and review ingestion results. Bulk ingestion enables you to upload large volumes of agreements into [Docusign Agreement Manager](https://www.docusign.com/products/platform/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](/docusign-cli/bulk-ingest-agreements#associate-agreements-with-external-data-source-records) for details. > **Note** > > 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](https://support.docusign.com/s/document-item?bundleId=pqz1702943441912\&topicId=concb493b18-adf8-4fe5-8b99-dd90cbc28399.html) for more information. See [Bulk ingest agreements with metadata](/docusign-cli/bulk-ingest-agreements#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](/docusign-cli/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](/docusign-cli/bulk-ingest-agreements#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 ` | One or more specific document files to upload. Multiple files can be specified, separated by spaces. | N/A | | `--directory ` | 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](/docusign-cli/bulk-ingest-agreements#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](/docusign-cli/bulk-ingest-agreements#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](/docusign-cli/bulk-ingest-agreements#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](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs#retrieve-current-configuration) command to retrieve standard and custom fields. See [Define custom fields](/docusign-cli/configure-agreement-types-and-fields/manifest-reference#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](/docusign-cli/configure-agreement-types-and-fields/manifest-reference#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](/docusign-cli/configure-agreement-types-and-fields/manifest-reference) for more information. ### Steps to bulk ingest agreements with metadata To bulk ingest agreements with metadata: 1. Run this command to generate a template file for the metadata: \ `ds agm ingest --directory --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. 2. 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. 3. 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. ```text [ { "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](/docs/agreement-manager-api) requests can be used to retrieve data source record metadata for ingested agreements: * [Agreements:getAgreement](/docs/agreement-manager-api/reference/agreementmanager/agreements/getagreement) * [Agreements:getAgreementsList](/docs/agreement-manager-api/reference/agreementmanager/agreements/getagreementslist) **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. > **Note** > > 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](https://support.docusign.com/s/document-item?bundleId=pqz1702943441912\&topicId=rvw1736364838500.html) 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](/docs/agreement-manager-api/reference/agreementmanager/bulkjob/createbulkuploadjob) | 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](https://support.docusign.com/s/document-item?bundleId=pqz1702943441912\&topicId=leq1712700300298.html) | 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](/docusign-cli/bulk-ingest-agreements#bulk-ingest-agreements-with-metadata) for details. To supply metadata for agreements that already reside in Agreement Manager, see [Bulk Metadata Editing](https://support.docusign.com/s/document-item?bundleId=pqz1702943441912\&topicId=concb493b18-adf8-4fe5-8b99-dd90cbc28399.html). ### 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](/docs/agreement-manager-api) calls. See [Associate agreements with external data source records](/docusign-cli/bulk-ingest-agreements#associate-agreements-with-external-data-source-records) for details. ## Next steps * Explore the [AI tools](/docusign-cli/ai-tools) available to help you build and manage your Agreement Manager configuration more efficiently. * [Join the open beta](/docusign-cli/open-beta) to access new features early and provide feedback to the Docusign team.