Skip to navigation
Concepts

Bulk upload agreements

View as Markdown

Bulk Upload enables developers to programmatically upload many agreements into the Agreement manager at the same time, triggering AI extraction where applicable on your uploaded documents or applying your supplied metadata directly.

Agreement manager bulk upload works by generating upload URLs as part of a bulk job and passing them back to your app. Your app then uploads one document to each upload URL and, when all of your documents are uploaded, calls an endpoint to signal completion. This removes the overhead of proxying large files and enables you to easily and painlessly mass-onboard legacy documents, such as old contracts from disparate systems, split between different file formats and organization systems.

Bulk upload use cases

Bulk upload enables you to migrate large numbers of legacy agreements into one place for management. Bulk upload legacy contracts from disparate systems such as your on-premises storage, SharePoint, Google Drive, or Dropbox into the Agreement Management platform.

You can use AI extraction to order and apply metadata to these documents, or upload documents alongside structured metadata such as custom field values, record IDs, or tags, to skip AI extraction overhead and maintain data fidelity.

For example, a bank with contracts going back years or decades, in many different formats, from many different regions, wants to standardize their documents and manage them from one place. Bulk upload is the mechanism by which the masses of these documents can be added to Agreement Manager for ingestion, sorting, and categorization.

How bulk upload works

You can create bulk upload jobs for documents using the following steps:

1. Create a bulk upload job

Call the POST /v1/accounts/{accountId}/upload/jobs endpoint to create a job, providing a name, language, and the number of docs to be uploaded.

The response includes a job ID and pre-signed blob storage URLs for each document, which are valid for 8 hours.

The document_uploader_write and document_uploader_read scopes are required for performing bulk upload tasks with the API. The adm_store_unified_repo_read is also required for tasks that involve reading agreement records.

curl --location \
  'https://api-d.docusign.com/v1/accounts/08b4799a-xxxx-xxxx-xxxx-b5b4b8a97604/upload/jobs' \
  --header 'Authorization: Bearer eyJ…1UA' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "job_name": "Q4 Contract Migration",
    "expected_number_of_docs": 3,
    "language": "en-US",
    "agreement_set_ids": [
      "-8c-dVtBzjSe7nh_zAf9L"
    ]
  }'

2. Upload documents to pre-signed URLs

For each document URL in the _embedded.documents array, make an HTTP PUT request providing the binary file content. The required headers for these calls are:

  • x-ms-blob-type: BlockBlob: Required.
  • x-ms-meta-filename: YourDocumentName.pdf: Recommended. Defaults to your document ID if omitted.
  • Content-Type: The appropriate MIME type for your file. Required.

Documents can be uploaded in parallel, with your own retry logic, and integrated into existing file processing pipelines.

You can also add a metadata header alongside each document to be uploaded. When metadata is provided, the platform skips the AI extraction step for that document since the metadata already exists. This metadata must be provided in JSON format via the API (CSV-based metadata is a UI-only feature).

Supported file formats for bulk upload documents are:

  • .pdf
  • .docx
  • .doc
  • .pptx
  • .txt
  • .html
  • .htm
  • .rtf
  • .jpg or .jpeg
  • .png
  • .tiff or .tif
  • .eml
  • .zip

For the authoritative list of supported formats, size limits, and headers, always refer to the allowed_formats and headers in the _action_templates section of the createBulkUploadJob response.

{
   "provisions":{
      "jurisdiction":"California"
   },
   "custom_provisions":{
      "c_ClientId":{
         "value":"12345"
      }
   }
}

3. Mark the job complete

Once all of the documents have been uploaded, make a POST /v1/accounts/{accountId}/upload/jobs/{jobId}/actions/complete call to mark the job complete, triggering ingestion of the documents and AI extraction.

curl --location \
  'https://api-d.docusign.com/v1/accounts/08b4799a-xxxx-xxxx-xxxx-b5b4b8a97604/upload/jobs/c5f018e6-xxxx-xxxx-xxxx-539c6f505a95/actions/complete' \
  --request POST \
  --header 'Authorization: Bearer eyJ…1UA' \
  --header 'Content-Type: application/json'

Bulk upload rules and rate limits

ConstraintDescription
Maximum documents per job10,000 documents. For uploads exceeding 10,000 documents, you must use multiple bulk upload jobs.
Maximum file size500 MB per file.
AI extraction file size limit190 MB (up to 300 pages).
Pre-signed URL validity8 hours.
Bulk upload job lifespanA job will expire after 3 days.

Next steps