Create bulk job

Create a new job, give presigned URLs back, the client will upload to Azure Blob Store directly.

Important Upload Workflow:

1. Call this endpoint to create a job and receive upload URLs
2. For each document in the response’s _embedded.documents array, extract the upload_document URL from _actions
3. Upload your document file to each URL using an HTTP PUT request with the document content as binary data
4. After all documents are uploaded, call the /actions/complete endpoint to finalize the job
5. Use the GET endpoint to monitor job progress

Example response structure:

{
  "_embedded": {
    "documents": [
      {
        "id": "8c566d26-e7fb-4b7e-870c-1d0fb8df9084",
        "sequence": 1,
        "_actions": {
          "upload_document": "https://docupstoragewestwu3dsto.blob.core.windows.net/..."
        }
      }
    ]
  }
}

Azure Blob Storage Upload Instructions:

Use the pre-signed URL from step 2 to upload your document directly to Azure Blob Storage:

PUT [pre-signed URL from _actions.upload_document]
Headers:
x-ms-blob-type: BlockBlob (Required)
x-ms-meta-filename: YourDocumentName.pdf (Recommended)
Content-Type: application/pdf (Required)
x-ms-meta-metadata: <stringified JSON metadata> (Optional)
Body: [Your document binary data]

Important Notes:

• The upload_document URLs are pre-signed Azure Blob Storage URLs with time-limited validity (8 hours)
• No Auth header is needed
• The x-ms-meta-filename header should contain your original document filename
• The x-ms-blob-type must be set to BlockBlob
• Setting the Content-Type header is recommended to match your document type
• If Content-Type is not specified, Azure defaults to application/octet-stream
• The x-ms-meta-metadata header is optional and allows you to attach metadata to the newly created agreement at upload time. See Applying Metadata to Agreements below for details

Applying Metadata to Agreements:

You may include metadata alongside the document bytes during upload. This metadata will be directly applied to the newly created agreement. To do this, include the x-ms-meta-metadata header on the PUT operation with a stringified JSON value.

The JSON schema for this header follows the same structure as the standard Agreement PATCH request body.

Example metadata JSON:

{
  "provisions": {
    "jurisdiction": "California",
    "payment_terms_due_date": "OTHER"
  },
  "custom_provisions": {
    "c_ClientId": "value"
  },
  "linked_data": [
    {
      "application_name": "Salesforce",
      "object_name": "Account",
      "record_id": "579386BF-C8EA-4673-AE0E-E2F922B09DC5"
    },
    {
      "application_name": "Dynamics",
      "object_name": "Account",
      "record_id": "514CEAFB-1AC7-43FF-9E88-24CB15150963"
    }
  ]
}

Stringified header value:

The JSON must be stringified before being set as the header value. For example, the above JSON would become:

x-ms-meta-metadata: "{\"provisions\":{\"jurisdiction\":\"California\",\"payment_terms_due_date\":\"OTHER\"},\"custom_provisions\":{\"c_ClientId\":\"value\"},\"linked_data\":[{\"application_name\":\"Salesforce\",\"object_name\":\"Account\",\"record_id\":\"579386BF-C8EA-4673-AE0E-E2F922B09DC5\"},{\"application_name\":\"Dynamics\",\"object_name\":\"Account\",\"record_id\":\"514CEAFB-1AC7-43FF-9E88-24CB15150963\"}]}"

Metadata Notes:

• The x-ms-meta-metadata header is entirely optional. If omitted, the agreement is created with AI-extracted values only
• The JSON must be stringified (serialized to a single string) before being placed in the header value
• The metadata payload follows the same schema as the Agreement PATCH endpoint request body
• Values provided via metadata will be applied to the agreement after creation, overriding any AI-extracted values for the same fields

Firewall & Network Configuration:

If your organization uses firewalls or network restrictions, you may need to whitelist the following Azure Blob Storage domains to ensure successful document uploads. The upload URLs returned by this API will use one of these domains based on your account’s geographic region:

Primary Storage Endpoints:

• https://docupstorageaustauepsto.blob.core.windows.net/
• https://docupstoragecanacacpsto.blob.core.windows.net/
• https://docupstoragecentcuspsto.blob.core.windows.net/
• https://docupstorageeasteu2psto.blob.core.windows.net/
• https://docupstorageeasteusdsto.blob.core.windows.net/ (Demo)
• https://docupstoragejapajpepsto.blob.core.windows.net/
• https://docupstoragenortneupsto.blob.core.windows.net/
• https://docupstoragewestweupsto.blob.core.windows.net/
• https://docupstoragewestwu3dsto.blob.core.windows.net/ (Demo)

Secondary Storage Endpoints (for redundancy/failover):

• https://docupstorageaustauepsto-secondary.blob.core.windows.net/
• https://docupstoragecanacacpsto-secondary.blob.core.windows.net/
• https://docupstoragecentcuspsto-secondary.blob.core.windows.net/
• https://docupstorageeasteu2psto-secondary.blob.core.windows.net/
• https://docupstorageeasteusdsto-secondary.blob.core.windows.net/ (Demo)
• https://docupstoragejapajpepsto-secondary.blob.core.windows.net/
• https://docupstoragenortneupsto-secondary.blob.core.windows.net/
• https://docupstoragewestweupsto-secondary.blob.core.windows.net/
• https://docupstoragewestwu3dsto-secondary.blob.core.windows.net/ (Demo)

Note: You may whitelist all domains listed above, or contact your DocuSign administrator to determine which specific region(s) your account uses to minimize the whitelist scope.

Supported File Formats & Content Types:

The table below shows common file formats and their recommended Content-Type headers. Note: For the most up-to-date list of supported formats, headers, and constraints, always refer to the _action_templates object in the API response, which provides dynamic configuration including:

• allowed_formats: Current list of supported file extensions
• headers: Required HTTP headers with examples
• constraints: Maximum file size and other limits
• success_status_code: Expected response code for successful uploads

Example Upload Requests:

PDF Document (with optional metadata):

PUT https://storage.blob.core.windows.net/container/doc-id?signature=...
Content-Type: application/pdf
x-ms-blob-type: BlockBlob
x-ms-meta-filename: contract.pdf
x-ms-meta-metadata: "{\"provisions\":{\"jurisdiction\":\"California\"},\"custom_provisions\":{\"c_ClientId\":\"value\"}}"
[Binary PDF data]

Word Document:

PUT https://storage.blob.core.windows.net/container/doc-id?signature=...
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
x-ms-blob-type: BlockBlob
x-ms-meta-filename: agreement.docx
[Binary DOCX data]

Image:

PUT https://storage.blob.core.windows.net/container/doc-id?signature=...
Content-Type: image/jpeg
x-ms-blob-type: BlockBlob
x-ms-meta-filename: signed-page.jpg
[Binary JPEG data]