Unlock Your Historical Agreements: Navigator API Bulk Ingestion Made Simple

Most organizations have years, sometimes decades, of agreements stored across a patchwork of systems. These documents contain critical information about renewals, obligations, parties, and terms, yet they remain largely invisible to core business processes..

Docusign Navigator, a smart repository that centralizes and analyzes agreements, automatically ingests newly completed agreements, but what about the thousands, or millions, of historical documents that came before Navigator was in place? Manually uploading that volume through a UI is impossible. If your contracts are sitting in SharePoint, Google Drive, or scattered across legacy systems, the solution is simple: the Navigator API's bulk ingestion. It provides a straightforward, programmatic path to consolidate all your historical agreements into one intelligent repository. 

Let’s explore how to make that happen.

Before We Begin: Prerequisites

You will need to authenticate your application to access the Navigator API (currently in Limited Availability).

Prerequisites:

• Valid access token with the required scopes

• Navigator enabled on your account

• Developer account for testing (that also has Navigator API enabled)

Access: The Navigator API is currently in limited availability (LA), with general availability planned for early 2026. Request access through the Intelligent Agreement Management (IAM) or contact your Docusign account team.

Once you have completed these prerequisites, you are able to proceed to the next steps. 

How Bulk Ingestion Works

Navigator API provides a simple three-step process for uploading documents at scale. Here are the three steps:

Step 1: Create a Bulk Job

First, create a job to handle your document uploads using this endpoint:

POST https://api-d.docusign.com/v1/accounts/{accountId}/upload/jobs

{
  "job_name": "Q4 Contract Migration",
  "expected_number_of_docs": 100,
  "language": "en-US"
}

Note: The examples use the developer environment base URL (https://api-d.docusign.com). For production, use https://api.docusign.com.

The API returns a job ID along with pre-signed Azure Storage URLs  (_embedded -> documents[i] -> actions -> upload_document) for each document you want to upload. These URLs are valid for eight hours, giving you plenty of time to complete your uploads.

{
    "id": "bcf7fda5-059e-4019-bb22-xxxxxxxxx",
    "name": "test_name",
    "status": "PENDING",
    "status_enum": [
        "PENDING",
        "PROCESSING",
        "SUCCEEDED",
        "PARTIAL_SUCCESS",
        "FAILED",
        "CANCELLED"
    ],
    "created_at": "2025-11-19T18:27:31.243409641Z",
    "modified_at": "2025-11-19T18:27:31.243409741Z",
    "expires_at": "2025-11-22T18:27:31.243409641Z",
    "ttl_period": "P3D",
    "_embedded": {
        "documents": [
            {
                "id": "0cb93e96-xxxx-xxxx-xxxx-a6ade0c81812",
                "sequence": 1,
                "_actions": {
                    "upload_document": "https://docupstoragewestwu3dsto.blob.core.windows.net/bcf7fda5-059e-4019-bb22-xxxxxxxxxx/0cb93e96-37f4-45a6-bd43-xxxxxxxxx?sv=2023-01-03&st=2025-11-19T18%3A22%3A31Z&se=2025-11-20T02%3A27%3A31Z&skoid=f276d6bb-faf6-4ace-90ee-13766f8391ad&sktid=791313ac-cd3f-48b0-8501-2ac69aec78e9&skt=2025-11-18T17%3A39%3A44Z&ske=2025-11-25T17%3A44%3A44Z&sks=b&skv=2023-01-03&sr=b&sp=cw&sig=ez3k%2Ft3nCFamwlX%2F4NF5cEthGhwfV7KclkQqrlC%2BzRo%3D"
                }
            }
        ]
    },
    "_action_templates": {
        "upload_document": {
            "method": "PUT",
            "required": true,
            "description": "Upload the document binary content",
            "template_variables": {
                "document_name": "Client-provided filename, used in x-ms-meta-filename header"
            },
            "headers": {
                "x-ms-blob-type": "BlockBlob",
                "x-ms-meta-filename": "lease_agreement.pdf"
            },
            "constraints": {
                "max_size_mb": 100,
                "allowed_formats": [
                    "pdf",
                    "docx",
                    "txt"
                     ...
                ],
                "timeout_seconds": 300
            },
            "success_status_code": 200
        }
    },
    "constraints": {
        "max_documents_per_job": 10000
    },
    "metadata": {
        "response_timestamp": "2025-11-19T18:27:31.349059774Z",
        "response_duration": 539
    },
    "message": "Files exceeding 100MB or more than 10,000 per job will be rejected."
}

Important to know:

• Each job can handle up to 10,000 documents

• Each document can be up to 100MB (we're planning to increase these limits in the future)

• Supported formats: PDF, DOC, DOCX, PPS, PPSX, PPT, PPTX, RTF, WPD, XLS, XLSX, XLSB, HTML, HTM, JPEG, JPG, PNG, TIF, TIFF

• If you have a firewall or network restrictions, you may need to whitelist the upload URL domains.

Step 2: Upload Your Documents

Here's where it gets interesting. Instead of uploading through Docusign's servers, the documents will be uploaded directly to Azure Blob Storage using the pre-signed URLs. This means faster uploads and gives you complete flexibility in how you batch and manage your uploads.

Note: It is ok to not use all the URL’s to upload, we will pick up only the uploaded ones automatically when the upload complete signal (explained in next section) is received.

For each document, use a simple PUT request (or you can write code using Azure Blog Storage APIs and SDKs in your favorite language):

curl --location --request PUT 'https://docupstoragecentcuspsto.blob.core.windows.net/d832c0a0-1721-4724-86f3-xxxxxxx/5e71a067-c867-4a10-9760-xxxxxx?sv=2023-01-03&st=2025-11-24T17%3A39%3A30Z&se=2025-11-25T01%3A44%3A30Z&skoid=5f921de9-cf48-410c-8062-xxxxxxxxx&sktid=791313ac-cd3f-48b0-8501-2ac69aec78e9&skt=2025-11-24T17%3A39%3A30Z&ske=2025-12-01T17%3A44%3A30Z&sks=b&skv=2023-01-03&sr=b&sp=cw&sig=xxxxxxxx%xxxxxx%3D' \
--header 'x-ms-blob-type: BlockBlob' \
--header 'x-ms-meta-filename: yourfilename' \
--header 'Content-Type: application/pdf' \
--data-binary '@/user/documents/doc.pdf'

Important: Setting Content-Type

Azure recommends setting the Content-Type header to match your document type. If not specified, Azure defaults to Content-Type: application/octet-stream. While this works, setting the correct content type helps ensure your documents are handled and identified properly.

Here’s a list of content types for the supported document formats:

// PDF
Content-Type: application/pdf

// Word document
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document  //
Content-Type: application/msword  // .doc

// PPT
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation  // .PPTX
Content-Type: application/vnd.ms-powerpoint  // .ppt
Content-Type:application/vnd.openxmlformats-officedocument.presentationml.slideshow

// XLS
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet  // XSLX
Content-Type: application/vnd.ms-excel  // .xls
Content-Type: application/vnd.ms-excel.sheet.binary.macroenabled.12


// Images
Content-Type: image/jpeg  // .jpg, .jpeg
Content-Type: image/png   // .png
Content-Type: image/tiff  // .tif, .tiff

// Other formats
Content-Type: text/html  // .html, .htm
Content-Type: text/rtf   // .rtf

You can upload documents in parallel, use your own retry logic, or integrate with your existing file processing pipelines. The Navigator API allows you to manage uploads in a way that best fits your infrastructure.

Step 3: Mark the Job Complete

Once all your documents are uploaded, signal Navigator to begin processing: This complete api call tells Navigator you've finished uploading and it should start AI extraction on this job.

POST /v1/accounts/{accountId}/upload/jobs/{jobId}/actions/complete

That's it! Navigator's AI engine kicks in and begins extracting valuable metadata from your documents.

Track Your Job Status

Want to know how your upload is progressing? The status endpoint gives you real-time updates:

GET /v1/accounts/{accountId}/upload/jobs/{jobId}

This endpoint returns detailed status information, showing which documents have been processed, which are in progress, and if any have failed. The possible job statuses are:

• PENDING - Job has been created and is waiting for uploads

• PROCESSING - Documents are being ingested and analyzed

• SUCCEEDED - All the documents have been processed successfully

• PARTIAL_SUCCESS - Some documents were successfully processed, and others have failed

• FAILED - Job has failed to process

• CANCELLED - Job was cancelled

Each document within the job also has its own status tracking, so you know exactly what's happening with every file.

You can also track job progress in the Navigator UI at Navigator Document Uploader, providing your users with a visual method to track large uploads.

What Happens After Upload

Once your documents are in Navigator, the real magic begins. Navigator's AI automatically analyzes each agreement and extracts:

Agreement Details:

• Document type (MSA, NDA, Amendment, etc.)

• Parties involved

• Key dates (effective date, expiration, execution)

• Financial terms

• Renewal information

Extracted Provisions:

• Assignment clauses

• Termination terms

• Payment terms

• Liability caps

• Jurisdiction

• And much more...

Here's an example response body when you retrieve an agreement:

GET /v1/accounts/{accountId}/agreements/{agreementId}

{
  "id": "48e593bd-73e8-455f-92e7-xxxxxxxxxx",
  "type": "Addendum agreement",
  "parties": [
    {
      "name_in_agreement": "ACME, INC"
    },
    {
      "name_in_agreement": "TALLY, LTD"
    }
  ],
  "provisions": {
    "effective_date": "2024-09-01",
    "expiration_date": "2029-09-01",
    "total_agreement_value": 150000,
    "total_agreement_value_currency_code": "USD",
    "jurisdiction": "California",
    "renewal_type": "AUTO_RENEW",
    "renewal_notice_date": "2024-10-17",
    "termination_period_for_cause": "P1Y"
  }
}

All the data is automatically extracted by Navigator's AI. You don't have to do anything except upload the documents.

Real-World Example: Legacy Contract Migration

Here’s an example of a common scenario. A customer had thousands of contracts spread across multiple SharePoint sites from the past five years. Their legal team needed to track upcoming renewals but had no easy way to see which agreements were coming up for renewal.

Using the Navigator API, they:

1. Discovered all contract PDFs in SharePoint using Microsoft Graph API

2. Created bulk jobs of up to 10,000 documents each

3. Uploaded documents directly using the secured pre-signed URLs

4. Monitored job status through the Navigator API

Within days, all their historical agreements were in Navigator with AI-extracted metadata. The legal team could now go to the "Completed" section of Docusign Navigator agreement dashboard to: https://apps-d.docusign.com/send/navigator 

• Search for any agreement in seconds

• Get automatic renewal notifications

• Track all agreements with specific parties

• Generate compliance reports instantly

Conclusion

Whether you're migrating a few thousand documents or millions of agreements, the Navigator API's bulk ingestion capabilities let you consolidate all your historical agreements into a single, intelligent repository.

We're continuously improving the bulk ingestion capabilities. Here's what's coming soon::

• Higher document-size limits per job

• Tag agreement sets to your ingestion job

• Ingest custom attributes during or after the upload

• SDK support for easier integration

• Bulk update operations

Ready to start building? Head over to the Docusign Developer Center to learn more and sign up for a free developer account. Join the Docusign Developer Community to share feedback, get support and to connect with other developers. Lastly, check out our roadmap on GitHub to see what we're building next. 

Additional Resources

• Explore the full Navigator API Reference and Bulk Job documentation for endpoint schemas and specifications.

• Discover the complete capabilities of Docusign Navigator.

• Join the Navigator API Community Forum to ask questions and share feedback.